Package 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("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:

  • Field Details

    • importSupport

      protected transient ImportSupport importSupport
      ImportSupport utility which provides underlying i/o

  • Constructor Details

    • 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 Details

    • 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

      @Deprecated public String getPath()
      Deprecated.
      use getNodePath()

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

      This function is deprecated. In future versions, this function will first try get("path") before resorting to getNodePath().

      Returns:
      xpath node path

    • getNodePath

      public String getNodePath()
      Returns the XPath that identifies the first/sole Node represented by this instance.
      Returns:
      xpath node path
      Since:
      3.2

    • 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 Nodes internally held by this instance.
      Returns:
      whether the set of current nodes is empty

    • size

      public int size()
      Returns the number of Nodes 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 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.
      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 Elements of each of the Nodes 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 Elements of all the current internally held nodes that are Elements 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 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
      Returns:
      XML string of current nodes or null