Class 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
    • Constructor Summary

      Constructors 
      Constructor Description
      XmlTool()  
      XmlTool​(java.util.List<Node> nodes)  
      XmlTool​(Node node)  
    • 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/sole Node in the internal Node list for this instance, if that Node is an Element.
      java.util.Map<java.lang.String,​java.lang.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 Elements of all the current internally held nodes that are Elements 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​(java.lang.Object o)
      Converts the specified object to a String and calls find(String) with that.
      XmlTool find​(java.lang.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.
      XmlTool get​(java.lang.Number n)
      Returns an XmlTool that wraps the specified Node 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 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.
      java.lang.Object getName()
      Asks get(Object) for a "name" result.
      java.lang.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.
      java.lang.String getPath()
      Returns the XPath that identifies the first/sole Node represented by this instance.
      java.lang.String getText()
      Returns the concatenated text content of all the internally held nodes.
      boolean isEmpty()
      Returns true if there are no Nodes internally held by this instance.
      java.util.Iterator<XmlTool> iterator()
      Returns an Iterator that returns new XmlTool instances for each Node held internally by this instance.
      private void log​(java.lang.Object o, java.lang.Throwable t)  
      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 Elements of each of the Nodes 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 resulting Document as the root Node.
      XmlTool read​(java.lang.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​(java.lang.String file)
      Creates a URL from the string and passes it to read(URL).
      protected void read​(java.net.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​(Node node)
      Sets a singular root Node for this instance.
      int size()
      Returns the number of Nodes internally held by this instance.
      java.lang.String toString()
      If this instance has no XML Nodes, then this returns the result of super.toString().
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • LOG

        protected org.apache.velocity.runtime.log.Log LOG
      • nodes

        private java.util.List<Node> nodes
    • Constructor Detail

      • XmlTool

        public XmlTool()
      • XmlTool

        public XmlTool​(Node node)
      • XmlTool

        public XmlTool​(java.util.List<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​(Node node)
        Sets a singular root Node 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 a URL from the string and passes it to read(URL).
        Throws:
        java.lang.Exception
      • read

        protected void read​(java.net.URL url)
                     throws java.lang.Exception
        Reads, parses and creates a Document from the given URL and uses it as the root Node 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 resulting Document as the root Node.
        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 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​(java.lang.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 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 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 java.lang.Object getName()
        Asks get(Object) for a "name" result. If none, this will return the result of getNodeName().
      • getNodeName

        public java.lang.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 java.lang.String getPath()
        Returns the XPath that identifies the first/sole Node represented by this instance.
      • attr

        public java.lang.String attr​(java.lang.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 java.util.Map<java.lang.String,​java.lang.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 java.util.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​(java.lang.Number n)
        Returns an XmlTool that wraps the specified Node from this instance's internal Node list.
      • node

        public Node node()
        Returns the first/sole Node 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 calls find(String) with that.
      • find

        public XmlTool find​(java.lang.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 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 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 java.lang.Object