Package net.sf.saxon.xpath

Class XPathEvaluator

  • All Implemented Interfaces:
    javax.xml.xpath.XPath
    public class XPathEvaluator
extends java.lang.Object
implements javax.xml.xpath.XPath

    XPathEvaluator provides a simple API for standalone XPath processing (that is, executing XPath expressions in the absence of an XSLT stylesheet). It is an implementation of the JAXP 1.3 XPath interface, with additional methods provided (a) for backwards compatibility (b) to give extra control over the XPath evaluation, and (c) to support XPath 2.0.

    Author:
    Michael H. Kay

    • Constructor Summary

      Constructors 
      Constructor Description
      XPathEvaluator()
      Default constructor.
      XPathEvaluator​(javax.xml.transform.Source source)
      Construct an XPathEvaluator to process a particular source document.
      XPathEvaluator​(Configuration config)
      Construct an XPathEvaluator with a specified configuration.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      javax.xml.xpath.XPathExpression compile​(java.lang.String expr)
      Compile an XPath 2.0 expression
      XPathExpressionImpl createExpression​(java.lang.String expression)
      Prepare an XPath expression for subsequent evaluation.
      java.util.List evaluate​(java.lang.String expression)
      Prepare and execute an XPath expression, supplied as a string, and returning the results as a List.
      java.lang.String evaluate​(java.lang.String expr, java.lang.Object node)
      Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
      java.lang.Object evaluate​(java.lang.String expr, java.lang.Object node, javax.xml.namespace.QName qName)
      Single-shot method to compile and execute an XPath 2.0 expression.
      java.lang.String evaluate​(java.lang.String expr, org.xml.sax.InputSource inputSource)
      Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document, returning the result as a string
      java.lang.Object evaluate​(java.lang.String expr, org.xml.sax.InputSource inputSource, javax.xml.namespace.QName qName)
      Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document
      java.lang.Object evaluateSingle​(java.lang.String expression)
      Prepare and execute an XPath expression, supplied as a string, and returning the first item in the result.
      javax.xml.namespace.NamespaceContext getNamespaceContext()
      Get the namespace context, if one has been set using setNamespaceContext(javax.xml.namespace.NamespaceContext)
      StandaloneContext getStaticContext()
      Get the current static context
      javax.xml.xpath.XPathFunctionResolver getXPathFunctionResolver()
      Get the resolver for XPath functions
      javax.xml.xpath.XPathVariableResolver getXPathVariableResolver()
      Get the resolver for XPath variables
      void importSchema​(javax.xml.transform.Source source)
      Import a schema.
      boolean isBackwardsCompatible()
      Get the value of XPath 1.0 compatibility mode
      static void main​(java.lang.String[] args)
      A simple command-line interface for the XPathEvaluator (not documented).
      void reset()  
      void setBackwardsCompatible​(boolean compatible)
      Set XPath 1.0 compatibility mode on or off (by default, it is false)
      void setContextNode​(NodeInfo node)
      Set the context node.
      void setNamespaceContext​(javax.xml.namespace.NamespaceContext namespaceContext)
      Set the namespace context to be used.
      NodeInfo setSource​(javax.xml.transform.Source source)
      Supply the document against which XPath expressions are to be executed.
      void setStaticContext​(StandaloneContext context)
      Set the static context for compiling XPath expressions.
      void setStripSpace​(boolean strip)
      Indicate whether all whitespace text nodes in the source document are to be removed.
      void setXPathFunctionResolver​(javax.xml.xpath.XPathFunctionResolver xPathFunctionResolver)
      Set the resolver for XPath functions
      void setXPathVariableResolver​(javax.xml.xpath.XPathVariableResolver xPathVariableResolver)
      Set the resolver for XPath variables

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface javax.xml.xpath.XPath

        evaluateExpression, evaluateExpression, evaluateExpression, evaluateExpression

    • Constructor Detail

      • XPathEvaluator

        public XPathEvaluator()
        Default constructor. Creates an XPathEvaluator with a default configuration and name pool. The default Configuration is not schema-aware.

      • XPathEvaluator

        public XPathEvaluator​(Configuration config)
        Construct an XPathEvaluator with a specified configuration.
        Parameters:
        config - the configuration to be used. If schema-aware XPath expressions are to be used, this must be a SchemaAwareConfiguration.

      • XPathEvaluator

        public XPathEvaluator​(javax.xml.transform.Source source)
               throws XPathException
        Construct an XPathEvaluator to process a particular source document. This is equivalent to using the default constructor and immediately calling setSource().
        Parameters:
        source - The source document (or a specific node within it).
        Throws:
        XPathException

    • Method Detail

      • setStripSpace

        public void setStripSpace​(boolean strip)
        Indicate whether all whitespace text nodes in the source document are to be removed. This option has no effect unless it is called before the call on setSource(), and unless the Source supplied to setSource() is a SAXSource or StreamSource.
        Parameters:
        strip - True if all whitespace text nodes are to be stripped from the source document, false otherwise. The default if the method is not called is false.

      • setSource

        public NodeInfo setSource​(javax.xml.transform.Source source)
                   throws XPathException
        Supply the document against which XPath expressions are to be executed. This method must be called before preparing or executing an XPath expression. Setting a new source document clears all the namespaces that have been declared.
        Parameters:
        source - Any javax.xml.transform.Source object representing the document against which XPath expressions will be executed. Note that a Saxon DocumentInfo (indeed any NodeInfo) can be used as a Source. To use a third-party DOM Document as a source, create an instance of DOMSource to wrap it.

        The Source object supplied also determines the initial setting of the context item. In most cases the context node will be the root of the supplied document; however, if a NodeInfo or DOMSource is supplied it can be any node in the document.

        Returns:
        the NodeInfo of the start node in the resulting document object.
        Throws:
        XPathException

      • setStaticContext

        public void setStaticContext​(StandaloneContext context)
        Set the static context for compiling XPath expressions. This provides control over the environment in which the expression is compiled, for example it allows namespace prefixes to be declared, variables to be bound and functions to be defined. For most purposes, the static context can be defined by providing and tailoring an instance of the StandaloneContext class. Until this method is called, a default static context is used, in which no namespaces are defined other than the standard ones (xml, xslt, and saxon), and no variables or functions (other than the core XPath functions) are available.

      • getStaticContext

        public StandaloneContext getStaticContext()
        Get the current static context

      • createExpression

        public XPathExpressionImpl createExpression​(java.lang.String expression)
                                     throws XPathException
        Prepare an XPath expression for subsequent evaluation.
        Parameters:
        expression - The XPath expression to be evaluated, supplied as a string.
        Returns:
        an XPathExpression object representing the prepared expression
        Throws:
        XPathException - if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared.

      • setContextNode

        public void setContextNode​(NodeInfo node)
        Set the context node. This provides the context node for any expressions executed after this method is called, including expressions that were prepared before it was called.
        Parameters:
        node - The node to be used as the context node. This must be a node within the context document (the document supplied using the setSource() method).
        Throws:
        java.lang.NullPointerException - if the argument is null
        java.lang.IllegalArgumentException - if the supplied node is not a node in the context document

      • evaluate

        public java.util.List evaluate​(java.lang.String expression)
                        throws XPathException
        Prepare and execute an XPath expression, supplied as a string, and returning the results as a List.
        Parameters:
        expression - The XPath expression to be evaluated, supplied as a string.
        Returns:
        The results of the expression, as a List. The List represents the sequence of items returned by the expression. Each item in the list will either be an object representing a node, or a Java object representing an atomic value. The types of Java object that may be included in the list, and the XML Schema data types that they correspond to, are as follows:

        • Boolean (xs:boolean)
        • String (xs:string)
        • BigDecimal (xs:decimal)
        • Long (xs:integer and its derived types)
        • Double (xs:double)
        • Float (xs:float)
        • Date (xs:date, xs:dateTime)
        Throws:
        XPathException

      • reset

        public void reset()
        Specified by:
        reset in interface javax.xml.xpath.XPath

      • setBackwardsCompatible

        public void setBackwardsCompatible​(boolean compatible)
        Set XPath 1.0 compatibility mode on or off (by default, it is false)
        Parameters:
        compatible - true if XPath 1.0 compatibility mode is to be set to true, false if it is to be set to false.

      • isBackwardsCompatible

        public boolean isBackwardsCompatible()
        Get the value of XPath 1.0 compatibility mode
        Returns:
        true if XPath 1.0 compatibility mode is set

      • setXPathVariableResolver

        public void setXPathVariableResolver​(javax.xml.xpath.XPathVariableResolver xPathVariableResolver)
        Set the resolver for XPath variables
        Specified by:
        setXPathVariableResolver in interface javax.xml.xpath.XPath
        Parameters:
        xPathVariableResolver -

      • getXPathVariableResolver

        public javax.xml.xpath.XPathVariableResolver getXPathVariableResolver()
        Get the resolver for XPath variables
        Specified by:
        getXPathVariableResolver in interface javax.xml.xpath.XPath
        Returns:
        the resolver, if one has been set

      • setXPathFunctionResolver

        public void setXPathFunctionResolver​(javax.xml.xpath.XPathFunctionResolver xPathFunctionResolver)
        Set the resolver for XPath functions
        Specified by:
        setXPathFunctionResolver in interface javax.xml.xpath.XPath
        Parameters:
        xPathFunctionResolver -

      • getXPathFunctionResolver

        public javax.xml.xpath.XPathFunctionResolver getXPathFunctionResolver()
        Get the resolver for XPath functions
        Specified by:
        getXPathFunctionResolver in interface javax.xml.xpath.XPath
        Returns:
        the resolver, if one has been set

      • setNamespaceContext

        public void setNamespaceContext​(javax.xml.namespace.NamespaceContext namespaceContext)
        Set the namespace context to be used. This supplements any namespaces declared directly using declareNamespace on the staticContext object
        Specified by:
        setNamespaceContext in interface javax.xml.xpath.XPath
        Parameters:
        namespaceContext - The namespace context

      • getNamespaceContext

        public javax.xml.namespace.NamespaceContext getNamespaceContext()
        Get the namespace context, if one has been set using setNamespaceContext(javax.xml.namespace.NamespaceContext)
        Specified by:
        getNamespaceContext in interface javax.xml.xpath.XPath
        Returns:
        the namespace context if set, or null otherwise

      • importSchema

        public void importSchema​(javax.xml.transform.Source source)
                  throws SchemaException
        Import a schema. This is possible only if the schema-aware version of Saxon is being used, and if the Configuration is a SchemaAwareConfiguration. Having imported a schema, the types defined in that schema become part of the static context.
        Parameters:
        source - A Source object identifying the schema document to be loaded
        Throws:
        SchemaException - if the schema contained in this document is invalid
        java.lang.UnsupportedOperationException - if the configuration is not schema-aware

      • compile

        public javax.xml.xpath.XPathExpression compile​(java.lang.String expr)
                                        throws javax.xml.xpath.XPathExpressionException
        Compile an XPath 2.0 expression
        Specified by:
        compile in interface javax.xml.xpath.XPath
        Parameters:
        expr - the XPath 2.0 expression to be compiled, as a string
        Returns:
        the compiled form of the expression
        Throws:
        javax.xml.xpath.XPathExpressionException - if there are any static errors in the expression. Note that references to undeclared variables are not treated as static errors, because variables are not pre-declared using this API.

      • evaluate

        public java.lang.Object evaluate​(java.lang.String expr,
                                 java.lang.Object node,
                                 javax.xml.namespace.QName qName)
                          throws javax.xml.xpath.XPathExpressionException
        Single-shot method to compile and execute an XPath 2.0 expression.
        Specified by:
        evaluate in interface javax.xml.xpath.XPath
        Parameters:
        expr - The XPath 2.0 expression to be compiled and executed
        node - The context node for evaluation of the expression
        qName - The type of result required. For details, see XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
        Returns:
        the result of evaluating the expression, returned as described in XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
        Throws:
        javax.xml.xpath.XPathExpressionException - if any static or dynamic error occurs in evaluating the expression.

      • evaluate

        public java.lang.String evaluate​(java.lang.String expr,
                                 java.lang.Object node)
                          throws javax.xml.xpath.XPathExpressionException
        Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
        Specified by:
        evaluate in interface javax.xml.xpath.XPath
        Parameters:
        expr - The XPath 2.0 expression to be compiled and executed
        node - The context node for evaluation of the expression
        Returns:
        the result of evaluating the expression, converted to a string as if by calling the XPath string() function
        Throws:
        javax.xml.xpath.XPathExpressionException - if any static or dynamic error occurs in evaluating the expression.

      • evaluate

        public java.lang.Object evaluate​(java.lang.String expr,
                                 org.xml.sax.InputSource inputSource,
                                 javax.xml.namespace.QName qName)
                          throws javax.xml.xpath.XPathExpressionException
        Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document
        Specified by:
        evaluate in interface javax.xml.xpath.XPath
        Parameters:
        expr - The XPath 2.0 expression to be compiled and executed
        inputSource - The source document: this will be parsed and built into a tree, and the XPath expression will be executed with the root node of the tree as the context node
        qName - The type of result required. For details, see XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
        Returns:
        the result of evaluating the expression, returned as described in XPathExpressionImpl.evaluate(Object, javax.xml.namespace.QName)
        Throws:
        javax.xml.xpath.XPathExpressionException - if any static or dynamic error occurs in evaluating the expression.

      • evaluate

        public java.lang.String evaluate​(java.lang.String expr,
                                 org.xml.sax.InputSource inputSource)
                          throws javax.xml.xpath.XPathExpressionException
        Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document, returning the result as a string
        Specified by:
        evaluate in interface javax.xml.xpath.XPath
        Parameters:
        expr - The XPath 2.0 expression to be compiled and executed
        inputSource - The source document: this will be parsed and built into a tree, and the XPath expression will be executed with the root node of the tree as the context node
        Returns:
        the result of evaluating the expression, converted to a string as if by calling the XPath string() function
        Throws:
        javax.xml.xpath.XPathExpressionException - if any static or dynamic error occurs in evaluating the expression.

      • evaluateSingle

        public java.lang.Object evaluateSingle​(java.lang.String expression)
                                throws XPathException
        Prepare and execute an XPath expression, supplied as a string, and returning the first item in the result. This is useful where it is known that the expression will only return a singleton value (for example, a single node, or a boolean).
        Parameters:
        expression - The XPath expression to be evaluated, supplied as a string.
        Returns:
        The first item in the sequence returned by the expression. If the expression returns an empty sequence, this method returns null. Otherwise, it returns the first item in the result sequence, represented as a Java object using the same mapping as for the evaluate() method
        Throws:
        XPathException

      • main

        public static void main​(java.lang.String[] args)
                 throws java.lang.Exception
        A simple command-line interface for the XPathEvaluator (not documented). First parameter is the filename containing the source document, second parameter is the XPath expression.
        Throws:
        java.lang.Exception