org.apache.tools.ant.taskdefs

Class XmlProperty

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

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:

UNKNOWN: name="xmlproperty" category="xml"

Constructor Summary
XmlProperty()
Constructor.
Method Summary
voidaddConfigured(ResourceCollection a)
Set the source resource.
voidaddConfiguredXMLCatalog(XMLCatalog catalog)
add an XMLCatalog as a nested element; optional.
voidexecute()
Run the task.
protected booleangetCollapseAttributes()
StringgetDelimiter()
protected EntityResolvergetEntityResolver()
protected FilegetFile()
protected booleangetIncludeSementicAttribute()
protected booleangetKeeproot()
protected StringgetPrefix()
protected ResourcegetResource()
protected FilegetRootDirectory()
protected booleangetSemanticAttributes()
protected booleangetValidate()
voidinit()
Initializes the task.
ObjectprocessNode(Node node, String prefix, Object container)
Process the given node, adding any required attributes from this child node alone -- but not processing any children.
voidsetCollapseAttributes(boolean collapseAttributes)
flag to treat attributes as nested elements; optional, default false
voidsetDelimiter(String delimiter)
voidsetFile(File src)
The XML file to parse; required.
voidsetIncludeSemanticAttribute(boolean includeSemanticAttribute)
Include the semantic attribute name as part of the property name.
voidsetKeeproot(boolean keepRoot)
flag to include the xml root tag as a first value in the property name; optional, default is true
voidsetPrefix(String prefix)
the prefix to prepend to each property
voidsetRootDirectory(File rootDirectory)
The directory to use for resolving file references.
voidsetSemanticAttributes(boolean semanticAttributes)
Attribute to enable special handling of attributes - see ant manual.
voidsetSrcResource(Resource src)
The resource to pack; required.
voidsetValidate(boolean validate)
flag to validate the XML file; optional, default false
protected booleansupportsNonFileResources()
Whether this task can deal with non-file resources.

Constructor Detail

XmlProperty

public XmlProperty()
Constructor.

Method Detail

addConfigured

public void addConfigured(ResourceCollection a)
Set the source resource.

Parameters: a the resource to pack as a single element Resource collection.

addConfiguredXMLCatalog

public void addConfiguredXMLCatalog(XMLCatalog catalog)
add an XMLCatalog as a nested element; optional.

Parameters: catalog the XMLCatalog to use

execute

public void execute()
Run the task.

Throws: BuildException The exception raised during task execution.

UNKNOWN: validate the source file is valid before opening, print a better error message add a verbose level log message listing the name of the file being loaded

getCollapseAttributes

protected boolean getCollapseAttributes()

Returns: the collapse attributes attribute.

getDelimiter

public String getDelimiter()

getEntityResolver

protected EntityResolver getEntityResolver()

Returns: the xmlCatalog as the entityresolver.

getFile

protected File getFile()

Returns: the file attribute.

getIncludeSementicAttribute

protected boolean getIncludeSementicAttribute()

Returns: the include semantic attribute.

getKeeproot

protected boolean getKeeproot()

Returns: the keeproot attribute.

getPrefix

protected String getPrefix()

Returns: the prefix attribute.

getResource

protected Resource getResource()

Returns: the resource.

getRootDirectory

protected File getRootDirectory()

Returns: the root directory attribute.

getSemanticAttributes

protected boolean getSemanticAttributes()

Returns: the semantic attributes attribute.

getValidate

protected boolean getValidate()

Returns: the validate attribute.

init

public void init()
Initializes the task.

processNode

public Object processNode(Node node, String prefix, Object container)
Process the given node, adding any required attributes from this child node alone -- but not processing any children.

Parameters: node the XML Node to parse prefix A string to prepend to any properties that get added by this node. container Optionally, an object that a parent node generated that this node might belong to. For example, this node could be within a node that generated a Path.

Returns: the Object created by this node. Generally, this is either a String if this node resulted in setting an attribute, or a Path.

setCollapseAttributes

public void setCollapseAttributes(boolean collapseAttributes)
flag to treat attributes as nested elements; optional, default false

Parameters: collapseAttributes if true treat attributes as nested elements

setDelimiter

public void setDelimiter(String delimiter)

setFile

public void setFile(File src)
The XML file to parse; required.

Parameters: src the file to parse

setIncludeSemanticAttribute

public void setIncludeSemanticAttribute(boolean includeSemanticAttribute)
Include the semantic attribute name as part of the property name. Ignored if semanticAttributes is not set to true.

Parameters: includeSemanticAttribute if true include the sematic attribute name.

setKeeproot

public void setKeeproot(boolean keepRoot)
flag to include the xml root tag as a first value in the property name; optional, default is true

Parameters: keepRoot if true (default), include the xml root tag

setPrefix

public void setPrefix(String prefix)
the prefix to prepend to each property

Parameters: prefix the prefix to prepend to each property

setRootDirectory

public void setRootDirectory(File rootDirectory)
The directory to use for resolving file references. Ignored if semanticAttributes is not set to true.

Parameters: rootDirectory the directory.

setSemanticAttributes

public void setSemanticAttributes(boolean semanticAttributes)
Attribute to enable special handling of attributes - see ant manual.

Parameters: semanticAttributes if true enable the special handling.

setSrcResource

public void setSrcResource(Resource src)
The resource to pack; required.

Parameters: src resource to expand

setValidate

public void setValidate(boolean validate)
flag to validate the XML file; optional, default false

Parameters: validate if true validate the XML file, default false

supportsNonFileResources

protected boolean supportsNonFileResources()
Whether this task can deal with non-file resources.

This implementation returns true only if this task is <xmlproperty>. Any subclass of this class that also wants to support non-file resources needs to override this method. We need to do so for backwards compatibility reasons since we can't expect subclasses to support resources.

Returns: true for this task.

Since: Ant 1.7