net.sf.saxon.sxpath

## Class XPathExpression

- java.lang.Object
- - net.sf.saxon.sxpath.XPathExpression

- All Implemented Interfaces:
    Serializable

      public class XPathExpression
      extends Object
      implements Serializable

  This class is a representation of an XPath Expression for use with the `XPathEvaluator` class. It is modelled on the XPath API defined in JAXP 1.3, but is cut down to remove any dependencies on JAXP 1.3, making it suitable for use on vanilla JDK 1.4 installations.
  Author:
    Michael H. Kay
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `XPathExpression(XPathEvaluator evaluator, Expression exp)` The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XPathDynamicContext` | `createDynamicContext()` Create a dynamic context suitable for evaluating this expression, without supplying a context item
    `XPathDynamicContext` | `createDynamicContext(Controller controller, Item contextItem)` Create a dynamic context suitable for evaluating this expression within an environment represented by an existing controller.
    `XPathDynamicContext` | `createDynamicContext(Item contextItem)` Create a dynamic context suitable for evaluating this expression
    `boolean` | `effectiveBooleanValue(XPathDynamicContext context)` Evaluate the expression, returning its effective boolean value
    `List<Object>` | `evaluate(Source source)` Execute a prepared XPath expression, returning the results as a List in which items have been converted to the appropriate Java object.
    `List<Item>` | `evaluate(XPathDynamicContext context)` Execute the expression, returning the result as a List, whose members will be instances of the class `Item`
    `Object` | `evaluateSingle(Source source)` Execute a prepared XPath expression, returning the first item in the result.
    `Item` | `evaluateSingle(XPathDynamicContext context)` Execute the expression, returning the result as a single `Item` If the result of the expression is a sequence containing more than one item, items after the first are discarded.
    `Expression` | `getInternalExpression()` Low-level method to get the internal Saxon expression object.
    `SequenceIterator<? extends Item>` | `iterate(XPathDynamicContext context)` Execute the expression, returning the result as a `SequenceIterator`, whose members will be instances of the class `Item`
    `SequenceIterator` | `rawIterator(Source source)` Deprecated. since 8.9 - use `iterate(net.sf.saxon.sxpath.XPathDynamicContext)`
    `protected void` | `setStackFrameMap(SlotManager map, int numberOfExternalVariables)` Define the number of slots needed for local variables within the expression

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### XPathExpression

          protected XPathExpression(XPathEvaluator evaluator,
                         Expression exp)

      The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator
      Parameters:
        `evaluator` - the creating XPathEvaluator
        `exp` - the internal representation of the compiled expression

  - ### Method Detail

    - #### setStackFrameMap

          protected void setStackFrameMap(SlotManager map,
                              int numberOfExternalVariables)

      Define the number of slots needed for local variables within the expression
      Parameters:
        `map` - the stack frame map identifying all the variables used by the expression, both those declared internally, and references to variables declared externally
        `numberOfExternalVariables` - the number of slots in the stack frame allocated to externally-declared variables. These must be assigned a value before execution starts

    - #### createDynamicContext

          public XPathDynamicContext createDynamicContext()

      Create a dynamic context suitable for evaluating this expression, without supplying a context item
      Returns:
        an XPathDynamicContext object representing a suitable dynamic context. This will be initialized with a stack frame suitable for holding the variables used by the expression.

    - #### createDynamicContext

          public XPathDynamicContext createDynamicContext(Item contextItem)
                                                   throws XPathException

      Create a dynamic context suitable for evaluating this expression
      Parameters:
        `contextItem` - the initial context item, which may be null if no context item is required, or if it is to be supplied later
      Returns:
        an XPathDynamicContext object representing a suitable dynamic context. This will be initialized with a stack frame suitable for holding the variables used by the expression.
      Throws:
        `XPathException` - if the context item does not match the required context item type set up in the static context

    - #### createDynamicContext

          public XPathDynamicContext createDynamicContext(Controller controller,
                                                 Item contextItem)
                                                   throws XPathException

      Create a dynamic context suitable for evaluating this expression within an environment represented by an existing controller. The dynamic context will inherit properties of the Controller such as the current error listener, URI resolver, document pool, and implicit timezone.
      Parameters:
        `controller` - an existing controller. May be null, in which case the method is equivalent to calling `createDynamicContext(net.sf.saxon.om.Item)`
        `contextItem` - the initial context item, which may be null if no context item is required, or if it is to be supplied later
      Returns:
        an XPathDynamicContext object representing a suitable dynamic context. This will be initialized with a stack frame suitable for holding the variables used by the expression.
      Throws:
        `XPathException` - if the context item does not match the required context item type set up in the static context
      Since:
        9.2

    - #### iterate

          public SequenceIterator<? extends Item> iterate(XPathDynamicContext context)
                                                   throws XPathException

      Execute the expression, returning the result as a `SequenceIterator`, whose members will be instances of the class `Item`

      Note that if evaluation of the expression fails with a dynamic error, this will generally be reported in the form of an exception thrown by the next() method of the `SequenceIterator`

      Parameters:
        `context` - the XPath dynamic context
      Returns:
        an iterator over the result of the expression
      Throws:
        `XPathException` - if a dynamic error occurs during the expression evaluation (though in many cases, the error will only be detected when the iterator is actually used).

    - #### evaluate

          public List<Item> evaluate(XPathDynamicContext context)
                              throws XPathException

      Execute the expression, returning the result as a List, whose members will be instances of the class `Item`
      Parameters:
        `context` - the XPath dynamic context
      Returns:
        a list of items representing the result of the expression
      Throws:
        `XPathException` - if a dynamic error occurs while evaluation the expression

    - #### evaluateSingle

          public Item evaluateSingle(XPathDynamicContext context)
                              throws XPathException

      Execute the expression, returning the result as a single `Item` If the result of the expression is a sequence containing more than one item, items after the first are discarded. If the result is an empty sequence, the method returns null.
      Parameters:
        `context` - the XPath dynamic context
      Returns:
        the first item in the result of the expression, or null to indicate that the result is an empty sequence
      Throws:
        `XPathException` - if a dynamic error occurs during the expression evaluation

    - #### effectiveBooleanValue

          public boolean effectiveBooleanValue(XPathDynamicContext context)
                                        throws XPathException

      Evaluate the expression, returning its effective boolean value
      Parameters:
        `context` - the XPath dynamic context
      Returns:
        the effective boolean value of the result, as defined by the fn:boolean() function
      Throws:
        `XPathException` - if a dynamic error occurs, or if the result is a value for which no effective boolean value is defined

    - #### evaluate

          public List<Object> evaluate(Source source)
                                throws XPathException

      Execute a prepared XPath expression, returning the results as a List in which items have been converted to the appropriate Java object.
      Parameters:
        `source` - the document or other node against which the XPath expression will be evaluated. This may be a Saxon NodeInfo object, representing a node in an existing tree, or it may be any kind of JAXP Source object such as a StreamSource SAXSource or DOMSource. For the way in which the source document is built, see `Configuration.buildDocument(javax.xml.transform.Source)`
      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 instance of net.sf.saxon.om.NodeInfo, representing a node, or a Java object representing an atomic value.
      Throws:
        `XPathException` - if a dynamic error occurs during the expression evaluation

    - #### evaluateSingle

          public Object evaluateSingle(Source source)
                                throws XPathException

      Execute a prepared XPath expression, 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:
        `source` - the document or other node against which the XPath expression will be evaluated. This may be a Saxon NodeInfo object, representing a node in an existing tree, or it may be any kind of JAXP Source object such as a StreamSource SAXSource or DOMSource. For the way in which the source document is built, see `Configuration.buildDocument(javax.xml.transform.Source)`
      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` - if a dynamic error occurs during the expression evaluation

    - #### rawIterator

          public SequenceIterator rawIterator(Source source)
                                       throws XPathException

      Deprecated. since 8.9 - use `iterate(net.sf.saxon.sxpath.XPathDynamicContext)`
      Get a raw iterator over the results of the expression. This returns results without any conversion of the returned items to "native" Java classes. This method is intended for use by applications that need to process the results of the expression using internal Saxon interfaces.
      Parameters:
        `source` - the document or other node against which the XPath expression will be evaluated. This may be a Saxon NodeInfo object, representing a node in an existing tree, or it may be any kind of JAXP Source object such as a StreamSource SAXSource or DOMSource. For the way in which the source document is built, see `Configuration.buildDocument(javax.xml.transform.Source)`
      Returns:
        an iterator over the results of the expression
      Throws:
        `XPathException` - if a dynamic error occurs during the expression evaluation

    - #### getInternalExpression

          public Expression getInternalExpression()

      Low-level method to get the internal Saxon expression object. This exposes a wide range of internal methods that may be needed by specialized applications, and allows greater control over the dynamic context for evaluating the expression.
      Returns:
        the underlying Saxon expression object.

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