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

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:


Field Summary
 
Fields inherited from class org.apache.tools.ant.Task
description, location, target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
project
 
Constructor Summary
XmlProperty()
          Constructor.
 
Method Summary
 void execute()
          Run the task.
protected  boolean getCollapseAttributes()
           
protected  java.io.File getFile()
           
protected  boolean getIncludeSementicAttribute()
           
protected  boolean getKeeproot()
           
protected  java.lang.String getPrefix()
           
protected  java.io.File getRootDirectory()
           
protected  boolean getSemanticAttributes()
           
protected  boolean getValidate()
           
 void init()
          Initializes the task.
 java.lang.Object processNode(org.w3c.dom.Node node, java.lang.String prefix, java.lang.Object container)
          Process the given node, adding any required attributes from this child node alone -- but not processing any children.
 void setCollapseAttributes(boolean collapseAttributes)
          flag to treat attributes as nested elements; optional, default false
 void setFile(java.io.File src)
          The XML file to parse; required.
 void setIncludeSemanticAttribute(boolean includeSemanticAttribute)
           
 void setKeeproot(boolean keepRoot)
          flag to include the xml root tag as a first value in the property name; optional, default is true
 void setPrefix(java.lang.String prefix)
          the prefix to prepend to each property
 void setRootDirectory(java.io.File rootDirectory)
           
 void setSemanticAttributes(boolean semanticAttributes)
           
 void setValidate(boolean validate)
          flag to validate the XML file; optional, default false
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlProperty

public XmlProperty()
Constructor.

Method Detail

init

public void init()
Initializes the task.

Overrides:
init in class Task

execute

public void execute()
             throws BuildException
Run the task.

Overrides:
execute in class Task
Throws:
BuildException - The exception raised during task execution.
To do:
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

processNode

public java.lang.Object processNode(org.w3c.dom.Node node,
                                    java.lang.String prefix,
                                    java.lang.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.

setFile

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

Parameters:
src - the file to parse

setPrefix

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

Parameters:
prefix - the prefix to prepend to each property

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

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

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

setSemanticAttributes

public void setSemanticAttributes(boolean semanticAttributes)

setRootDirectory

public void setRootDirectory(java.io.File rootDirectory)

setIncludeSemanticAttribute

public void setIncludeSemanticAttribute(boolean includeSemanticAttribute)

getFile

protected java.io.File getFile()

getPrefix

protected java.lang.String getPrefix()

getKeeproot

protected boolean getKeeproot()

getValidate

protected boolean getValidate()

getCollapseAttributes

protected boolean getCollapseAttributes()

getSemanticAttributes

protected boolean getSemanticAttributes()

getRootDirectory

protected java.io.File getRootDirectory()

getIncludeSementicAttribute

protected boolean getIncludeSementicAttribute()


Copyright © 2000-2004 Apache Software Foundation. All Rights Reserved.