XmlProperty (Apache Ant API)
Date: 2016-08-23

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:
    java.lang.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.

- - ### Field Summary

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlProperty()` Constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addConfigured(ResourceCollection a)` Set the source resource.
    `void` | `addConfiguredXMLCatalog(XMLCatalog catalog)` add an XMLCatalog as a nested element; optional.
    `void` | `execute()` Run the task.
    `protected boolean` | `getCollapseAttributes()`
    `java.lang.String` | `getDelimiter()` Get the current delimiter.
    `protected org.xml.sax.EntityResolver` | `getEntityResolver()`
    `protected java.io.File` | `getFile()`
    `protected boolean` | `getIncludeSementicAttribute()`
    `protected boolean` | `getKeeproot()`
    `protected java.lang.String` | `getPrefix()`
    `protected Resource` | `getResource()`
    `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` | `setDelimiter(java.lang.String delimiter)` Sets a new delimiter.
    `void` | `setFile(java.io.File src)` The XML file to parse; required.
    `void` | `setIncludeSemanticAttribute(boolean includeSemanticAttribute)` Include the semantic attribute name as part of the property name.
    `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)` The directory to use for resolving file references.
    `void` | `setSemanticAttributes(boolean semanticAttributes)` Attribute to enable special handling of attributes - see ant manual.
    `void` | `setSrcResource(Resource src)` The resource to pack; required.
    `void` | `setValidate(boolean validate)` flag to validate the XML file; optional, default false
    `protected boolean` | `supportsNonFileResources()` Whether this task can deal with non-file resources.

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

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

    - #### getEntityResolver

          protected org.xml.sax.EntityResolver getEntityResolver()

      Returns:
        the xmlCatalog as the entityresolver.

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

    - #### setSrcResource

          public void setSrcResource(Resource src)

      The resource to pack; required.
      Parameters:
        `src` - resource to expand

    - #### addConfigured

          public void addConfigured(ResourceCollection a)

      Set the source resource.
      Parameters:
        `a` - the resource to pack as a single element Resource collection.

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

      Attribute to enable special handling of attributes - see ant manual.
      Parameters:
        `semanticAttributes` - if true enable the special handling.

    - #### setRootDirectory

          public void setRootDirectory(java.io.File rootDirectory)

      The directory to use for resolving file references. Ignored if semanticAttributes is not set to true.
      Parameters:
        `rootDirectory` - the directory.

    - #### 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 semantic attribute name.

    - #### addConfiguredXMLCatalog

          public void addConfiguredXMLCatalog(XMLCatalog catalog)

      add an XMLCatalog as a nested element; optional.
      Parameters:
        `catalog` - the XMLCatalog to use

    - #### getFile

          protected java.io.File getFile()

      Returns:
        the file attribute.

    - #### getResource

          protected Resource getResource()

      Returns:
        the resource.

    - #### getPrefix

          protected java.lang.String getPrefix()

      Returns:
        the prefix attribute.

    - #### getKeeproot

          protected boolean getKeeproot()

      Returns:
        the keeproot attribute.

    - #### getValidate

          protected boolean getValidate()

      Returns:
        the validate attribute.

    - #### getCollapseAttributes

          protected boolean getCollapseAttributes()

      Returns:
        the collapse attributes attribute.

    - #### getSemanticAttributes

          protected boolean getSemanticAttributes()

      Returns:
        the semantic attributes attribute.

    - #### getRootDirectory

          protected java.io.File getRootDirectory()

      Returns:
        the root directory attribute.

    - #### getIncludeSementicAttribute

          protected boolean getIncludeSementicAttribute()

      Returns:
        the include semantic attribute.

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

    - #### getDelimiter

          public java.lang.String getDelimiter()

      Get the current delimiter.
      Returns:
        delimiter

    - #### setDelimiter

          public void setDelimiter(java.lang.String delimiter)

      Sets a new delimiter.
      Parameters:
        `delimiter` - new value
      Since:
        Ant 1.7.1