Doc patches and additional tests for <xmlproperty>.

Submitted by: Paul Christmann <paul at priorartisans.com> git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@273487 13f79535-47bb-0310-9956-ffa450edef68
23 years ago · 8ff0a12291
--- a/docs/manual/CoreTasks/xmlproperty.html
+++ b/docs/manual/CoreTasks/xmlproperty.html
@@ -5,11 +5,72 @@

 <body>


 <h2><a name="xmlproperty">XmlProperty</a></h2>
 <h3>Description</h3>
 <p>
 Loads property values from a valid xml file.
 Loads property values from a valid xml file.  This XML property file:
 <pre>
  &lt;root&gt;
    &lt;properties&gt;
      &lt;foo&gt;bar&lt;/foo&gt;
    &lt;/properties&gt;
  &lt;/root&gt;
 </pre>
 is roughly equivalent to this java property file:
 <pre>
  root.properties.foo = bar
 </pre>

 <p>
 By default, this load
 does <em>no</em> processing of the input.  In particular, unlike the
 <a href="property.html">Property task</a>, property references
 (i.e., ${foo}) are not resolved.
 <p>
 <a name="semanticAttributes">
 <h3>Semantic Attributes</h3>
 </a>
 Input processing can be enabled by using the <b>semanticAttributes</b>
 attribute.  If this attribute is set to <i>true</i> (its default is
 <i>false</i>), the following processing occurs as the input XML file
 is loaded:
 <ul>
  <li>Property references are resolved.</li>
  <li>The following attriubtes are treated differently:
    <ul>
      <li><b>id</b>: The property is associated with the given id value.</li>
      <li><b>location</b>: The property is treated as a file location</li>
      <li><b>refid</b>: The property is set to the value of the
          referenced property.</li>
      <li><b>value</b>: The property is set to the value indicated.</li>
    </ul>
  </li>
  <li><a href="../using.html#path">Path-like Structures</a> can be defined
      by use of the following attributes:
    <ul>
      <li><b>pathid</b>: The given id is used to identify a path.  The
          nested XML tag name is ignored.  Child elements can be used
          (XML tag names are ignored) to identify elements of the path.</li>
    </ul>
  </li>
 </ul>
 <p>
 For example, with semantic attribute processing enabled, this XML property
 file:
 <pre>
  &lt;root&gt;
    &lt;properties&gt;
      &lt;foo location="bar"/&gt;
      &lt;quux&gt;${root.properties.foo}&lt;/quux&gt;
    &lt;/properties&gt;
  &lt;/root&gt;
 </pre>
 is roughly equivalent to the following fragments in a build.xml file:
 <pre>
  &lt;property name="root.properties.foo" location="bar"/&gt;
  &lt;property name="root.properties.quux" value="${root.properties.foo}"/&gt;
 </pre>

 </p>

 <h3>Parameters</h3>
@@ -31,29 +92,51 @@ Loads property values from a valid xml file.
  </tr>
  <tr>
    <td valign="top">keepRoot</td>
    <td valign="top">If false, it doesn't include the xml root tag as a first
                     value in the property name.</td>
    <td valign="top">Keep the xml root tag as the
                     first value in the property name.</td>
    <td valign="top" align="center">No, default is <i>true</i>.</td>
  </tr>  
  <tr>
    <td valign="top">validate</td>
    <td valign="top">If true, it enables validation.</td>
    <td valign="top">Validate the input file.</td>
    <td valign="top" align="center">No, default is <i>false</i>.</td>
  </tr>
  <tr>
    <td valign="top">collapseAttributes</td>
    <td valign="top">If true, it treats attributes as nested elements.</td>
    <td valign="top">Treat attributes as nested elements.</td>
    <td valign="top" align="center">No, default is <i>false</i>.</td>
  </tr>
  <tr>
    <td valign="top">semanticAttributes</td>
    <td valign="top">Enable special handling of certain attribute names.
                     See the <a href="#semanticAttributes">Semantic Attributes</a>
                     section for more information.</td>
    <td valign="top" align="center">No, default is <i>false</i>.</td>
  </tr>  
  <tr>
    <td valign="top">includeSemanticAttribute</td>
    <td valign="top">Include the semantic attribute name
                     as part of the property name.  Ignored if
                     <i>semanticAttributes</i> is not set to <i>true</i>.
                     See the <a href="#semanticAttributes">Semantic Attributes</a>
                     section for more information.</td>
    <td valign="top" align="center">No, default is <i>false</i>.</td>
  </tr>
  <tr>
    <td valign="top">rootDirectory</td>
    <td valign="top">The directory to use for resolving file references. Ignored
                     if <i>semanticAttributes</i> is not set to <i>true</i>.</td>
    <td valign="top" align="center">No, default is <i>${basedir}</i>.</td>
  </tr>
 </table>


 <a name="examples">
 <h3>Examples</h3>
 <pre>   &lt;xmlproperty file="somefile.xml" /&gt;</pre>
 </a>

 <h4>Non-semantic Attributes</h4>

 <p>Load contents of somefile.xml as Ant properties,
 generating the property names from the 
 file's element and attribute names.</p>
 <p>Here is an example xml file that does not have any semantic attributes.</p>

 <pre> 
   &lt;root-tag myattr="true"&gt;
@@ -62,28 +145,110 @@ file's element and attribute names.</p>
   &lt;/root-tag&gt;
 </pre>

 <p>This is an example xml file.</p>

 <pre>   root-tag(myattr)=true
 <h5>default loading</h5>
 <p>This entry in a build file:
 <pre>   &lt;xmlproperty file="somefile.xml" /&gt;</pre>
 is equivalent to the following properties:
 <pre>
   root-tag(myattr)=true
   root-tag.inner-tag=Text
   root-tag.inner-tag(someattr)=val
   root-tag.a2.a3.a4=false
 </pre>

 <p>These are the properties loaded by this task from the previous example file.</p>

 <h5>collapseAttributes=false</h5>
 <p>This entry in a build file:
 <pre>   &lt;xmlproperty file="somefile.xml" collapseAttributes="true"/&gt;</pre>

 <p>Load contents of somefile.xml as Ant properties collapsing attributes as nodes.</p>

 <pre>   root-tag.myattr=true
 is equivalent to the following properties:
 <pre>
   root-tag.myattr=true
   root-tag.inner-tag=Text
   root-tag.inner-tag.someatt=val
   root-tag.a2.a3.a4=false
 </pre>

 <p>These are the properties loaded by this task from the previous example file, with
   attribute collapsing true.</p>
 <h5>keepRoot=false</h5>
 <p>This entry in a build file:
 <pre>   &lt;xmlproperty file="somefile.xml" keepRoot="false"/&gt;</pre>
 is equivalent to the following properties:
 <pre>
   inner-tag=Text
   inner-tag(someattr)=val
   a2.a3.a4=false
 </pre>

 <h4>Semantic Attributes</h4>

 <p>Here is an example xml file that has semantic attributes.</p>
 <pre>
  &lt;root-tag&gt;
    &lt;version value="0.0.1"/&gt;
    &lt;build folder="build"&gt;
      &lt;classes id="build.classes" location="${build.folder}/classes"/&gt;
      &lt;reference refid="build.classes"/&gt;
    &lt;/build&gt;
    &lt;compile&gt;
      &lt;classpath pathid="compile.classpath"&gt;
        &lt;pathelement location="${build.classes}"/&gt;
      &lt;/classpath&gt;
    &lt;/compile&gt;
    &lt;run-time&gt;
      &lt;jars&gt;*.jar&lt;/jars&gt;
      &lt;classpath pathid="run-time.classpath"&gt;
        &lt;path refid="compile.classpath"/&gt;
        &lt;pathelement path="${run-time.jars}"/&gt;
      &lt;/classpath&gt;
    &lt;/run-time&gt;
  &lt;/root-tag&gt;
 </pre>

 <h5>default loading (semanticAttributes=true)</h5>
 <p>This entry in a build file:
 <pre>   &lt;xmlproperty file="somefile.xml"
                semanticAttributes="true"/&gt;</pre>
 is equivalent to the following entries in a build file:
 <pre>
  &lt;property name="version" value="0.0.1"/&gt;
  &lt;property name="build.folder" value="build"/&gt;
  &lt;property name="build.classes" location="${build.folder}/classes" id="build.classes"/&gt;
  &lt;property name="build.reference" refid="build.classes"/&gt;

  &lt;property name="run-time.jars" value="*.jar/&gt;

  &lt;classpath id="compile.classpath"&gt;
    &lt;pathelement location="${build.classes}"/&gt;
  &lt;/classpath&gt;

  &lt;classpath id="run-time.classpath"&gt;
    &lt;path refid="compile.classpath"/&gt;
    &lt;pathelement path="${run-time.jars}"/&gt;
  &lt;/classpath&gt;
 </pre>

 <h5>includeSemanticAttribute="true"</h5>
 <p>This entry in a build file:
 <pre>   &lt;xmlproperty file="somefile.xml"
                semanticAttributes="true"
                includeSemanticAttribute="true"/&gt;
 </pre>
 is equivalent to the following entries in a build file:
 <pre>
  &lt;property name="version.value" value="0.0.1"/&gt;
  &lt;property name="build.folder" value="build"/&gt;
  &lt;property name="build.classes.location" location="${build.folder}/classes"/&gt;
  &lt;property name="build.reference.refid" refid="build.location"/&gt;

  &lt;property name="run-time.jars" value="*.jar/&gt;

  &lt;classpath id="compile.classpath"&gt;
    &lt;pathelement location="${build.classes}"/&gt;
  &lt;/classpath&gt;

  &lt;classpath id="run-time.classpath"&gt;
    &lt;path refid="compile.classpath"/&gt;
    &lt;pathelement path="${run-time.jars}"/&gt;
  &lt;/classpath&gt;
 </pre>

 <hr/>

--- a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-collapse-original.properties
+++ b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-collapse-original.properties
@@ -0,0 +1,5 @@
 root-tag.myattr=true
 root-tag.inner-tag=Text
 root-tag.inner-tag.someattr=val
 root-tag.a2.a3.a4=false

--- a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-nocollapse-original.properties
+++ b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-nocollapse-original.properties
@@ -0,0 +1,5 @@
 root-tag(myattr)=true
 root-tag.inner-tag=Text
 root-tag.inner-tag(someattr)=val
 root-tag.a2.a3.a4=false

--- a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-collapse-original.properties
+++ b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-collapse-original.properties
@@ -0,0 +1,4 @@
 inner-tag=Text
 inner-tag.someattr=val
 a2.a3.a4=false

--- a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-nocollapse-original.properties
+++ b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-nocollapse-original.properties
@@ -0,0 +1,4 @@
 inner-tag=Text
 inner-tag(someattr)=val
 a2.a3.a4=false

--- a/src/etc/testcases/taskdefs/xmlproperty/inputs/original.xml
+++ b/src/etc/testcases/taskdefs/xmlproperty/inputs/original.xml
@@ -0,0 +1,5 @@
 <root-tag myattr="true">
  <inner-tag someattr="val">Text</inner-tag>
  <a2><a3><a4>false</a4></a3></a2>
 </root-tag>

--- a/src/etc/testcases/taskdefs/xmlproperty/inputs/override.xml
+++ b/src/etc/testcases/taskdefs/xmlproperty/inputs/override.xml
@@ -1,5 +1,10 @@
 <root>
  <override>
    <!-- This property should not get set.  The
         XmlPropertyTest code explicitly sets
         override.property.test to foo to make
         sure that attempts to reset it via
         property file loads *fail*. -->
    <property test="bar"/>
  </override>
 </root>
--- a/src/main/org/apache/tools/ant/taskdefs/XmlProperty.java
+++ b/src/main/org/apache/tools/ant/taskdefs/XmlProperty.java
@@ -113,7 +113,7 @@ import org.xml.sax.SAXException;
 *
 * <p>Optionally, to more closely mirror the abilities of the Property
 * task, a selected set of attributes can be treated specially.  To
 * enable this behavior, the "semanticAttribute" property of this task
 * enable this behavior, the "semanticAttributes" property of this task
 * must be set to true (it defaults to false).  If this attribute is
 * specified, the following attributes take on special meaning
 * (setting this to true implicitly sets collapseAttributes to true as
@@ -133,9 +133,10 @@ import org.xml.sax.SAXException;
 *
 * <pre>
 * &lt;root-tag&gt;
 *   &lt;build location="build"&gt;
 *     &lt;classes id="build.classes" location="${build.location}/classes"/&gt;
 *     &lt;reference refid="build.location"/&gt;
 *   &lt;build&gt;
 *   &lt;build folder="build"&gt;
 *     &lt;classes id="build.classes" location="${build.folder}/classes"/&gt;
 *     &lt;reference refid="build.classes"/&gt;
 *   &lt;/build&gt;
 *   &lt;compile&gt;
 *     &lt;classpath pathid="compile.classpath"&gt;
@@ -155,9 +156,9 @@ import org.xml.sax.SAXException;
 * <p>is equivalent to the following entries in a build file:</p>
 *
 * <pre>
 * &lt;property name="build.location" location="build"/&gt;
 * &lt;property name="build.classes.location" location="${build.location}/classes"/&gt;
 * &lt;property name="build.reference" refid="build.location"/&gt;
 * &lt;property name="build" location="build"/&gt;
 * &lt;property name="build.classes" location="${build.location}/classes"/&gt;
 * &lt;property name="build.reference" refid="build.classes"/&gt;
 *
 * &lt;property name="run-time.jars" value="*.jar/&gt;
 *
@@ -193,13 +194,13 @@ import org.xml.sax.SAXException;
 * <li><b>semanticAttributes</b>: Indicate whether attributes
 *     named "location", "value", "refid" and "path"
 *     are interpreted as ant properties.  Defaults
 *     to true.</li>
 *     to false.</li>
 * <li><b>rootDirectory</b>: Indicate the directory to use
 *     as the root directory for resolving location
 *     properties.  Defaults to the directory
 *     of the project using the task.</li>
 * <li><b>includeSemanticAttribute</b>: Indicate whether to include
 *     the semanticAttribute ("location" or "value") as
 *     the semantic attribute ("location" or "value") as
 *     part of the property name.  Defaults to false.</li>
 * </ul>
 *
@@ -275,6 +276,10 @@ public class XmlProperty extends org.apache.tools.ant.Task {

            Element topElement = factory.newDocumentBuilder().parse(configurationStream).getDocumentElement();

            // Keep a hashtable of attributes added by this task.
            // This task is allow to override its own properties
            // but not other properties.  So we need to keep track
            // of which properties we've added.
            addedAttributes = new Hashtable();

            if (keepRoot) {
@@ -473,6 +478,12 @@ public class XmlProperty extends org.apache.tools.ant.Task {
        if (addedAttributes.containsKey(name)) {
            // If this attribute was added by this task, then
            // we append this value to the existing value.
            // We use the setProperty method which will
            // forcibly override the property if it already exists.
            // We need to put these properties into the project
            // when we read them, though (instead of keeping them
            // outside of the project and batch adding them at the end)
            // to allow other properties to reference them.
            value = (String)addedAttributes.get(name) + "," + value;
            getProject().setProperty(name, value);
        } else {
--- a/src/testcases/org/apache/tools/ant/taskdefs/XmlPropertyTest.java
+++ b/src/testcases/org/apache/tools/ant/taskdefs/XmlPropertyTest.java
@@ -180,13 +180,18 @@ public class XmlPropertyTest extends BuildFileTest {
                xmlproperty.setIncludeSemanticAttribute(include);
                xmlproperty.setRootDirectory(workingDir);

                // Set a property on the project to make sure that loading
                // a property with the same name from an xml file will
                // *not* change it.
                project.setNewProperty("override.property.test", "foo");

                xmlproperty.execute();

                Properties props = new Properties();
                props.load(new FileInputStream(propertyFile));

                //printProperties(project.getProperties());

                ensureProperties(msg, inputFile, workingDir, project, props);
                ensureReferences(msg, inputFile, project.getReferences());