net.sf.saxon.xpath

## Class XPathEvaluator

- java.lang.Object
- - net.sf.saxon.xpath.XPathEvaluator

- All Implemented Interfaces:
    XPath

      public class XPathEvaluator
      extends Object
      implements XPath

  XPathEvaluator implements the JAXP 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.

  It is intended to evolve this so that it only supports the JAXP style of operation. Some of the methods are therefore marked as deprecated in this release, and will be dropped in a future release.

  For an alternative XPath API, offering more direct access to Saxon capabilities, see `XPathEvaluator`.

  Note that the `XPathEvaluator` links to a Saxon `Configuration` object. By default a new `Configuration` is created automatically. In many applications, however, it is desirable to share a configuration. The default configuration is not schema aware. All source documents used by XPath expressions under this evaluator must themselves be built using the `Configuration` used by this evaluator.

  Author:
    Michael H. Kay

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XPathEvaluator()` Default constructor.
    `XPathEvaluator(Configuration config)` Construct an XPathEvaluator with a specified configuration.
    `XPathEvaluator(Source source)` Construct an XPathEvaluator to process a particular source document.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XPathExpression` | `compile(String expr)` Compile an XPath 2.0 expression
    `XPathExpressionImpl` | `createExpression(String expression)` Deprecated. since Saxon 8.9 - use `compile(String)`
    `String` | `evaluate(String expr, 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
    `Object` | `evaluate(String expr, InputSource inputSource, QName qName)` Single-shot method to parse and build a source document, and compile an execute an XPath 2.0 expression, against that document
    `String` | `evaluate(String expr, Object node)` Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
    `Object` | `evaluate(String expr, Object node, QName qName)` Single-shot method to compile and execute an XPath 2.0 expression.
    `Configuration` | `getConfiguration()` Get the Configuration used by this XPathEvaluator
    `NamespaceContext` | `getNamespaceContext()` Get the namespace context, if one has been set using `setNamespaceContext(javax.xml.namespace.NamespaceContext)`
    `JAXPXPathStaticContext` | `getStaticContext()` Get the current static context
    `XPathFunctionResolver` | `getXPathFunctionResolver()` Get the resolver for XPath functions
    `XPathVariableResolver` | `getXPathVariableResolver()` Get the resolver for XPath variables
    `void` | `importSchema(Source source)` Import a schema.
    `boolean` | `isBackwardsCompatible()` Get the value of XPath 1.0 compatibility mode
    `static void` | `main(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)` Deprecated. since Saxon 8.9 - use the various method defined in the JAXP interface definition, which allow a NodeInfo object to be supplied as the value of the Source argument
    `void` | `setNamespaceContext(NamespaceContext namespaceContext)` Set the namespace context to be used.
    `NodeInfo` | `setSource(Source source)` Supply a document against which XPath expressions are to be executed, converting it to a Saxon NodeInfo object.
    `void` | `setStaticContext(JAXPXPathStaticContext context)` Set the static context for compiling XPath expressions.
    `void` | `setStripSpace(boolean strip)` Deprecated. since 8.9. The preferred way to define options for the way in which source documents are built is to use the class `AugmentedSource` for any of the methods expecting a `Source` object.
    `void` | `setXPathFunctionResolver(XPathFunctionResolver xPathFunctionResolver)` Set the resolver for XPath functions
    `void` | `setXPathLanguageLevel(String level)` Set the XPath language level to be supported.
    `void` | `setXPathVariableResolver(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`

- - ### Constructor Detail

    - #### XPathEvaluator

          public XPathEvaluator()

      Default constructor. Creates an XPathEvaluator with Configuration appropriate to the version of the Saxon software being run.

    - #### 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 an EnterpriseConfiguration.

    - #### XPathEvaluator

          public XPathEvaluator(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

    - #### setXPathLanguageLevel

          public void setXPathLanguageLevel(String level)

      Set the XPath language level to be supported. The values recognized are the strings "1.0", "2.0", and "3.0". The default is "2.0". The value "1.0" does not disable 2.0 features, but switches on 1.0 compatibility mode. The value "3.0" is necessary to enable XPath 3.0 features. Setting the value to "3.0" switches backwards compatibility off.
      Parameters:
        `level` - one of "1.0", "2.0", or "3.0".
      Since:
        9.5

    - #### getConfiguration

          public Configuration getConfiguration()

      Get the Configuration used by this XPathEvaluator
      Returns:
        the Configuration used by this XPathEvaluator

    - #### setStripSpace

          public void setStripSpace(boolean strip)

      Deprecated. since 8.9. The preferred way to define options for the way in which source documents are built is to use the class `AugmentedSource` for any of the methods expecting a `Source` object.
      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(Source source)
                             throws XPathException

      Supply a document against which XPath expressions are to be executed, converting it to a Saxon NodeInfo object.

      If the supplied source is a `NodeInfo`, it is returned unchanged.

      If the supplied source is a `DOMSource`, the result is a Saxon `NodeInfo` wrapper around the DOM Node contained by the DOMSource.

      In all other cases, the result is a document node, and is the same as the result of calling `Configuration.buildDocument(javax.xml.transform.Source)` with the same argument; except that when whitespace stripping has been requested using `setStripSpace(boolean)`, this request is passed on.

      Despite the name of this method, it does not change the state of the `XPathEvaluator` in any way.

      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` - if the supplied Source is a NodeInfo object that was built using an incompatible Configuration (that is, a Configuration using a different NamePool). Also, if any error occurs parsing the document supplied as the Source.
        `XPathException`

    - #### setStaticContext

          public void setStaticContext(JAXPXPathStaticContext 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 JAXPXPathStaticContext 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.
      Parameters:
        `context` - the static context
      Throws:
        `IllegalArgumentException` - if the supplied static context uses a different and incompatible Configuration from the one used in this XPathEvaluator

    - #### getStaticContext

          public JAXPXPathStaticContext getStaticContext()

      Get the current static context
      Returns:
        the static context

    - #### createExpression

          public XPathExpressionImpl createExpression(String expression)
                                               throws XPathException

      Deprecated. since Saxon 8.9 - use `compile(String)`
      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)

      Deprecated. since Saxon 8.9 - use the various method defined in the JAXP interface definition, which allow a NodeInfo object to be supplied as the value of the Source argument
      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. The node must be within a tree built using the same Saxon `Configuration` as used by this XPathEvaluator.
      Throws:
        `IllegalArgumentException` - if the supplied node was built using the wrong Configuration

    - #### reset

          public void reset()

      Specified by:
        `reset` in interface `XPath`

    - #### setBackwardsCompatible

          public void setBackwardsCompatible(boolean compatible)

      Set XPath 1.0 compatibility mode on or off (by default, it is false). This applies to any XPath expression compiled while this option is in force.
      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(XPathVariableResolver xPathVariableResolver)

      Set the resolver for XPath variables
      Specified by:
        `setXPathVariableResolver` in interface `XPath`
      Parameters:
        `xPathVariableResolver` - a resolver for variables

    - #### getXPathVariableResolver

          public XPathVariableResolver getXPathVariableResolver()

      Get the resolver for XPath variables
      Specified by:
        `getXPathVariableResolver` in interface `XPath`
      Returns:
        the resolver, if one has been set

    - #### setXPathFunctionResolver

          public void setXPathFunctionResolver(XPathFunctionResolver xPathFunctionResolver)

      Set the resolver for XPath functions
      Specified by:
        `setXPathFunctionResolver` in interface `XPath`
      Parameters:
        `xPathFunctionResolver` - a resolver for XPath function calls

    - #### getXPathFunctionResolver

          public XPathFunctionResolver getXPathFunctionResolver()

      Get the resolver for XPath functions
      Specified by:
        `getXPathFunctionResolver` in interface `XPath`
      Returns:
        the resolver, if one has been set

    - #### setNamespaceContext

          public void setNamespaceContext(NamespaceContext namespaceContext)

      Set the namespace context to be used.
      Specified by:
        `setNamespaceContext` in interface `XPath`
      Parameters:
        `namespaceContext` - The namespace context

    - #### getNamespaceContext

          public NamespaceContext getNamespaceContext()

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

    - #### importSchema

          public void importSchema(Source source)
                            throws SchemaException

      Import a schema. This is possible only if Saxon-EE is being used, and if the Configuration is an EnterpriseConfiguration. 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
        `UnsupportedOperationException` - if the configuration is not schema-aware

    - #### compile

          public XPathExpression compile(String expr)
                                  throws XPathExpressionException

      Compile an XPath 2.0 expression
      Specified by:
        `compile` in interface `XPath`
      Parameters:
        `expr` - the XPath 2.0 expression to be compiled, as a string
      Returns:
        the compiled form of the expression
      Throws:
        `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 Object evaluate(String expr,
                        Object node,
                        QName qName)
                          throws XPathExpressionException

      Single-shot method to compile and execute an XPath 2.0 expression.
      Specified by:
        `evaluate` in interface `XPath`
      Parameters:
        `expr` - The XPath 2.0 expression to be compiled and executed
        `node` - The context node for evaluation of the expression.

        This may be a NodeInfo object, representing a node in Saxon's native implementation of the data model, or it may be a node in any supported external object model: DOM, JDOM, DOM4J, or XOM, or any other model for which support has been configured in the Configuration. Note that the supporting libraries for the chosen model must be on the class path.

        Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because Saxon supports multiple object models, and it's unclear what kind of document node would be appropriate. Instead, Saxon uses the node supplied to the `setContextNode(net.sf.saxon.om.NodeInfo)` method if available, and if none is available, executes the XPath expression with the context item undefined.

        `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:
        `XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.

    - #### evaluate

          public String evaluate(String expr,
                        Object node)
                          throws XPathExpressionException

      Single-shot method to compile an execute an XPath 2.0 expression, returning the result as a string.
      Specified by:
        `evaluate` in interface `XPath`
      Parameters:
        `expr` - The XPath 2.0 expression to be compiled and executed
        `node` - The context node for evaluation of the expression

        This may be a NodeInfo object, representing a node in Saxon's native implementation of the data model, or it may be a node in any supported external object model: DOM, JDOM, DOM4J, or XOM, or any other model for which support has been configured in the Configuration. Note that the supporting libraries for the chosen model must be on the class path.

        Contrary to the interface specification, Saxon does not supply an empty document when the value is null. This is because Saxon supports multiple object models, and it's unclear what kind of document node would be appropriate. Instead, Saxon uses the node supplied to the `setContextNode(net.sf.saxon.om.NodeInfo)` method if available, and if none is available, executes the XPath expression with the context item undefined.

      Returns:
        the result of evaluating the expression, converted to a string as if by calling the XPath string() function
      Throws:
        `XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.

    - #### evaluate

          public Object evaluate(String expr,
                        InputSource inputSource,
                        QName qName)
                          throws 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 `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:
        `XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.
        `NullPointerException` - if any of the three arguments is null

    - #### evaluate

          public String evaluate(String expr,
                        InputSource inputSource)
                          throws 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 `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:
        `XPathExpressionException` - if any static or dynamic error occurs in evaluating the expression.
        `NullPointerException` - if either of the two arguments is null

    - #### main

          public static void main(String[] args)
                           throws Exception

      A simple command-line interface for the XPathEvaluator (not documented).
      Parameters:
        `args` - command line arguments. First parameter is the filename containing the source document, second parameter is the XPath expression.
      Throws:
        `Exception` - if any error occurs

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.