Class XmlTool
- 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: 749731 $ $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 java.lang.String
FILE_KEY
protected org.apache.velocity.runtime.log.Log
LOG
private java.util.List<Node>
nodes
-
Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.String
attr(java.lang.Object o)
Returns the value of the specified attribute for the first/soleNode
in the internal Node list for this instance, if that Node is anElement
.java.util.Map<java.lang.String,java.lang.String>
attributes()
Returns aMap
of all attributes for the first/soleNode
held internally by this instance.XmlTool
children()
Returns a newXmlTool
instance that wraps all the childElement
s of all the current internally held nodes that areElement
s themselves.protected void
configure(ValueParser parser)
Looks for the "file" parameter and automatically usesread(String)
to parse the file and set the resultingDocument
as the root node for this instance.XmlTool
find(java.lang.Object o)
Converts the specified object to a String and callsfind(String)
with that.XmlTool
find(java.lang.String xpath)
Performs an XPath selection on the current set ofNode
s held by this instance and returns a newXmlTool
instance that wraps those results.XmlTool
get(java.lang.Number n)
Returns anXmlTool
that wraps the specifiedNode
from this instance's internal Node list.java.lang.Object
get(java.lang.Object o)
This will first attempt to find an attribute with the specified name and return its value.XmlTool
getFirst()
Returns anXmlTool
that wraps only the firstNode
from this instance's internal Node list.XmlTool
getLast()
Returns anXmlTool
that wraps only the lastNode
from this instance's internal Node list.java.lang.Object
getName()
Asksget(Object)
for a "name" result.java.lang.String
getNodeName()
Returns the name of the root node.XmlTool
getParent()
Returns a newXmlTool
instance that wraps the parentElement
of the first/soleNode
being wrapped by this instance.java.lang.String
getPath()
Returns the XPath that identifies the first/soleNode
represented by this instance.java.lang.String
getText()
Returns the concatenated text content of all the internally held nodes.boolean
isEmpty()
Returnstrue
if there are noNode
s internally held by this instance.java.util.Iterator<XmlTool>
iterator()
Returns anIterator
that returns newXmlTool
instances for eachNode
held internally by this instance.private void
log(java.lang.Object o, java.lang.Throwable t)
Node
node()
Returns the first/soleNode
from this instance's internal Node list, if any.XmlTool
parents()
Returns a newXmlTool
instance that wraps the parentElement
s of each of theNode
s being wrapped by this instance.XmlTool
parse(java.lang.Object o)
This accepts XML in form.protected void
parse(java.lang.String xml)
Parses the given XML string and uses the resultingDocument
as the rootNode
.XmlTool
read(java.lang.Object o)
If safe mode is explicitly turned off for this tool, then this will accept either aURL
or the string representation thereof.protected void
read(java.lang.String file)
Creates aURL
from the string and passes it toread(URL)
.protected void
read(java.net.URL url)
Reads, parses and creates aDocument
from the givenURL
and uses it as the rootNode
for this instance.protected void
setRoot(Node node)
Sets a singular rootNode
for this instance.int
size()
Returns the number ofNode
s internally held by this instance.java.lang.String
toString()
If this instance has no XMLNode
s, then this returns the result ofsuper.toString()
.-
Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
-
-
-
-
Field Detail
-
FILE_KEY
public static final java.lang.String FILE_KEY
- See Also:
- Constant Field Values
-
LOG
protected org.apache.velocity.runtime.log.Log LOG
-
nodes
private java.util.List<Node> nodes
-
-
Method Detail
-
configure
protected void configure(ValueParser parser)
Looks for the "file" parameter and automatically usesread(String)
to parse the file and set the resultingDocument
as the root node for this instance.- Overrides:
configure
in classSafeConfig
-
setRoot
protected void setRoot(Node node)
Sets a singular rootNode
for this instance.
-
log
private void log(java.lang.Object o, java.lang.Throwable t)
-
read
protected void read(java.lang.String file) throws java.lang.Exception
Creates aURL
from the string and passes it toread(URL)
.- Throws:
java.lang.Exception
-
read
protected void read(java.net.URL url) throws java.lang.Exception
Reads, parses and creates aDocument
from the givenURL
and uses it as the rootNode
for this instance.- Throws:
java.lang.Exception
-
parse
protected void parse(java.lang.String xml) throws java.lang.Exception
Parses the given XML string and uses the resultingDocument
as the rootNode
.- Throws:
java.lang.Exception
-
read
public XmlTool read(java.lang.Object o)
If safe mode is explicitly turned off for this tool, then this will accept either aURL
or the string representation thereof. If valid, it will return a newXmlTool
instance with that document as the rootNode
. If reading the URL or parsing its content fails or if safe mode is on (the default), this will returnnull
.
-
parse
public XmlTool parse(java.lang.Object o)
This accepts XML in form. If the XML is valid, it will return a newXmlTool
instance with the resulting XML document as the rootNode
. If parsing the content fails, this will returnnull
.
-
get
public java.lang.Object get(java.lang.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 isnull
, this will attempt to convert the given value to aNumber
and get the result ofget(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 ofgetPath()
and a '/' to the front of it. Finally, it delegates the string to thefind(String)
method and returns the result of that.
-
getName
public java.lang.Object getName()
Asksget(Object)
for a "name" result. If none, this will return the result ofgetNodeName()
.
-
getNodeName
public java.lang.String getNodeName()
Returns the name of the root node. If the internalNode
list has more than oneNode
, it will only return the name of the first node in the list.
-
getPath
public java.lang.String getPath()
Returns the XPath that identifies the first/soleNode
represented by this instance.
-
attr
public java.lang.String attr(java.lang.Object o)
Returns the value of the specified attribute for the first/soleNode
in the internal Node list for this instance, if that Node is anElement
. If it is a non-Element node type or there is no value for that attribute in this element, then this will returnnull
.
-
attributes
public java.util.Map<java.lang.String,java.lang.String> attributes()
Returns aMap
of all attributes for the first/soleNode
held internally by this instance. If that Node is not anElement
, this will return null.
-
isEmpty
public boolean isEmpty()
Returnstrue
if there are noNode
s internally held by this instance.
-
size
public int size()
Returns the number ofNode
s internally held by this instance.
-
iterator
public java.util.Iterator<XmlTool> iterator()
Returns anIterator
that returns newXmlTool
instances for eachNode
held internally by this instance.
-
getFirst
public XmlTool getFirst()
Returns anXmlTool
that wraps only the firstNode
from this instance's internal Node list.
-
getLast
public XmlTool getLast()
Returns anXmlTool
that wraps only the lastNode
from this instance's internal Node list.
-
get
public XmlTool get(java.lang.Number n)
Returns anXmlTool
that wraps the specifiedNode
from this instance's internal Node list.
-
node
public Node node()
Returns the first/soleNode
from this instance's internal Node list, if any.
-
find
public XmlTool find(java.lang.Object o)
Converts the specified object to a String and callsfind(String)
with that.
-
find
public XmlTool find(java.lang.String xpath)
Performs an XPath selection on the current set ofNode
s held by this instance and returns a newXmlTool
instance that wraps those results. If the specified value is null or this instance does not currently hold any nodes, then this will returnnull
. 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 newXmlTool
instance that wraps the parentElement
of the first/soleNode
being wrapped by this instance.
-
parents
public XmlTool parents()
Returns a newXmlTool
instance that wraps the parentElement
s of each of theNode
s being wrapped by this instance. This does not return all ancestors, just the immediate parents.
-
children
public XmlTool children()
Returns a newXmlTool
instance that wraps all the childElement
s of all the current internally held nodes that areElement
s themselves.
-
getText
public java.lang.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 java.lang.String toString()
If this instance has no XMLNode
s, then this returns the result ofsuper.toString()
. Otherwise, it returns the XML (as a string) of all the internally held nodes that are notAttribute
s. For attributes, only the value is used.- Overrides:
toString
in classjava.lang.Object
-
-