Package com.jcabi.xml

Interface XML

All Known Implementing Classes:
SaxonDocument, StrictXML, XMLDocument
public interface XML
XML document.

Set of convenient XML manipulations: 

 XML xml = new XMLDocument(content);
 for (XML employee : xml.nodes("//Employee")) {
   String name = employee.xpath("name/text()").get(0);
   // ...
 }

You can always get DOM node out of this abstraction using node() method.

toString() must produce a full XML.

Implementation of this interface must be immutable and thread-safe.

In most cases, you can use the XMLDocument implementation. It implements all required features and will be sufficient for most practical tasks. The only problem with that implementation is that it uses javax.xml classes under the hood. The issue with the default java implementation is that it only supports XPath 1.0. If you require XPath 2.0 support and beyond, you can use the Saxon implementation of XML - SaxonDocument. It is based on the Saxon library and supports XPath 2.0 and higher. You can read more about Java XPath versioning problems in the following threads:

Since:
0.1
See Also:
Suppressed Checkstyle violations:
AbbreviationAsWordInNameCheck (5 lines)

  • Method Summary

    Modifier and Type
    Method
    Description
    XML
    merge(NamespaceContext context)
    Append this namespace context to the existing one.
    Node
    node()
    Retrieve DOM node, represented by this wrapper.
    List<XML>
    nodes(String query)
    Retrieve DOM nodes from the XML response.
    XML
    registerNs(String prefix, Object uri)
    Register additional namespace prefix for XPath.
    List<String>
    xpath(String query)
    Find and return text elements or attributes matched by XPath address.

  • Method Details

    • xpath

      List<String> xpath(String query)
      Find and return text elements or attributes matched by XPath address.

      The XPath query should point to text elements or attributes in the XML document. If any nodes of different types (elements, comments, etc.) are found in result node list - a RuntimeException will be thrown.

      Alternatively, the XPath query can be a function or expression that returns a single value instead of pointing to a set of nodes. In this case, the result will be a List containing a single String, the content of which is the result of the evaluation. If the expression result is not a String, it will be converted to a String representation and returned as such. For example, a document containing three <a> elements, the input query "count(//a)", will return a singleton List with a single string value "3".

      This is a convenient method, which is used (according to our experience) in 95% of all cases. Usually you don't need to get anything else but a text value of some node or an attribute. And in most cases you are interested to get just the first value (use xpath(..).get(0)). But when/if you need to get more than just a plain text - use nodes(String).

      The List returned will throw IndexOutOfBoundsException if you try to access a node which wasn't found by this XPath query.

      An IllegalArgumentException is thrown if the parameter passed is not a valid XPath expression.

      Parameters:
      query - The XPath query
      Returns:
      The list of string values (texts) or single function result

    • nodes

      List<XML> nodes(String query)
      Retrieve DOM nodes from the XML response.

      The List returned will throw IndexOutOfBoundsException if you try to access a node which wasn't found by this XPath query.

      An IllegalArgumentException is thrown if the parameter passed is not a valid XPath expression.

      Parameters:
      query - The XPath query
      Returns:
      Collection of DOM nodes

    • registerNs

      XML registerNs(String prefix, Object uri)
      Register additional namespace prefix for XPath.

      For example: 

       String name = new XMLDocument("...")
   .registerNs("ns1", "http://example.com")
   .registerNs("foo", "http://example.com/foo")
   .xpath("/ns1:root/foo:name/text()")
   .get(0);

      A number of standard namespaces are registered by default in instances of XML. Their full list is in XMLDocument(String).

      If a namespace prefix is already registered an IllegalArgumentException will be thrown.

      Parameters:
      prefix - The XPath prefix to register
      uri - Namespace URI
      Returns:
      A new XML document, with this additional namespace registered

    • merge

      XML merge(NamespaceContext context)
      Append this namespace context to the existing one.

      The existing context (inside this object) and the new one provided will be merged together. The existing context will be have higher priority.

      Parameters:
      context - The context to append
      Returns:
      A new XML document, with a merged context on board

    • node

      Node node()
      Retrieve DOM node, represented by this wrapper.
      Returns:
      DOM node