Package com.adaptris.util.text.xml

Class XPath

  • public class XPath
extends java.lang.Object
    Wrapper around XPath/

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String SYSPROP_USE_SAXON_XPATH
      "interlok.useSaxonXPath" controls whether Saxon is explicitly enabled as an XPathFactory (defaults to true).

    • Constructor Summary

      Constructors 
      Constructor Description
      XPath()  
      XPath​(javax.xml.namespace.NamespaceContext ctx)  
      XPath​(javax.xml.namespace.NamespaceContext ctx, javax.xml.xpath.XPathFactory factory)  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static javax.xml.xpath.XPathFactory newXPathFactory()
      Convenience method to create a new XPathFactory.
      static XPath newXPathInstance​(DocumentBuilderFactoryBuilder builder, javax.xml.namespace.NamespaceContext namespaceCtx)
      Create a new XPath instance.
      static XPath newXPathInstance​(javax.xml.parsers.DocumentBuilderFactory builder, javax.xml.namespace.NamespaceContext namespaceCtx)  
      java.lang.String[] selectMultipleTextItems​(org.w3c.dom.Node context, java.lang.String xpath)
      returns an array of string values taken from a list of elements returned by an xpath
      org.w3c.dom.NodeList selectNodeList​(org.w3c.dom.Node context, java.lang.String xpath)
      selects a list of Nodes from the context node using the supplied xpath
      org.w3c.dom.Node selectSingleNode​(org.w3c.dom.Node context, java.lang.String xpath)
      Selects a single Node based on the supplied Xpath
      java.lang.String selectSingleTextItem​(org.w3c.dom.Node context, java.lang.String xpath)
      returns the string value contained in an element returned by an XPath

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • SYSPROP_USE_SAXON_XPATH

        public static final java.lang.String SYSPROP_USE_SAXON_XPATH
        "interlok.useSaxonXPath" controls whether Saxon is explicitly enabled as an XPathFactory (defaults to true).

        From the saxon documentation : Saxon therefore no longer identifies itself (in the JAR file manifest) as a JAXP XPath supplier. If you want to load Saxon as your XPath engine, you need to select it explicitly; it's not enough to just put it on the classpath.. If set to true, then we attempt to use com.saxonica.config.EnterpriseXPathFactory, com.saxonica.config.ProfessionalXPathFactory and net.sf.saxon.xpath.XPathFactoryImpl as XPathFactory instances (in that order).

        See Also:
        Constant Field Values

    • Constructor Detail

      • XPath

        public XPath()

      • XPath

        public XPath​(javax.xml.namespace.NamespaceContext ctx)

      • XPath

        public XPath​(javax.xml.namespace.NamespaceContext ctx,
             javax.xml.xpath.XPathFactory factory)

    • Method Detail

      • selectSingleTextItem

        public java.lang.String selectSingleTextItem​(org.w3c.dom.Node context,
                                             java.lang.String xpath)
                                      throws javax.xml.xpath.XPathExpressionException
        returns the string value contained in an element returned by an XPath
        Parameters:
        context - the node to apply the XPath to
        xpath - the xpath to apply
        Returns:
        the string extracted
        Throws:
        javax.xml.xpath.XPathExpressionException - on error

      • selectMultipleTextItems

        public java.lang.String[] selectMultipleTextItems​(org.w3c.dom.Node context,
                                                  java.lang.String xpath)
                                           throws javax.xml.xpath.XPathExpressionException
        returns an array of string values taken from a list of elements returned by an xpath
        Parameters:
        context - the node to apply the XPath to
        xpath - the xpath to apply
        Returns:
        the strings extracted
        Throws:
        javax.xml.xpath.XPathExpressionException - on error

      • selectNodeList

        public org.w3c.dom.NodeList selectNodeList​(org.w3c.dom.Node context,
                                           java.lang.String xpath)
                                    throws javax.xml.xpath.XPathExpressionException
        selects a list of Nodes from the context node using the supplied xpath
        Parameters:
        context - the root node to query
        xpath - the xpath to apply
        Returns:
        NodeList of returned Nodes
        Throws:
        javax.xml.xpath.XPathExpressionException - on error.

      • selectSingleNode

        public org.w3c.dom.Node selectSingleNode​(org.w3c.dom.Node context,
                                         java.lang.String xpath)
                                  throws javax.xml.xpath.XPathExpressionException
        Selects a single Node based on the supplied Xpath
        Parameters:
        context - the root node to query
        xpath - the xpath to apply
        Returns:
        the Node extracted
        Throws:
        javax.xml.xpath.XPathExpressionException - on error.

      • newXPathFactory

        public static javax.xml.xpath.XPathFactory newXPathFactory()
        Convenience method to create a new XPathFactory.
        Returns:
        either a Saxon based XPathFactory or one auto-found by XPathFactory.newInstance()

      • newXPathInstance

        public static XPath newXPathInstance​(DocumentBuilderFactoryBuilder builder,
                                     javax.xml.namespace.NamespaceContext namespaceCtx)
        Create a new XPath instance.

        If the DocumentBuilderFactoryBuilder has been explicitly set to be not namespace aware and the document does in fact contain namespaces, then Saxon can cause merry havoc in the sense that //NonNamespaceXpath doesn't work if the document has namespaces in it. This then is a helper to mitigate against that; but of course in this situation you end up not being able to use XPath 2.0 functions, when namespace-awareness is off as saxon 9.7+ no longer registers itself as a XPathFactory.

        This leads us to a behavioural matrix that looks like this. Using Saxon means you get XPath 2.0 and its associated benefits, Using XPathFactory.newInstance() generally means you don't, unless you have registered an alternative XPathFactory.

        DocumentBuilderFactoryBuilder#withNamespaceAware()   Namespace Context available   Uses Saxon   Uses XPathFactory#newInstance()
        true   no   true   false
        true   true   true   false
        false   no   false   true
        false   yes   false   true
        not specified   yes   true   false
        not specified   no   true   false
        Parameters:
        builder - the document builder factory
        namespaceCtx - the namespace context (might be null, but we pass it into the XPath constructor)