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

```
@DefaultKey("xml")
public class XmlTool
extends SafeConfig
```
Tool for reading/navigating XML files. This uses dom4j under the covers to provide complete XPath support for traversing XML files.

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" file="doc.xml"/>
   </toolbox>
 </tools>
 
```
Note that this tool is included in the default GenericTools configuration under the key "xml", 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(Object) method.
Since:

VelocityTools 2.0

Version:

$Revision$ $Date: 2006-11-27 10:49:37 -0800 (Mon, 27 Nov 2006) $

Author:

Nathan Bubna

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`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
Modifier and Type Field Description

static String FILE_KEY

protected org.apache.velocity.runtime.log.Log LOG
- Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
  LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

Constructors
Constructor Description

XmlTool()

XmlTool(List<org.dom4j.Node> nodes)

XmlTool(org.dom4j.Node node)

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`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 parser)`	Looks for the "file" parameter and automatically uses `read(String)` to parse the file and set the resulting `Document` as the root node for this instance.
`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.
`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.
`org.dom4j.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(Object o)`	This accepts XML in form.
`protected void`	`parse(String xml)`	Parses the given XML string and uses the resulting `Document` as the root `Node`.
`XmlTool`	`read(Object o)`	If safe mode is explicitly turned off for this tool, then this will accept either a `URL` or the string representation thereof.
`protected void`	`read(String file)`	Creates a `URL` from the string and passes it to `read(URL)`.
`protected void`	`read(URL url)`	Reads, parses and creates a `Document` from the given `URL` and uses it as the root `Node` for this instance.
`protected void`	`setRoot(org.dom4j.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, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - FILE_KEY
```
public static final String FILE_KEY
```
    See Also:
    
    Constant Field Values
  - LOG
```
protected org.apache.velocity.runtime.log.Log LOG
```
- Constructor Detail
  - XmlTool
```
public XmlTool()
```
  - XmlTool
```
public XmlTool(org.dom4j.Node node)
```
  - XmlTool
```
public XmlTool(List<org.dom4j.Node> nodes)
```
- Method Detail
  - configure
```
protected void configure(ValueParser parser)
```
    Looks for the "file" parameter and automatically uses read(String) to parse the file and set the resulting Document as the root node for this instance.
    
    Overrides:
    
    configure in class SafeConfig
  - setRoot
```
protected void setRoot(org.dom4j.Node node)
```
    Sets a singular root Node for this instance.
  - read
```
protected void read(String file)
             throws Exception
```
    Creates a URL from the string and passes it to read(URL).
    
    Throws:
    
    Exception
  - read
```
protected void read(URL url)
             throws Exception
```
    Reads, parses and creates a Document from the given URL and uses it as the root Node for this instance.
    
    Throws:
    
    Exception
  - parse
```
protected void parse(String xml)
              throws Exception
```
    Parses the given XML string and uses the resulting Document as the root Node.
    
    Throws:
    
    Exception
  - read
```
public XmlTool read(Object o)
```
    If safe mode is explicitly turned off for this tool, then this will accept either a URL or the string representation thereof. If valid, it will return a new XmlTool instance with that document as the root Node. If reading the URL or parsing its content fails or if safe mode is on (the default), this will return null.
  - parse
```
public XmlTool parse(Object o)
```
    This accepts XML in form. If the XML is valid, it will return a new XmlTool instance with the resulting XML document as the root Node. If parsing the content fails, this will return null.
  - 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.
  - getName
```
public Object getName()
```
    Asks get(Object) for a "name" result. If none, this will return the result of getNodeName().
  - 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.
  - getPath
```
public String getPath()
```
    Returns the XPath that identifies the first/sole Node represented by this instance.
  - 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.
  - 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.
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if there are no Nodes internally held by this instance.
  - size
```
public int size()
```
    Returns the number of Nodes internally held by this instance.
  - iterator
```
public Iterator<XmlTool> iterator()
```
    Returns an Iterator that returns new XmlTool instances for each Node held internally by this instance.
  - getFirst
```
public XmlTool getFirst()
```
    Returns an XmlTool that wraps only the first Node from this instance's internal Node list.
  - getLast
```
public XmlTool getLast()
```
    Returns an XmlTool that wraps only the last Node from this instance's internal Node list.
  - get
```
public XmlTool get(Number n)
```
    Returns an XmlTool that wraps the specified Node from this instance's internal Node list.
  - node
```
public org.dom4j.Node node()
```
    Returns the first/sole Node from this instance's internal Node list, if any.
  - find
```
public XmlTool find(Object o)
```
    Converts the specified object to a String and calls find(String) with that.
  - find
```
public XmlTool find(String xpath)
```
    Performs an XPath selection on the current set of Nodes 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.
  - getParent
```
public XmlTool getParent()
```
    Returns a new XmlTool instance that wraps the parent Element of the first/sole Node being wrapped by this instance.
  - parents
```
public XmlTool parents()
```
    Returns a new XmlTool instance that wraps the parent Elements of each of the Nodes being wrapped by this instance. This does not return all ancestors, just the immediate parents.
  - children
```
public XmlTool children()
```
    Returns a new XmlTool instance that wraps all the child Elements of all the current internally held nodes that are Elements themselves.
  - 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.
  - toString
```
public String toString()
```
    If this instance has no XML Nodes, 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 Attributes. For attributes, only the value is used.
    
    Overrides:
    
    toString in class Object

Modifier and Type	Field	Description
`static String`	`FILE_KEY`
`protected org.apache.velocity.runtime.log.Log`	`LOG`

Constructor	Description
`XmlTool()`
`XmlTool(List<org.dom4j.Node> nodes)`
`XmlTool(org.dom4j.Node node)`

Class XmlTool

Nested Class Summary

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

FILE_KEY

LOG

Constructor Detail

XmlTool

XmlTool

XmlTool

Method Detail

configure

setRoot

read

read

parse

read

parse

get

getName

getNodeName

getPath

attr

attributes

isEmpty

size

iterator

getFirst

getLast

get

node

find

find

getParent

parents

children

getText

toString