Package com.jcabi.xml

Class SaxonDocument

  • All Implemented Interfaces:
    XML
    public final class SaxonDocument
extends Object
implements XML
    Saxon XML document.

    Objects of this class are immutable, but NOT thread-safe.

    Since:
    0.28

    • Constructor Detail

      • SaxonDocument

        public SaxonDocument​(String text)
        Public constructor from XML as string text.
        Parameters:
        text - XML document body.
        Since:
        0.28.0

      • SaxonDocument

        public SaxonDocument​(byte[] data)
        Public constructor from XML as byte array.
        Parameters:
        data - XML document body as byte array.
        Since:
        0.28.1

      • SaxonDocument

        public SaxonDocument​(Path path)
        Public constructor from XML saved in a filesystem.
        Parameters:
        path - Path to XML file in a filesystem.
        Since:
        0.28.1

      • SaxonDocument

        public SaxonDocument​(File file)
        Public constructor from XML saved in a filesystem.
        Parameters:
        file - XML file in a filesystem.
        Since:
        0.28.1

      • SaxonDocument

        public SaxonDocument​(URL url)
              throws IOException
        Public constructor from XML reached by URL.
        Parameters:
        url - URL of XML document.
        Throws:
        IOException - If fails.
        Since:
        0.28.1

      • SaxonDocument

        public SaxonDocument​(URI uri)
              throws IOException
        Public constructor from XML reached by URI.
        Parameters:
        uri - URI of XML document.
        Throws:
        IOException - If fails.
        Since:
        0.28.1

      • SaxonDocument

        public SaxonDocument​(InputStream stream)
        Public constructor from XML as input stream.
        Parameters:
        stream - Input stream with XML document.
        Since:
        0.28.1

      • SaxonDocument

        public SaxonDocument​(net.sf.saxon.s9api.XdmNode xml)
        Public constructor from Saxon XML document node.
        Parameters:
        xml - Saxon XML document node.
        Since:
        0.28.0

    • Method Detail

      • xpath

        public List<String> xpath​(String query)
        Description copied from interface: XML
        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 XML.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.

        Specified by:
        xpath in interface XML
        Parameters:
        query - The XPath query
        Returns:
        The list of string values (texts) or single function result

      • nodes

        public List<XML> nodes​(String query)
        Description copied from interface: XML
        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.

        Specified by:
        nodes in interface XML
        Parameters:
        query - The XPath query
        Returns:
        Collection of DOM nodes

      • registerNs

        public XML registerNs​(String prefix,
                      Object uri)
        Description copied from interface: XML
        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.

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

      • merge

        public XML merge​(NamespaceContext context)
        Description copied from interface: XML
        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.

        Specified by:
        merge in interface XML
        Parameters:
        context - The context to append
        Returns:
        A new XML document, with a merged context on board

      • node

        public Node node()
        Description copied from interface: XML
        Retrieve DOM node, represented by this wrapper.
        Specified by:
        node in interface XML
        Returns:
        DOM node