org.apache.velocity.tools.generic

## Class XmlTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.generic.XmlTool

All Implemented Interfaces:
  Serializable

    @DefaultKey(value="xml")
    public class XmlTool
    extends SafeConfig
    implements Serializable

Tool for reading/navigating XML files, with XPath expressions support.

Configuration parameters:

- `resource`=file or classpath resource
- `source`=URL

Here's a short example:

     XML file:
       <foo><bar>woogie</bar><a name="test"/></foo>

     Template:
       $foo.bar.text
       $foo.find('a')
       $foo.a.name

     Output:
       woogie
       <a name="test"/>
       test

     Configuration:
     <tools>
       <toolbox scope="application">
         <tool class="org.apache.velocity.tools.generic.XmlTool"
                  key="foo" source="doc.xml"/>
       </toolbox>
     </tools>

Note that this tool is included in the default GenericTools configuration under the key "xml". You can read but unless you set safeMode="false" for it, you will only be able to parse XML strings. Safe mode is on by default and blocks access to the `read(String)` method.

Since:
  VelocityTools 2.0
Version:
  $Revision: 1769055 $ $Date: 2006-11-27 10:49:37 -0800 (Mon, 27 Nov 2006) $
Author:
  Nathan Bubna, Claude Brisson
See Also:
  Serialized Form

### Nested Class Summary

Nested Classes
`static class` `XmlTool.NodeIterator` Iterator implementation that wraps a Node list iterator to return new XmlTool instances for each item in the wrapped iterator.s

### Field Summary

Fields
`protected ImportSupport` `importSupport` ImportSupport utility which provides underlying i/o

### Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

`LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`XmlTool()` Default constructor.
`XmlTool(List<Node> nodes)` Builds an XmlTool around a nodes list.
`XmlTool(Node node)` Builds an XmlTool around a node.

### Method Summary

All Methods Instance Methods Concrete Methods
`String` `attr(Object o)` Returns the value of the specified attribute for the first/sole `Node` in the internal Node list for this instance, if that Node is an `Element`.
`Map<String,String>` `attributes()` Returns a `Map` of all attributes for the first/sole `Node` held internally by this instance.
`XmlTool` `children()` Returns a new `XmlTool` instance that wraps all the child `Element`s of all the current internally held nodes that are `Element`s themselves.
`protected void` `configure(ValueParser values)` Configuration.
`XmlTool` `fetch(String url)` Reads and parses a remote or local URL
`XmlTool` `find(Object o)` Converts the specified object to a String and calls `find(String)` with that.
`XmlTool` `find(String xpath)` Performs an XPath selection on the current set of `Node`s held by this instance and returns a new `XmlTool` instance that wraps those results.
`XmlTool` `get(Number n)` Returns an `XmlTool` that wraps the specified `Node` from this instance's internal Node list.
`Object` `get(Object o)` This will first attempt to find an attribute with the specified name and return its value.
`XmlTool` `getFirst()` Returns an `XmlTool` that wraps only the first `Node` from this instance's internal Node list.
`XmlTool` `getLast()` Returns an `XmlTool` that wraps only the last `Node` from this instance's internal Node list.
`Object` `getName()` Asks `get(Object)` for a "name" result.
`String` `getNodeName()` Returns the name of the root node.
`XmlTool` `getParent()` Returns a new `XmlTool` instance that wraps the parent `Element` of the first/sole `Node` being wrapped by this instance.
`String` `getPath()` Returns the XPath that identifies the first/sole `Node` represented by this instance.
`String` `getText()` Returns the concatenated text content of all the internally held nodes.
`protected void` `initializeImportSupport(ValueParser config)` ImportSupport initialization
`boolean` `isEmpty()` Returns `true` if there are no `Node`s internally held by this instance.
`Iterator<XmlTool>` `iterator()` Returns an `Iterator` that returns new `XmlTool` instances for each `Node` held internally by this instance.
`Node` `node()` Returns the first/sole `Node` from this instance's internal Node list, if any.
`XmlTool` `parents()` Returns a new `XmlTool` instance that wraps the parent `Element`s of each of the `Node`s being wrapped by this instance.
`XmlTool` `parse(String xml)` Parses the given XML string and uses the resulting `Document` as the root `Node`.
`XmlTool` `read(String resource)` Reads and parses a local resource file
`protected void` `setRoot(Node node)` Sets a singular root `Node` for this instance.
`int` `size()` Returns the number of `Node`s internally held by this instance.
`String` `toString()` If this instance has no XML `Node`s, then this returns the result of `super.toString()`.

### Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

`configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

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

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Field Detail

#### importSupport

    protected transient ImportSupport importSupport

ImportSupport utility which provides underlying i/o

### Constructor Detail

#### XmlTool

    public XmlTool()

Default constructor.

#### XmlTool

    public XmlTool(Node node)

Builds an XmlTool around a node.

Parameters:
  `node` - target node

#### XmlTool

    public XmlTool(List<Node> nodes)

Builds an XmlTool around a nodes list.

Parameters:
  `nodes` - nodes list

### Method Detail

#### initializeImportSupport

    protected void initializeImportSupport(ValueParser config)

ImportSupport initialization

Parameters:
  `config` - configuration values

#### configure

    protected void configure(ValueParser values)

Configuration.

Overrides:
  `configure` in class `SafeConfig`
Parameters:
  `values` - configuration values

#### setRoot

    protected void setRoot(Node node)

Sets a singular root `Node` for this instance.

Parameters:
  `node` - new root node

#### parse

    public XmlTool parse(String xml)

Parses the given XML string and uses the resulting `Document` as the root `Node`.

Parameters:
  `xml` - XML string
Returns:
  new XmlTool

#### read

    public XmlTool read(String resource)

Reads and parses a local resource file

Parameters:
  `resource` - resource path
Returns:
  new XmlTool

#### fetch

    public XmlTool fetch(String url)

Reads and parses a remote or local URL

Parameters:
  `url` - resource URL
Returns:
  new XmlTool

#### get

    public Object get(Object o)

This will first attempt to find an attribute with the specified name and return its value. If no such attribute exists or its value is `null`, this will attempt to convert the given value to a `Number` and get the result of `get(Number)`. If the number conversion fails, then this will convert the object to a string. If that string does not contain a '/', it appends the result of `getPath()` and a '/' to the front of it. Finally, it delegates the string to the `find(String)` method and returns the result of that.

Parameters:
  `o` - attribute name, number, xpath relative expression
Returns:
  found value or null

#### getName

    public Object getName()

Asks `get(Object)` for a "name" result. If none, this will return the result of `getNodeName()`.

Returns:
  found value or null

#### getNodeName

    public String getNodeName()

Returns the name of the root node. If the internal `Node` list has more than one `Node`, it will only return the name of the first node in the list.

Returns:
  node name

#### getPath

    public String getPath()

Returns the XPath that identifies the first/sole `Node` represented by this instance.

Returns:
  xpath node path

#### attr

    public String attr(Object o)

Returns the value of the specified attribute for the first/sole `Node` in the internal Node list for this instance, if that Node is an `Element`. If it is a non-Element node type or there is no value for that attribute in this element, then this will return `null`.

Parameters:
  `o` - attribute name
Returns:
  attribute value or null

#### attributes

    public Map<String,String> attributes()

Returns a `Map` of all attributes for the first/sole `Node` held internally by this instance. If that Node is not an `Element`, this will return null.

Returns:
  attributes map

#### isEmpty

    public boolean isEmpty()

Returns `true` if there are no `Node`s internally held by this instance.

Returns:
  whether the set of current nodes is empty

#### size

    public int size()

Returns the number of `Node`s internally held by this instance.

Returns:
  the size of the set of current nodes

#### iterator

    public Iterator<XmlTool> iterator()

Returns an `Iterator` that returns new `XmlTool` instances for each `Node` held internally by this instance.

Returns:
  an iterator on wrappers of current nodes or null

#### getFirst

    public XmlTool getFirst()

Returns an `XmlTool` that wraps only the first `Node` from this instance's internal Node list.

Returns:
  a wrapper on the first node or null

#### getLast

    public XmlTool getLast()

Returns an `XmlTool` that wraps only the last `Node` from this instance's internal Node list.

Returns:
  a wrapper on the last node or null

#### get

    public XmlTool get(Number n)

Returns an `XmlTool` that wraps the specified `Node` from this instance's internal Node list.

Parameters:
  `n` - node index in current nodes list
Returns:
  a wrapper on the nth node or null

#### node

    public Node node()

Returns the first/sole `Node` from this instance's internal Node list, if any.

Returns:
  the unwrapped first node or null

#### find

    public XmlTool find(Object o)

Converts the specified object to a String and calls `find(String)` with that.

Parameters:
  `o` - xpath to search
Returns:
  a wrapper on found nodes or null

#### find

    public XmlTool find(String xpath)

Performs an XPath selection on the current set of `Node`s held by this instance and returns a new `XmlTool` instance that wraps those results. If the specified value is null or this instance does not currently hold any nodes, then this will return `null`. If the specified value, when converted to a string, does not contain a '/' character, then it has "//" prepended to it. This means that a call to `$xml.find("a")` is equivalent to calling `$xml.find("//a")`. The full range of XPath selectors is supported here.

Parameters:
  `xpath` - xpath to search
Returns:
  a wrapper on found nodes or null

#### getParent

    public XmlTool getParent()

Returns a new `XmlTool` instance that wraps the parent `Element` of the first/sole `Node` being wrapped by this instance.

Returns:
  wrapper on the parent of the first node or null

#### parents

    public XmlTool parents()

Returns a new `XmlTool` instance that wraps the parent `Element`s of each of the `Node`s being wrapped by this instance. This does not return all ancestors, just the immediate parents.

Returns:
  a wrapper on the set of parents nodes or null

#### children

    public XmlTool children()

Returns a new `XmlTool` instance that wraps all the child `Element`s of all the current internally held nodes that are `Element`s themselves.

Returns:
  a wrapper on the children of current nodes

#### getText

    public String getText()

Returns the concatenated text content of all the internally held nodes. Obviously, this is most useful when only one node is held.

Returns:
  text of current nodes or null

#### toString

    public String toString()

If this instance has no XML `Node`s, then this returns the result of `super.toString()`. Otherwise, it returns the XML (as a string) of all the internally held nodes that are not `Attr`ibutes. For attributes, only the value is used.

Overrides:
  `toString` in class `Object`
Returns:
  XML string of current nodes or null