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.
addConfigured
public void addConfigured(ResourceCollection a)
Set the source resource.
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.
catalog
- the XMLCatalog to use
execute
public void execute()
throws BuildException
Run the task.
- execute in interface Task
- 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()
- the collapse attributes attribute.
getEntityResolver
protected EntityResolver getEntityResolver()
- the xmlCatalog as the entityresolver.
getFile
protected File getFile()
getIncludeSementicAttribute
protected boolean getIncludeSementicAttribute()
- the include semantic attribute.
getKeeproot
protected boolean getKeeproot()
getPrefix
protected String getPrefix()
getResource
protected Resource getResource()
getRootDirectory
protected File getRootDirectory()
- the root directory attribute.
getSemanticAttributes
protected boolean getSemanticAttributes()
- the semantic attributes attribute.
getValidate
protected boolean getValidate()
init
public void init()
Initializes the task.
- init in interface 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.
node
- the XML Node to parseprefix
- 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.
- 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
collapseAttributes
- if true treat attributes as nested elements
setFile
public void setFile(File src)
The XML file to parse; required.
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.
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
keepRoot
- if true (default), include the xml root tag
setPrefix
public void setPrefix(String prefix)
the prefix to prepend to each property
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.
rootDirectory
- the directory.
setSemanticAttributes
public void setSemanticAttributes(boolean semanticAttributes)
Attribute to enable special handling of attributes - see ant manual.
semanticAttributes
- if true enable the special handling.
setSrcResource
public void setSrcResource(Resource src)
The resource to pack; required.
setValidate
public void setValidate(boolean validate)
flag to validate the XML file; optional, default false
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.