propertyHelper info

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@677346 13f79535-47bb-0310-9956-ffa450edef68

docs/manual/CoreTasks/propertyhelper.html

@@ -30,7 +30,8 @@
 <b>(a)</b> install a different PropertyHelper at runtime, or
 <b>(b)</b> (hopefully more often) install one or more PropertyHelper Delegates into the
 PropertyHelper active on the current Project. This is somewhat advanced Ant usage and
-assumes a working familiarity with the modern Ant APIs.
+assumes a working familiarity with the modern Ant APIs. See the description of Ant's
+<a href="../using.html#propertyhelper">Property Helper</a> for more information.
 <b>Since Ant 1.8</b></p>
 
 <h3>Parameters specified as nested elements</h3>

docs/manual/develop.html

@@ -128,7 +128,14 @@ good convention, though.</p>
 <h3><a name="set-magic">Conversions Ant will perform for attributes</a></h3>
 
 <p>Ant will always expand properties before it passes the value of an
-attribute to the corresponding setter method.</p>
+attribute to the corresponding setter method. <b>Since Ant 1.8</b>, it is
+possible to <a href="using.html#propertyhelper">extend Ant's property handling</a>
+such that a non-string Object may be the result of the evaluation of a string
+containing a single property reference. These will be assigned directly via
+setter methods of matching type. Since it requires some beyond-the-basics
+intervention to enable this behavior, it may be a good idea to flag attributes
+intended to permit this usage paradigm.
+</p>
 
 <p>The most common way to write an attribute setter is to use a
 <code>java.lang.String</code> argument.  In this case Ant will pass
@@ -156,6 +163,13 @@ is more!  If the argument of you setter method is</p>
   not, Ant will interpret the value as a path name relative to the
   project's basedir.</li>
 
+  <li><code>org.apache.tools.ant.types.Resource</code>
+  <code>org.apache.tools.ant.types.Resource</code>, Ant will
+  resolve the string as a <code>java.io.File</code> as above, then
+  pass in as a <code>org.apache.tools.ant.types.resources.FileResource</code>.
+  <b>Since Ant 1.8</b>
+  </li>
+
   <li><code>org.apache.tools.ant.types.Path</code>, Ant will tokenize
   the value specified in the build file, accepting <code>:</code> and
   <code>;</code> as path separators.  Relative path names will be

docs/manual/tutorial-writing-tasks.html

@@ -282,8 +282,10 @@ arguments of the set-method:<ul>
 <li>its wrapper classes like <i>java.lang.Integer</i>, <i>java.lang.Long</i>, ...</li>
 <li><i>java.lang.String</i></li>
 <li>some more classes (e.g. <i>java.io.File</i>; see
-    <a href="http://ant.apache.org/manual/develop.html#set-magic">Manual
+    <a href="develop.html#set-magic">Manual
     'Writing Your Own Task' [3]</a>)</li>
+<li>Any Java Object parsed from Ant 1.8's <a href="using.html#propertyhelper">Property
+Helper</a></li>
 </ul>
 Before calling the set-method all properties are resolved. So a <tt>&lt;helloworld message="${msg}"/&gt;</tt>
 would not set the message string to "${msg}" if there is a property "msg" with a set value.

docs/manual/using.html

@@ -325,6 +325,17 @@ maybe not set inside IDEs:</p>
 ant.home            home directory of Ant
 </pre>
 
+<a name="propertyHelper"><h3>Property Helpers</h3></a>
+Ant's property handling is accomplished by an instance of
+<code>org.apache.tools.ant.PropertyHelper</code> associated with the current Project.
+You can learn more about this class by examining Ant's Java API. In Ant 1.8 the
+PropertyHelper class was much reworked and now itself employs a number of helper
+classes (actually instances of the <code>org.apache.tools.ant.PropertyHelper$Delegate</code>
+marker interface) to take care of discrete tasks such as property setting, retrieval,
+parsing, etc. This makes Ant's property handling highly extensible; also of interest is the
+new <a href="CoreTasks/propertyhelper.html">propertyhelper</a> task used to manipulate the
+PropertyHelper and its delegates from the context of the Ant buildfile.
+
 <a name="example"><h3>Example Buildfile</h3></a>
 <pre>
 &lt;project name=&quot;MyProject&quot; default=&quot;dist&quot; basedir=&quot;.&quot;&gt;

docs/manual/usinglist.html

@@ -35,6 +35,7 @@
   <a href="using.html#tasks">Tasks</a><br/>
   <a href="using.html#properties">Properties</a><br/>
   <a href="using.html#built-in-props">Built-in Properties</a><br/>
+  <a href="using.html#propertyhelper">Property Helpers</a><br />
   <a href="using.html#example">Example Buildfile</a><br/>
   <a href="using.html#filters">Token Filters</a><br/>
   <a href="using.html#path">Path-like Structures</a><br/>