@DefaultKey(value="xml") public class XmlTool extends SafeConfig implements Serializable
Tool for reading/navigating XML files. This uses dom4j under the covers to provide complete XPath support for traversing XML files.
Configuration parameters:
resource
=file or classpath resourcesource
=URLHere'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.
Modifier and Type | Class and 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
|
Modifier and Type | Field and Description |
---|---|
protected ImportSupport |
importSupport
ImportSupport utility which provides underlying i/o
|
LOCK_CONFIG_KEY, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY
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.
|
Modifier and Type | Method and Description |
---|---|
String |
attr(Object o)
|
Map<String,String> |
attributes()
|
XmlTool |
children()
|
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)
|
XmlTool |
get(Number n)
|
Object |
get(Object o)
This will first attempt to find an attribute with the
specified name and return its value.
|
XmlTool |
getFirst()
|
XmlTool |
getLast()
|
Object |
getName()
Asks
get(Object) for a "name" result. |
String |
getNodeName()
Returns the name of the root node.
|
XmlTool |
getParent()
|
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()
|
Node |
node()
Returns the first/sole
Node from this
instance's internal Node list, if any. |
XmlTool |
parents()
|
XmlTool |
parse(String xml)
|
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() . |
configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
protected transient ImportSupport importSupport
public XmlTool()
public XmlTool(Node node)
node
- target nodeprotected void initializeImportSupport(ValueParser config)
config
- configuration valuesprotected void configure(ValueParser values)
configure
in class SafeConfig
values
- configuration valuesprotected void setRoot(Node node)
Node
for this instance.node
- new root nodepublic XmlTool read(String resource)
resource
- resource pathpublic XmlTool fetch(String url)
url
- resource URLpublic Object get(Object o)
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.o
- attribute name, number, xpath relative expressionpublic Object getName()
get(Object)
for a "name" result.
If none, this will return the result of getNodeName()
.public String getNodeName()
Node
list has more than one Node
, it will only return the name
of the first node in the list.public String getPath()
Node
represented by this instance.public String attr(Object o)
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
.o
- attribute namepublic Map<String,String> attributes()
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.public boolean isEmpty()
true
if there are no Node
s internally held
by this instance.public int size()
Node
s internally held by this instance.public Iterator<XmlTool> iterator()
Iterator
that returns new XmlTool
instances for each Node
held internally by this instance.public XmlTool getFirst()
public XmlTool getLast()
public XmlTool get(Number n)
n
- node index in current nodes listpublic Node node()
Node
from this
instance's internal Node list, if any.public XmlTool find(Object o)
find(String)
with that.o
- xpath to searchpublic XmlTool find(String xpath)
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.xpath
- xpath to searchpublic XmlTool getParent()
XmlTool
instance that wraps
the parent Element
of the first/sole Node
being wrapped by this instance.public XmlTool parents()
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.public XmlTool children()
XmlTool
instance that wraps all the
child Element
s of all the current internally held nodes
that are Element
s themselves.public String getText()
public String toString()
Copyright © 2002–2018 The Apache Software Foundation. All rights reserved.