You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by bo...@apache.org on 2009/09/04 10:02:49 UTC
svn commit: r811240 - in
/ant/core/trunk/src/main/org/apache/tools/ant/property:
ParseNextProperty.java ParseProperties.java PropertyExpander.java
Author: bodewig
Date: Fri Sep 4 08:02:49 2009
New Revision: 811240
URL: http://svn.apache.org/viewvc?rev=811240&view=rev
Log:
document PropertyExpander and helpers, some minor optimizations in ParseProperties
Modified:
ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java
ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java
ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java
Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java
URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java?rev=811240&r1=811239&r2=811240&view=diff
==============================================================================
--- ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java (original)
+++ ant/core/trunk/src/main/org/apache/tools/ant/property/ParseNextProperty.java Fri Sep 4 08:02:49 2009
@@ -22,7 +22,8 @@
import org.apache.tools.ant.Project;
/**
- * Interface to parse a property.
+ * Helper for {@link PropertyExpander PropertyExpander} that can be
+ * used to expand property references to values.
* @since Ant 1.8.0
*/
public interface ParseNextProperty {
Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java
URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java?rev=811240&r1=811239&r2=811240&view=diff
==============================================================================
--- ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java (original)
+++ ant/core/trunk/src/main/org/apache/tools/ant/property/ParseProperties.java Fri Sep 4 08:02:49 2009
@@ -24,6 +24,7 @@
/**
* Parse properties using a collection of expanders.
+ *
* @since Ant 1.8.0
*/
public class ParseProperties implements ParseNextProperty {
@@ -53,9 +54,33 @@
}
/**
- * Decode properties from a String representation. If the entire
- * contents of the String resolve to a single property, that value
- * is returned. Otherwise a String is returned.
+ * Decode properties from a String representation.
+ *
+ * <ul>
+ *
+ * <li>This implementation starts parsing the <code>value</code>
+ * parameter (unsurprisingly) at the beginning and asks each
+ * {@link org.apache.tools.ant.PropertyHelper.PropertyExpander
+ * PropertyExpander} whether there is a property reference at
+ * that point. PropertyExpanders return the name of a property
+ * they may find and may advance the parse position.</li>
+ *
+ * <li>If the PropertyExpander returns <code>null</code> the
+ * method continues with the next PropertyExpander, otherwise it
+ * tries to look up the property's value using the configured
+ * {@link GetProperty GetProperty} instance.</li>
+ *
+ * <li>Once all PropertyExpanders have been consulted, the parse
+ * position is advanced by one character and the process repeated
+ * until <code>value</code> is exhausted.</li>
+ *
+ * </ul>
+ *
+ * <p>If the entire contents of <code>value</code> resolves to a
+ * single property, the looked up property value is returned.
+ * Otherwise a String is returned that concatenates the
+ * non-property parts of <code>value</code> and the expanded
+ * values of the properties that have been found.</p>
*
* @param value The string to be scanned for property references.
* May be <code>null</code>, in which case this
@@ -68,19 +93,20 @@
if (value == null || "".equals(value)) {
return value;
}
+ final int len = value.length();
ParsePosition pos = new ParsePosition(0);
Object o = parseNextProperty(value, pos);
- if (o != null && pos.getIndex() == value.length()) {
+ if (o != null && pos.getIndex() >= len) {
return o;
}
- StringBuffer sb = new StringBuffer(value.length() * 2);
+ StringBuffer sb = new StringBuffer(len * 2);
if (o == null) {
sb.append(value.charAt(pos.getIndex()));
pos.setIndex(pos.getIndex() + 1);
} else {
sb.append(o);
}
- while (pos.getIndex() < value.length()) {
+ while (pos.getIndex() < len) {
o = parseNextProperty(value, pos);
if (o == null) {
sb.append(value.charAt(pos.getIndex()));
@@ -94,6 +120,12 @@
/**
* Learn whether a String contains replaceable properties.
+ *
+ * <p>Uses the configured {@link
+ * org.apache.tools.ant.PropertyHelper.PropertyExpander
+ * PropertyExpanders} and scans through the string. Returns true
+ * as soon as any expander finds a property.</p>
+ *
* @param value the String to check.
* @return <code>true</code> if <code>value</code> contains property notation.
*/
@@ -101,7 +133,8 @@
if (value == null) {
return false;
}
- for (ParsePosition pos = new ParsePosition(0); pos.getIndex() < value.length();) {
+ final int len = value.length();
+ for (ParsePosition pos = new ParsePosition(0); pos.getIndex() < len;) {
if (parsePropertyName(value, pos) != null) {
return true;
}
@@ -113,12 +146,28 @@
/**
* Return any property that can be parsed from the specified position
* in the specified String.
+ *
+ * <p>Uses the configured {@link
+ * org.apache.tools.ant.PropertyHelper.PropertyExpander
+ * PropertyExpanders} and {@link GetProperty GetProperty}
+ * instance .</p>
+ *
* @param value String to parse
* @param pos ParsePosition
- * @return Object or null if no property is at the current location.
+ * @return Object or null if no property is at the current
+ * location. If a property reference has been found but the
+ * property doesn't expand to a value, the property's name is
+ * returned.
*/
public Object parseNextProperty(String value, ParsePosition pos) {
- int start = pos.getIndex();
+ final int start = pos.getIndex();
+
+ if (start > value.length()) {
+ // early exit, can't find any property here, no need to
+ // consult all the delegates.
+ return null;
+ }
+
String propertyName = parsePropertyName(value, pos);
if (propertyName != null) {
Object result = getProperty(propertyName);
Modified: ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java
URL: http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java?rev=811240&r1=811239&r2=811240&view=diff
==============================================================================
--- ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java (original)
+++ ant/core/trunk/src/main/org/apache/tools/ant/property/PropertyExpander.java Fri Sep 4 08:02:49 2009
@@ -22,17 +22,30 @@
import java.text.ParsePosition;
/**
- * Interface to a class (normally PropertyHelper) to get a property.
+ * Responsible for locating a property reference inside a String.
* @since Ant 1.8.0
*/
public interface PropertyExpander extends PropertyHelper.Delegate {
+
/**
- * Parse the next property name.
+ * Determine whether there is a property reference at the current
+ * ParsePosition and return its name (or null if there is none).
+ *
+ * <p>Implementations should advance the ParsePosition to the last
+ * character that makes up the property reference. E.g. the
+ * default implementation would return <code>"foo"</code> for
+ * <code>${foo}</code> and advance the ParsePosition to the
+ * <code>}</code> character.</p>
+ *
* @param s the String to parse.
- * @param pos the ParsePosition in use.
- * @param parseNextProperty parse next property
- * @return parsed String if any, else <code>null</code>.
+ * @param pos the ParsePosition in use, the location is expected
+ * to be modified if a property reference has been found (and may
+ * even be modified if no reference has been found).
+ * @param parseNextProperty provides access to the Project and may
+ * be used to look up property values.
+ * @return property name if any, else <code>null</code>.
*/
- String parsePropertyName(String s, ParsePosition pos, ParseNextProperty parseNextProperty);
+ String parsePropertyName(String s, ParsePosition pos,
+ ParseNextProperty parseNextProperty);
}