From 8ff0a1229189912701348624b729d25328c338c2 Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Wed, 6 Nov 2002 08:43:46 +0000 Subject: [PATCH] Doc patches and additional tests for . Submitted by: Paul Christmann git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@273487 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTasks/xmlproperty.html | 209 ++++++++++++++++-- .../keeproot-collapse-original.properties | 5 + .../keeproot-nocollapse-original.properties | 5 + .../nokeeproot-collapse-original.properties | 4 + .../nokeeproot-nocollapse-original.properties | 4 + .../taskdefs/xmlproperty/inputs/original.xml | 5 + .../taskdefs/xmlproperty/inputs/override.xml | 5 + .../tools/ant/taskdefs/XmlProperty.java | 29 ++- .../tools/ant/taskdefs/XmlPropertyTest.java | 5 + 9 files changed, 240 insertions(+), 31 deletions(-) create mode 100644 src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-collapse-original.properties create mode 100644 src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-nocollapse-original.properties create mode 100644 src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-collapse-original.properties create mode 100644 src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-nocollapse-original.properties create mode 100644 src/etc/testcases/taskdefs/xmlproperty/inputs/original.xml diff --git a/docs/manual/CoreTasks/xmlproperty.html b/docs/manual/CoreTasks/xmlproperty.html index 44df5b105..3c337d34b 100644 --- a/docs/manual/CoreTasks/xmlproperty.html +++ b/docs/manual/CoreTasks/xmlproperty.html @@ -5,11 +5,72 @@ -

XmlProperty

Description

-Loads property values from a valid xml file. +Loads property values from a valid xml file. This XML property file: +

+  <root>
+    <properties>
+      <foo>bar</foo>
+    </properties>
+  </root>
+
+is roughly equivalent to this java property file: +
+  root.properties.foo = bar
+
+ +

+By default, this load +does no processing of the input. In particular, unlike the +Property task, property references +(i.e., ${foo}) are not resolved. +

+ +

Semantic Attributes

+ +Input processing can be enabled by using the semanticAttributes +attribute. If this attribute is set to true (its default is +false), the following processing occurs as the input XML file +is loaded: +
    +
  • Property references are resolved.
    • +
  • The following attriubtes are treated differently: +
      +
    • id: The property is associated with the given id value.
      • +
    • location: The property is treated as a file location
      • +
    • refid: The property is set to the value of the + referenced property.
      • +
    • value: The property is set to the value indicated.
      • +
    +
    • +
  • Path-like Structures can be defined + by use of the following attributes: +
      +
    • pathid: 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.
      • +
    +
    • +
+

+For example, with semantic attribute processing enabled, this XML property +file: +

+  <root>
+    <properties>
+      <foo location="bar"/>
+      <quux>${root.properties.foo}</quux>
+    </properties>
+  </root>
+
+is roughly equivalent to the following fragments in a build.xml file: +
+  <property name="root.properties.foo" location="bar"/>
+  <property name="root.properties.quux" value="${root.properties.foo}"/>
+
+

Parameters

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

Examples

-
   <xmlproperty file="somefile.xml" />
+ + +

Non-semantic Attributes

-

Load contents of somefile.xml as Ant properties, -generating the property names from the -file's element and attribute names.

+

Here is an example xml file that does not have any semantic attributes.

 
    <root-tag myattr="true">
@@ -62,28 +145,110 @@ file's element and attribute names.

    </root-tag>
-

This is an example xml file.

- -
   root-tag(myattr)=true
+
default loading

+
This entry in a build file:
+
   <xmlproperty file="somefile.xml" />

+is equivalent to the following properties:
+
+   root-tag(myattr)=true
    root-tag.inner-tag=Text
    root-tag.inner-tag(someattr)=val
    root-tag.a2.a3.a4=false
 

 
-
These are the properties loaded by this task from the previous example file.

-
+
collapseAttributes=false

+
This entry in a build file:
 
   <xmlproperty file="somefile.xml" collapseAttributes="true"/>

-
-
Load contents of somefile.xml as Ant properties collapsing attributes as nodes.

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

 
-
These are the properties loaded by this task from the previous example file, with
-   attribute collapsing true.

+
keepRoot=false

+
This entry in a build file:
+
   <xmlproperty file="somefile.xml" keepRoot="false"/>

+is equivalent to the following properties:
+
+   inner-tag=Text
+   inner-tag(someattr)=val
+   a2.a3.a4=false
+

+
+
Semantic Attributes

+
+
Here is an example xml file that has semantic attributes.

+
+  <root-tag>
+    <version value="0.0.1"/>
+    <build folder="build">
+      <classes id="build.classes" location="${build.folder}/classes"/>
+      <reference refid="build.classes"/>
+    </build>
+    <compile>
+      <classpath pathid="compile.classpath">
+        <pathelement location="${build.classes}"/>
+      </classpath>
+    </compile>
+    <run-time>
+      <jars>*.jar</jars>
+      <classpath pathid="run-time.classpath">
+        <path refid="compile.classpath"/>
+        <pathelement path="${run-time.jars}"/>
+      </classpath>
+    </run-time>
+  </root-tag>
+

+
+
default loading (semanticAttributes=true)

+
This entry in a build file:
+
   <xmlproperty file="somefile.xml"
+                semanticAttributes="true"/>

+is equivalent to the following entries in a build file:
+
+  <property name="version" value="0.0.1"/>
+  <property name="build.folder" value="build"/>
+  <property name="build.classes" location="${build.folder}/classes" id="build.classes"/>
+  <property name="build.reference" refid="build.classes"/>
+
+  <property name="run-time.jars" value="*.jar/>
+
+  <classpath id="compile.classpath">
+    <pathelement location="${build.classes}"/>
+  </classpath>
+
+  <classpath id="run-time.classpath">
+    <path refid="compile.classpath"/>
+    <pathelement path="${run-time.jars}"/>
+  </classpath>
+

+
+
includeSemanticAttribute="true"

+
This entry in a build file:
+
   <xmlproperty file="somefile.xml"
+                semanticAttributes="true"
+                includeSemanticAttribute="true"/>
+

+is equivalent to the following entries in a build file:
+
+  <property name="version.value" value="0.0.1"/>
+  <property name="build.folder" value="build"/>
+  <property name="build.classes.location" location="${build.folder}/classes"/>
+  <property name="build.reference.refid" refid="build.location"/>
+
+  <property name="run-time.jars" value="*.jar/>
+
+  <classpath id="compile.classpath">
+    <pathelement location="${build.classes}"/>
+  </classpath>
+
+  <classpath id="run-time.classpath">
+    <path refid="compile.classpath"/>
+    <pathelement path="${run-time.jars}"/>
+  </classpath>
+

 
 

 
diff --git a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-collapse-original.properties b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-collapse-original.properties
new file mode 100644
index 000000000..8797a3f8f
--- /dev/null
+++ 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
+
diff --git a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-nocollapse-original.properties b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/keeproot-nocollapse-original.properties
new file mode 100644
index 000000000..58b372ecd
--- /dev/null
+++ 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
+
diff --git a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-collapse-original.properties b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-collapse-original.properties
new file mode 100644
index 000000000..bc4a02c7f
--- /dev/null
+++ 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
+
diff --git a/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-nocollapse-original.properties b/src/etc/testcases/taskdefs/xmlproperty/goldfiles/nokeeproot-nocollapse-original.properties
new file mode 100644
index 000000000..40a15a8b8
--- /dev/null
+++ 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
+
diff --git a/src/etc/testcases/taskdefs/xmlproperty/inputs/original.xml b/src/etc/testcases/taskdefs/xmlproperty/inputs/original.xml
new file mode 100644
index 000000000..2bf54a152
--- /dev/null
+++ b/src/etc/testcases/taskdefs/xmlproperty/inputs/original.xml
@@ -0,0 +1,5 @@
+
+  Text
+  false
+
+
diff --git a/src/etc/testcases/taskdefs/xmlproperty/inputs/override.xml b/src/etc/testcases/taskdefs/xmlproperty/inputs/override.xml
index 9ae88991f..ea01264eb 100644
--- a/src/etc/testcases/taskdefs/xmlproperty/inputs/override.xml
+++ b/src/etc/testcases/taskdefs/xmlproperty/inputs/override.xml
@@ -1,5 +1,10 @@
 
   
+    
     
   
 
\ No newline at end of file
diff --git a/src/main/org/apache/tools/ant/taskdefs/XmlProperty.java b/src/main/org/apache/tools/ant/taskdefs/XmlProperty.java
index 90ec7f48c..37bc35107 100644
--- 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;
  *
  * 
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;
  *
  * 
  * <root-tag>
- *   <build location="build">
- *     <classes id="build.classes" location="${build.location}/classes"/>
- *     <reference refid="build.location"/>
+ *   <build>
+ *   <build folder="build">
+ *     <classes id="build.classes" location="${build.folder}/classes"/>
+ *     <reference refid="build.classes"/>
  *   </build>
  *   <compile>
  *     <classpath pathid="compile.classpath">
@@ -155,9 +156,9 @@ import org.xml.sax.SAXException;
  * 
is equivalent to the following entries in a build file:

  *
  * 
- * <property name="build.location" location="build"/>
- * <property name="build.classes.location" location="${build.location}/classes"/>
- * <property name="build.reference" refid="build.location"/>
+ * <property name="build" location="build"/>
+ * <property name="build.classes" location="${build.location}/classes"/>
+ * <property name="build.reference" refid="build.classes"/>
  *
  * <property name="run-time.jars" value="*.jar/>
  *
@@ -193,13 +194,13 @@ import org.xml.sax.SAXException;
  * 
  • semanticAttributes: Indicate whether attributes
  *     named "location", "value", "refid" and "path"
  *     are interpreted as ant properties.  Defaults
- *     to true.
    • 
+ *     to false.
  * 
  • rootDirectory: Indicate the directory to use
  *     as the root directory for resolving location
  *     properties.  Defaults to the directory
  *     of the project using the task.
    • 
  * 
  • includeSemanticAttribute: 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.
    • 
  * 
  *
@@ -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 {
diff --git a/src/testcases/org/apache/tools/ant/taskdefs/XmlPropertyTest.java b/src/testcases/org/apache/tools/ant/taskdefs/XmlPropertyTest.java
index f424d1f32..df796d1a7 100644
--- 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());