Package org.apache.tools.ant.taskdefs

Class XmlProperty

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.XmlProperty
All Implemented Interfaces:
Cloneable
public class XmlProperty extends Task
Loads property values from a valid XML file, generating the property names from the file's element and attribute names.

Example:

   <root-tag myattr="true">
     <inner-tag someattr="val">Text</inner-tag>
     <a2><a3><a4>false</a4></a3></a2>
     <x>x1</x>
     <x>x2</x>
   </root-tag>

this generates the following properties:

  root-tag(myattr)=true
  root-tag.inner-tag=Text
  root-tag.inner-tag(someattr)=val
  root-tag.a2.a3.a4=false
  root-tag.x=x1,x2

The collapseAttributes property of this task can be set to true (the default is false) which will instead result in the following properties (note the difference in names of properties corresponding to XML attributes):

  root-tag.myattr=true
  root-tag.inner-tag=Text
  root-tag.inner-tag.someattr=val
  root-tag.a2.a3.a4=false
  root-tag.x=x1,x2

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 "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 well):

  • value: Identifies a text value for a property.
  • location: Identifies a file location for a property.
  • id: Sets an id for a property
  • refid: Sets a property to the value of another property based upon the provided id
  • pathid: Defines a path rather than a property with the given id.

For example, with keepRoot = false, the following properties file:

 <root-tag>
   <build>
   <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>

is equivalent to the following entries in a build file:

 <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/>

 <classpath id="compile.classpath">
   <pathelement location="${build.classes}"/>
 </classpath>

 <classpath id="run-time.classpath">
   <path refid="compile.classpath"/>
   <pathelement path="${run-time.jars}"/>
 </classpath>

This task requires the following attributes:

  • file: The name of the file to load.

This task supports the following attributes:

  • prefix: Optionally specify a prefix applied to all properties loaded. Defaults to an empty string.
  • keepRoot: Indicate whether the root xml element is kept as part of property name. Defaults to true.
  • validate: Indicate whether the xml file is validated. Defaults to false.
  • collapseAttributes: Indicate whether attributes are stored in property names with parens or with period delimiters. Defaults to false, meaning properties are stored with parens (i.e., foo(attr)).
  • semanticAttributes: Indicate whether attributes named "location", "value", "refid" and "path" are interpreted as ant properties. Defaults 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 semantic attribute ("location" or "value") as part of the property name. Defaults to false.