From e2c45d16da89cd3a956efa6b949e32e1b199fd71 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 4 Sep 2009 09:26:43 +0000 Subject: [PATCH] method level Javadocs for PropertyHelper git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@811318 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/tools/ant/ProjectHelper.java | 3 + .../org/apache/tools/ant/PropertyHelper.java | 104 +++++++++++++++--- 2 files changed, 91 insertions(+), 16 deletions(-) diff --git a/src/main/org/apache/tools/ant/ProjectHelper.java b/src/main/org/apache/tools/ant/ProjectHelper.java index 13520a94e..fc49c2cf6 100644 --- a/src/main/org/apache/tools/ant/ProjectHelper.java +++ b/src/main/org/apache/tools/ant/ProjectHelper.java @@ -495,6 +495,9 @@ public class ProjectHelper { * null entries in the first list indicate a property * reference from the second list. * + *

As of Ant 1.8.0 this method is never invoked by any code + * inside of Ant itself.

+ * * @param value Text to parse. Must not be null. * @param fragments List to add text fragments to. * Must not be null. diff --git a/src/main/org/apache/tools/ant/PropertyHelper.java b/src/main/org/apache/tools/ant/PropertyHelper.java index bbf7a4924..133475bc8 100644 --- a/src/main/org/apache/tools/ant/PropertyHelper.java +++ b/src/main/org/apache/tools/ant/PropertyHelper.java @@ -172,11 +172,13 @@ public class PropertyHelper implements GetProperty { // -------------------------------------------------------- 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 @@ public class PropertyHelper implements GetProperty { // 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 @@ public class PropertyHelper implements GetProperty { } /** - * 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 @@ public class PropertyHelper implements GetProperty { * Again, you are required to respect the immutability semantics (at * least for non-dynamic properties) * + *

As of Ant 1.8.0 this method is never invoked by any code + * inside of Ant itself.

+ * * @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 @@ public class PropertyHelper implements GetProperty { /** * Get the next property helper in the chain. * + *

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.

+ * * @return the next property helper. - * @deprecated + * @deprecated use the delegate mechanism instead */ public PropertyHelper getNext() { return next; @@ -366,7 +376,8 @@ public class PropertyHelper implements GetProperty { } /** - * Get the expanders. + * Get the {@link PropertyExpander expanders}. + * @since Ant 1.8.0 * @return the expanders. */ public Collection getExpanders() { @@ -378,12 +389,14 @@ public class PropertyHelper implements GetProperty { /** * 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. * + *

As of Ant 1.8.0 this method is never invoked by any code + * inside of Ant itself.

+ * * @param ns The namespace that the property is in (currently * not used. * @param name The name of property to set. @@ -416,6 +429,9 @@ public class PropertyHelper implements GetProperty { * Get a property. If all hooks return null, the default * tables will be used. * + *

As of Ant 1.8.0 this method is never invoked by any code + * inside of Ant itself.

+ * * @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 @@ public class PropertyHelper implements GetProperty { * null entries in the first list indicate a property * reference from the second list. * - * It can be overridden with a more efficient or customized version. + *

Delegates to {@link #parsePropertyStringDefault + * parsePropertyStringDefault}.

+ * + *

As of Ant 1.8.0 this method is never invoked by any code + * inside of Ant itself except {ProjectHelper#parsePropertyString + * ProjectHelper.parsePropertyString}.

* * @param value Text to parse. Must not be null. * @param fragments List to add text fragments to. @@ -462,7 +483,7 @@ public class PropertyHelper implements GetProperty { * @exception BuildException if the string contains an opening * ${ without a closing * } - * @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 @@ public class PropertyHelper implements GetProperty { * Replaces ${xxx} style constructions in the given value * with the string value of the corresponding data types. * + *

Delegates to the one-arg version, completely ignoring the ns + * and keys parameters.

+ * * @param ns The namespace for the property. * @param value The string to be scanned for property references. * May be null, in which case this @@ -548,6 +572,10 @@ public class PropertyHelper implements GetProperty { * Default implementation of setProperty. Will be called from Project. * This is the original 1.5 implementation, with calls to the hook * added. + * + *

Delegates to the three-arg version, completely ignoring the + * ns parameter.

+ * * @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 @@ public class PropertyHelper implements GetProperty { /** * 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 @@ public class PropertyHelper implements GetProperty { * exists already, a message is logged and the method returns with * no other effect. * + *

Delegates to the two-arg version, completely ignoring the + * ns parameter.

+ * * @param ns The namespace for the property (currently not used). * @param name The name of property to set. * Must not be null. @@ -649,6 +678,10 @@ public class PropertyHelper implements GetProperty { /** * Sets a user property, which cannot be overwritten by * set/unset property calls. Any previous value is overwritten. + * + *

Delegates to the two-arg version, completely ignoring the + * ns parameter.

+ * * @param ns The namespace for the property (currently not used). * @param name The name of property to set. * Must not be null. @@ -663,6 +696,9 @@ public class PropertyHelper implements GetProperty { /** * Sets a user property, which cannot be overwritten by * set/unset property calls. Any previous value is overwritten. + * + *

Does not consult any delegates.

+ * * @param name The name of property to set. * Must not be null. * @param value The new value of the property. @@ -682,6 +718,9 @@ public class PropertyHelper implements GetProperty { * these properties as properties that have not come from the * command line. * + *

Delegates to the two-arg version, completely ignoring the + * ns parameter.

+ * * @param ns The namespace for the property (currently not used). * @param name The name of property to set. * Must not be null. @@ -699,6 +738,8 @@ public class PropertyHelper implements GetProperty { * these properties as properties that have not come from the * command line. * + *

Does not consult any delegates.

+ * * @param name The name of property to set. * Must not be null. * @param value The new value of the property. @@ -720,6 +761,8 @@ public class PropertyHelper implements GetProperty { * Returns the value of a property, if it is set. You can override * this method in order to plug your own storage. * + *

Delegates to the one-arg version ignoring the ns parameter.

+ * * @param ns The namespace for the property (currently not used). * @param name The name of the property. * May be null, in which case @@ -733,8 +776,15 @@ public class PropertyHelper implements GetProperty { } /** - * 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. + * + *

This is the method that is invoked by {Project#getProperty + * Project.getProperty}.

+ * + *

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.

* * @param name The name of the property. * May be null, in which case @@ -761,6 +811,8 @@ public class PropertyHelper implements GetProperty { /** * Returns the value of a user property, if it is set. * + *

Delegates to the one-arg version ignoring the ns parameter.

+ * * @param ns The namespace for the property (currently not used). * @param name The name of the property. * May be null, in which case @@ -776,6 +828,8 @@ public class PropertyHelper implements GetProperty { /** * Returns the value of a user property, if it is set. * + *

Does not consult any delegates.

+ * * @param name The name of the property. * May be null, in which case * the return value is also null. @@ -796,6 +850,10 @@ public class PropertyHelper implements GetProperty { /** * Returns a copy of the properties table. + * + *

Does not contain properties held by implementations of + * delegates (like local properties).

+ * * @return a hashtable containing all properties (including user properties). */ public Hashtable getProperties() { @@ -809,6 +867,10 @@ public class PropertyHelper implements GetProperty { /** * Returns a copy of the user property hashtable + * + *

Does not contain properties held by implementations of + * delegates (like local properties).

+ * * @return a hashtable containing just the user properties */ public Hashtable getUserProperties() { @@ -820,6 +882,10 @@ public class PropertyHelper implements GetProperty { /** * Returns a copy of the inherited property hashtable + * + *

Does not contain properties held by implementations of + * delegates (like local properties).

+ * * @return a hashtable containing just the inherited properties */ public Hashtable getInheritedProperties() { @@ -863,6 +929,9 @@ public class PropertyHelper implements GetProperty { *

To copy all "user" properties, you will also have to call * {@link #copyUserProperties copyUserProperties}.

* + *

Does not copy properties held by implementations of + * delegates (like local properties).

+ * * @param other the project to copy the properties to. Must not be null. * * @since Ant 1.6 @@ -890,6 +959,9 @@ public class PropertyHelper implements GetProperty { *

To copy all "user" properties, you will also have to call * {@link #copyInheritedProperties copyInheritedProperties}.

* + *

Does not copy properties held by implementations of + * delegates (like local properties).

+ * * @param other the project to copy the properties to. Must not be null. * * @since Ant 1.6