<xml : xmlproperty>

Description

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

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:

This task supports the following attributes:

Parameters

Attribute Description Type Required?
file The XML file to parse; required. File ?
semanticattributes Attribute to enable special handling of attributes - see ant manual. boolean ?
keeproot flag to include the xml root tag as a first value in the property name; optional, default is true boolean ?
prefix the prefix to prepend to each property String ?
collapseattributes flag to treat attributes as nested elements; optional, default false boolean ?
validate flag to validate the XML file; optional, default false boolean ?
rootdirectory The directory to use for resolving file references. Ignored if semanticAttributes is not set to true. File ?
includesemanticattribute Include the semantic attribute name as part of the property name. Ignored if semanticAttributes is not set to true. boolean ?

Parameters accepted as nested elements

<xmlcatalog> ...

This data type provides a catalog of resource locations (such as DTDs and XML entities), based on the OASIS "Open Catalog" standard. The catalog entries are used both for Entity resolution and URI resolution, in accordance with the {@link org.xml.sax.EntityResolver EntityResolver} and {@link javax.xml.transform.URIResolver URIResolver} interfaces as defined in the Java API for XML Processing Specification.

Resource locations can be specified either in-line or in external catalog file(s), or both. In order to use an external catalog file, the xml-commons resolver library ("resolver.jar") must be in your classpath. External catalog files may be either plain text format or XML format. If the xml-commons resolver library is not found in the classpath, external catalog files, specified in <catalogpath> paths, will be ignored and a warning will be logged. In this case, however, processing of inline entries will proceed normally.

Currently, only <dtd> and <entity> elements may be specified inline; these correspond to OASIS catalog entry types PUBLIC and URI respectively.

The following is a usage example:

<xmlcatalog>
  <dtd publicId="" location="/path/to/file.jar" />
  <dtd publicId="" location="/path/to/file2.jar" />
  <entity publicId="" location="/path/to/file3.jar" />
  <entity publicId="" location="/path/to/file4.jar" />
  <catalogpath>
    <pathelement location="/etc/sgml/catalog"/>
  </catalogpath>
  <catalogfiles dir="/opt/catalogs/" includes="**\catalog.xml" />
</xmlcatalog>

Tasks wishing to use <xmlcatalog> must provide a method called createXMLCatalog which returns an instance of XMLCatalog. Nested DTD and entity definitions are handled by the XMLCatalog object and must be labeled dtd and entity respectively.

The following is a description of the resolution algorithm: entities/URIs/dtds are looked up in each of the following contexts, stopping when a valid and readable resource is found:

  1. In the local filesystem
  2. In the classpath
  3. Using the Apache xml-commons resolver (if it is available)
  4. In URL-space

See {@link org.apache.tools.ant.taskdefs.optional.XMLValidateTask XMLValidateTask} for an example of a task that has integrated support for XMLCatalogs.

Possible future extension could provide for additional OASIS entry types to be specified inline.

Attribute Description Type Required
catalogpathref Allows catalogpath reference. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes. Reference ?
classpath Allows simple classpath string. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes. Path ?
classpathref Allows classpath reference. Not allowed if this catalog is itself a reference to another catalog -- that is, a catalog cannot both refer to another and contain elements or other attributes. Reference ?
refid Makes this instance in effect a reference to another XMLCatalog instance.

You must not set another attribute or nest elements inside this element if you make it a reference. That is, a catalog cannot both refer to another and contain elements or attributes.

Reference ?