Author: bodewig
Date: Fri Sep 4 09:26:43 2009
New Revision: 811318
URL: http://svn.apache.org/viewvc?rev=811318&view=rev
Log:
method level Javadocs for PropertyHelper
Modified:
ant/core/trunk/src/main/org/apache/tools/ant/ProjectHelper.java
ant/core/trunk/src/main/org/apache/tools/ant/PropertyHelper.java
Modified: ant/core/trunk/src/main/org/apache/tools/ant/ProjectHelper.java
URL:
http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/ProjectHelper.java?rev=811318&r1=811317&r2=811318&view=diff
==============================================================================
--- ant/core/trunk/src/main/org/apache/tools/ant/ProjectHelper.java (original)
+++ ant/core/trunk/src/main/org/apache/tools/ant/ProjectHelper.java Fri Sep 4
09:26:43 2009
@@ -495,6 +495,9 @@
* <code>null</code> entries in the first list indicate a property
* reference from the second list.
*
+ * <p>As of Ant 1.8.0 this method is never invoked by any code
+ * inside of Ant itself.</p>
+ *
* @param value Text to parse. Must not be <code>null</code>.
* @param fragments List to add text fragments to.
* Must not be <code>null</code>.
Modified: ant/core/trunk/src/main/org/apache/tools/ant/PropertyHelper.java
URL:
http://svn.apache.org/viewvc/ant/core/trunk/src/main/org/apache/tools/ant/PropertyHelper.java?rev=811318&r1=811317&r2=811318&view=diff
==============================================================================
--- ant/core/trunk/src/main/org/apache/tools/ant/PropertyHelper.java (original)
+++ ant/core/trunk/src/main/org/apache/tools/ant/PropertyHelper.java Fri Sep 4
09:26:43 2009
@@ -172,11 +172,13 @@
// --------------------------------------------------------
private static final PropertyEvaluator TO_STRING = new PropertyEvaluator()
{
- private String prefix = "toString:";
+ private final String PREFIX = "toString:";
+ private final int PREFIX_LEN = PREFIX.length();
+
public Object evaluate(String property, PropertyHelper propertyHelper)
{
Object o = null;
- if (property.startsWith(prefix) && propertyHelper.getProject() !=
null) {
- o =
propertyHelper.getProject().getReference(property.substring(prefix.length()));
+ if (property.startsWith(PREFIX) && propertyHelper.getProject() !=
null) {
+ o =
propertyHelper.getProject().getReference(property.substring(PREFIX_LEN));
}
return o == null ? null : o.toString();
}
@@ -210,7 +212,6 @@
// CheckStyle:LineLengthCheck ON
public String parsePropertyName(
String s, ParsePosition pos, ParseNextProperty notUsed) {
- //System.out.println("parseproperty " + s);
int index = pos.getIndex();
if (s.indexOf("$$", index) == index) {
pos.setIndex(++index);
@@ -317,7 +318,8 @@
}
/**
- * There are 2 ways to hook into property handling:
+ * Prior to Ant 1.8.0 there have been 2 ways to hook into property
handling:
+ *
* - you can replace the main PropertyHelper. The replacement is required
* to support the same semantics (of course :-)
*
@@ -325,8 +327,11 @@
* Again, you are required to respect the immutability semantics (at
* least for non-dynamic properties)
*
+ * <p>As of Ant 1.8.0 this method is never invoked by any code
+ * inside of Ant itself.</p>
+ *
* @param next the next property helper in the chain.
- * @deprecated
+ * @deprecated use the delegate mechanism instead
*/
public void setNext(PropertyHelper next) {
this.next = next;
@@ -335,8 +340,13 @@
/**
* Get the next property helper in the chain.
*
+ * <p>As of Ant 1.8.0 this method is never invoked by any code
+ * inside of Ant itself except the {...@link #setPropertyHook
+ * setPropertyHook} and {...@link #getPropertyHook getPropertyHook}
+ * methods in this class.</p>
+ *
* @return the next property helper.
- * @deprecated
+ * @deprecated use the delegate mechanism instead
*/
public PropertyHelper getNext() {
return next;
@@ -366,7 +376,8 @@
}
/**
- * Get the expanders.
+ * Get the {...@link PropertyExpander expanders}.
+ * @since Ant 1.8.0
* @return the expanders.
*/
public Collection getExpanders() {
@@ -378,12 +389,14 @@
/**
* Sets a property. Any existing property of the same name
- * is overwritten, unless it is a user property. Will be called
- * from setProperty().
+ * is overwritten, unless it is a user property.
*
* If all helpers return false, the property will be saved in
* the default properties table by setProperty.
*
+ * <p>As of Ant 1.8.0 this method is never invoked by any code
+ * inside of Ant itself.</p>
+ *
* @param ns The namespace that the property is in (currently
* not used.
* @param name The name of property to set.
@@ -416,6 +429,9 @@
* Get a property. If all hooks return null, the default
* tables will be used.
*
+ * <p>As of Ant 1.8.0 this method is never invoked by any code
+ * inside of Ant itself.</p>
+ *
* @param ns namespace of the sought property.
* @param name name of the sought property.
* @param user True if this is a user property.
@@ -451,7 +467,12 @@
* <code>null</code> entries in the first list indicate a property
* reference from the second list.
*
- * It can be overridden with a more efficient or customized version.
+ * <p>Delegates to {...@link #parsePropertyStringDefault
+ * parsePropertyStringDefault}.</p>
+ *
+ * <p>As of Ant 1.8.0 this method is never invoked by any code
+ * inside of Ant itself except {ProjectHelper#parsePropertyString
+ * ProjectHelper.parsePropertyString}.</p>
*
* @param value Text to parse. Must not be <code>null</code>.
* @param fragments List to add text fragments to.
@@ -462,7 +483,7 @@
* @exception BuildException if the string contains an opening
* <code>${</code> without a closing
* <code>}</code>
- * @deprecated We can do better than this.
+ * @deprecated use the other mechanisms of this class instead
*/
public void parsePropertyString(String value, Vector fragments,
Vector propertyRefs) throws BuildException
{
@@ -473,6 +494,9 @@
* Replaces <code>${xxx}</code> style constructions in the given value
* with the string value of the corresponding data types.
*
+ * <p>Delegates to the one-arg version, completely ignoring the ns
+ * and keys parameters.</p>
+ *
* @param ns The namespace for the property.
* @param value The string to be scanned for property references.
* May be <code>null</code>, in which case this
@@ -548,6 +572,10 @@
* Default implementation of setProperty. Will be called from Project.
* This is the original 1.5 implementation, with calls to the hook
* added.
+ *
+ * <p>Delegates to the three-arg version, completely ignoring the
+ * ns parameter.</p>
+ *
* @param ns The namespace for the property (currently not used).
* @param name The name of the property.
* @param value The value to set the property to.
@@ -561,8 +589,6 @@
/**
* Default implementation of setProperty. Will be called from Project.
- * This is the original 1.5 implementation, with calls to the hook
- * added.
* @param name The name of the property.
* @param value The value to set the property to.
* @param verbose If this is true output extra log messages.
@@ -603,6 +629,9 @@
* exists already, a message is logged and the method returns with
* no other effect.
*
+ * <p>Delegates to the two-arg version, completely ignoring the
+ * ns parameter.</p>
+ *
* @param ns The namespace for the property (currently not used).
* @param name The name of property to set.
* Must not be <code>null</code>.
@@ -649,6 +678,10 @@
/**
* Sets a user property, which cannot be overwritten by
* set/unset property calls. Any previous value is overwritten.
+ *
+ * <p>Delegates to the two-arg version, completely ignoring the
+ * ns parameter.</p>
+ *
* @param ns The namespace for the property (currently not used).
* @param name The name of property to set.
* Must not be <code>null</code>.
@@ -663,6 +696,9 @@
/**
* Sets a user property, which cannot be overwritten by
* set/unset property calls. Any previous value is overwritten.
+ *
+ * <p>Does <code>not</code> consult any delegates.</p>
+ *
* @param name The name of property to set.
* Must not be <code>null</code>.
* @param value The new value of the property.
@@ -682,6 +718,9 @@
* these properties as properties that have not come from the
* command line.
*
+ * <p>Delegates to the two-arg version, completely ignoring the
+ * ns parameter.</p>
+ *
* @param ns The namespace for the property (currently not used).
* @param name The name of property to set.
* Must not be <code>null</code>.
@@ -699,6 +738,8 @@
* these properties as properties that have not come from the
* command line.
*
+ * <p>Does <code>not</code> consult any delegates.</p>
+ *
* @param name The name of property to set.
* Must not be <code>null</code>.
* @param value The new value of the property.
@@ -720,6 +761,8 @@
* Returns the value of a property, if it is set. You can override
* this method in order to plug your own storage.
*
+ * <p>Delegates to the one-arg version ignoring the ns parameter.</p>
+ *
* @param ns The namespace for the property (currently not used).
* @param name The name of the property.
* May be <code>null</code>, in which case
@@ -733,8 +776,15 @@
}
/**
- * Returns the value of a property, if it is set. You can override
- * this method in order to plug your own storage.
+ * Returns the value of a property, if it is set.
+ *
+ * <p>This is the method that is invoked by {Project#getProperty
+ * Project.getProperty}.</p>
+ *
+ * <p>You can override this method in order to plug your own
+ * storage but the recommended approach is to add your own
+ * implementation of {...@link PropertyEvaluator PropertyEvaluator}
+ * instead.</p>
*
* @param name The name of the property.
* May be <code>null</code>, in which case
@@ -761,6 +811,8 @@
/**
* Returns the value of a user property, if it is set.
*
+ * <p>Delegates to the one-arg version ignoring the ns parameter.</p>
+ *
* @param ns The namespace for the property (currently not used).
* @param name The name of the property.
* May be <code>null</code>, in which case
@@ -776,6 +828,8 @@
/**
* Returns the value of a user property, if it is set.
*
+ * <p>Does <code>not</code> consult any delegates.</p>
+ *
* @param name The name of the property.
* May be <code>null</code>, in which case
* the return value is also <code>null</code>.
@@ -796,6 +850,10 @@
/**
* Returns a copy of the properties table.
+ *
+ * <p>Does not contain properties held by implementations of
+ * delegates (like local properties).</p>
+ *
* @return a hashtable containing all properties (including user
properties).
*/
public Hashtable getProperties() {
@@ -809,6 +867,10 @@
/**
* Returns a copy of the user property hashtable
+ *
+ * <p>Does not contain properties held by implementations of
+ * delegates (like local properties).</p>
+ *
* @return a hashtable containing just the user properties
*/
public Hashtable getUserProperties() {
@@ -820,6 +882,10 @@
/**
* Returns a copy of the inherited property hashtable
+ *
+ * <p>Does not contain properties held by implementations of
+ * delegates (like local properties).</p>
+ *
* @return a hashtable containing just the inherited properties
*/
public Hashtable getInheritedProperties() {
@@ -863,6 +929,9 @@
* <p>To copy all "user" properties, you will also have to call
* {...@link #copyUserProperties copyUserProperties}.</p>
*
+ * <p>Does not copy properties held by implementations of
+ * delegates (like local properties).</p>
+ *
* @param other the project to copy the properties to. Must not be null.
*
* @since Ant 1.6
@@ -890,6 +959,9 @@
* <p>To copy all "user" properties, you will also have to call
* {...@link #copyInheritedProperties copyInheritedProperties}.</p>
*
+ * <p>Does not copy properties held by implementations of
+ * delegates (like local properties).</p>
+ *
* @param other the project to copy the properties to. Must not be null.
*
* @since Ant 1.6
