Class XPathExpressionImpl

  • All Implemented Interfaces:
    javax.xml.xpath.XPathExpression, SortKeyEvaluator

    public class XPathExpressionImpl
    extends java.lang.Object
    implements javax.xml.xpath.XPathExpression, SortKeyEvaluator

    The JAXP XPathExpression interface represents a compiled XPath expression that can be repeatedly evaluated. This class is Saxon's implementation of that interface.

    The class also includes some methods retained from Saxon's original XPath API. When these methods are used, the object contains the context node and other state, so it is not thread-safe.

    Author:
    Michael H. Kay
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected XPathExpressionImpl​(Expression exp, Executable exec)
      The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      java.util.List evaluate()
      Deprecated.
      since 9.0.
      java.lang.String evaluate​(java.lang.Object node)
      Evaluate the expression to return a string value
      java.lang.Object evaluate​(java.lang.Object node, javax.xml.namespace.QName qName)
      JAXP 1.3 evaluate() method
      java.lang.String evaluate​(org.xml.sax.InputSource inputSource)
      Evaluate the XPath expression against an input source to obtain a string result
      java.lang.Object evaluate​(org.xml.sax.InputSource inputSource, javax.xml.namespace.QName qName)
      Evaluate the XPath expression against an input source to obtain a result of a specified type
      java.lang.Object evaluateSingle()
      Deprecated.
      since 9.0.
      Item evaluateSortKey​(int n, XPathContext c)
      Callback for evaluating the sort keys.
      Configuration getConfiguration()
      Get the Configuration under which this XPath expression was compiled
      Expression getInternalExpression()
      Low-level method to get the internal Saxon expression object.
      SlotManager getStackFrameMap()
      Get the stack frame map.
      protected void privatelySetContextNode​(NodeInfo node)
      Protected, undeprecated version of setContextNode() for use by deprecated paths within the package (exists to avoid deprecation warnings when compiling Saxon)
      SequenceIterator rawIterator​(Item contextItem)
      Get a raw iterator over the results of the expression.
      void setContextNode​(NodeInfo node)
      Deprecated.
      since 9.0.
      void setSortKey​(XPathExpressionImpl sortKey)
      Deprecated.
      since 9.0.
      protected void setStackFrameMap​(SlotManager map)
      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
      • Methods inherited from interface javax.xml.xpath.XPathExpression

        evaluateExpression, evaluateExpression, evaluateExpression, evaluateExpression
    • Constructor Detail

      • XPathExpressionImpl

        protected XPathExpressionImpl​(Expression exp,
                                      Executable exec)
        The constructor is protected, to ensure that instances can only be created using the createExpression() method of XPathEvaluator
        Parameters:
        exp - the compiled expression
        exec - the executable
    • Method Detail

      • setStackFrameMap

        protected void setStackFrameMap​(SlotManager map)
        Define the number of slots needed for local variables within the expression. This method is for internal use only.
        Parameters:
        map - description of the stack frame
      • getStackFrameMap

        public SlotManager getStackFrameMap()
        Get the stack frame map. This holds information about the allocation of slots to variables. This is needed by applications using low-level interfaces for evaluating the expression
        Returns:
        a description of the stack frame
      • getConfiguration

        public Configuration getConfiguration()
        Get the Configuration under which this XPath expression was compiled
        Returns:
        the Saxon configuration
      • setSortKey

        public void setSortKey​(XPathExpressionImpl sortKey)
        Deprecated.
        since 9.0. This method is not present in the JAXP interface. The recommended way to get a sorted result is to use XQuery instead of XPath.
        Define the sort order for the results of the expression. If this method is called, then the list returned by a subsequent call on the evaluate() method will first be sorted.
        Parameters:
        sortKey - an XPathExpression, which will be applied to each item in the sequence; the result of this expression determines the ordering of the list returned by the evaluate() method. The sortKey can be null, to clear a previous sort key. Note that the expression is not automatically atomized; if it selects nodes, these should be explicitly converted to atomic values by calling the string() or data() functions.
      • setContextNode

        public void setContextNode​(NodeInfo node)
        Deprecated.
        since 9.0. Using this method is not thread-safe. Use a method instead such as evaluate(Object, QName) that allows the context node to be specified as a parameter to the call.
        Set the context node for evaluating the expression. If this method is not called, the context node will be the root of the document to which the prepared expression is bound.
        Parameters:
        node - the context node
      • privatelySetContextNode

        protected void privatelySetContextNode​(NodeInfo node)
        Protected, undeprecated version of setContextNode() for use by deprecated paths within the package (exists to avoid deprecation warnings when compiling Saxon)
        Parameters:
        node - the context node
      • evaluate

        public java.util.List evaluate()
                                throws XPathException
        Deprecated.
        since 9.0. This method is not present in the JAXP interface. Either use the JAXP methods such as evaluate(Object, QName), or use the Saxon XPath API instead of JAXP.
        Execute a prepared XPath expression, returning the results as a List. The context node must have been set previously using setContextNode(net.sf.saxon.om.NodeInfo).
        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. For the types of Java object that may be returned, see evaluate(Object, javax.xml.namespace.QName) with the second argument set to NODESET.
        Throws:
        XPathException
      • evaluateSingle

        public java.lang.Object evaluateSingle()
                                        throws XPathException
        Deprecated.
        since 9.0. This method is not present in the JAXP interface. Either use the JAXP methods such as evaluate(Object, QName), or use the Saxon XPath API instead of JAXP.
        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). The context node must be set previously using setContextNode(net.sf.saxon.om.NodeInfo).
        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
      • rawIterator

        public SequenceIterator rawIterator​(Item contextItem)
                                     throws XPathException
        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:
        contextItem - the context item for evaluating the expression
        Returns:
        an iterator over the results of the expression, with no conversion of returned items
        Throws:
        XPathException
        Since:
        9.0
      • evaluate

        public java.lang.Object evaluate​(java.lang.Object node,
                                         javax.xml.namespace.QName qName)
                                  throws javax.xml.xpath.XPathExpressionException
        JAXP 1.3 evaluate() method
        Specified by:
        evaluate in interface javax.xml.xpath.XPathExpression
        Parameters:
        node - The context node. This must use a representation of nodes that this implementation understands. This may be a Saxon NodeInfo, or a node in one of the external object models supported, for example DOM, DOM4J, JDOM, or XOM, provided the support module for that object model is loaded.

        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.

        Saxon does not allow a NodeList to be supplied for this parameter. It's not clear what this would be intended to mean.

        qName - Indicates the type of result required. This must be one of the constants defined in the JAXP XPathConstants class. Saxon will attempt to convert the actual result of the expression to the required type using the XPath 1.0 conversion rules.
        Returns:
        the result of the evaluation, as a Java object of the appropriate type. Saxon interprets the rules as follows:
        QNameReturn Value
        BOOLEAN The effective boolean value of the actual result, as a Java Boolean object
        STRING The result of applying the string() function to the actual result, as a Java String object
        NUMBER The result of applying the number() function to the actual result, as a Java Double object
        NODE A single node, in the native data model supplied as input. If the expression returns more than one node, the first is returned. If the expression returns an empty sequence, null is returned. If the expression returns an atomic value, or if the first item in the result sequence is an atomic value, an exception is thrown.
        NODESET This is interpreted as allowing any sequence, of nodes or atomic values. If the first argument is a wrapper around a DOM Node, then the result is returned as a DOM NodeList, and an exception is then thrown if the result sequence contains a value that is not a DOM Node. In all other cases the result is returned as a Java List object, unless it is empty, in which case null is returned. The contents of the list may be node objects (in the native data model supplied as input), or Java objects representing the XPath atomic values in the actual result: String for an xs:string, Double for a xs:double, Long for an xs:integer, and so on. (For safety, cast the values to a type such as xs:string within the XPath expression).
        Throws:
        javax.xml.xpath.XPathExpressionException - if evaluation of the expression fails or if the result cannot be converted to the requested type.
      • evaluate

        public java.lang.String evaluate​(java.lang.Object node)
                                  throws javax.xml.xpath.XPathExpressionException
        Evaluate the expression to return a string value
        Specified by:
        evaluate in interface javax.xml.xpath.XPathExpression
        Parameters:
        node - the initial context node. This must be either an instance of NodeInfo or a node recognized by a known external object model.

        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 results of the expression, converted to a String
        Throws:
        javax.xml.xpath.XPathExpressionException - if evaluation fails
      • evaluate

        public java.lang.Object evaluate​(org.xml.sax.InputSource inputSource,
                                         javax.xml.namespace.QName qName)
                                  throws javax.xml.xpath.XPathExpressionException
        Evaluate the XPath expression against an input source to obtain a result of a specified type
        Specified by:
        evaluate in interface javax.xml.xpath.XPathExpression
        Parameters:
        inputSource - The input source document against which the expression is evaluated. (Note that there is no caching. This will be parsed, and the parsed result will be discarded.) If the supplied value is null then (contrary to the JAXP specifications), the XPath expression is evaluated with the context item undefined.
        qName - The type required, identified by a constant in XPathConstants
        Returns:
        the result of the evaluation, as a Java object of the appropriate type: see evaluate(Object, javax.xml.namespace.QName)
        Throws:
        javax.xml.xpath.XPathExpressionException
      • evaluate

        public java.lang.String evaluate​(org.xml.sax.InputSource inputSource)
                                  throws javax.xml.xpath.XPathExpressionException
        Evaluate the XPath expression against an input source to obtain a string result
        Specified by:
        evaluate in interface javax.xml.xpath.XPathExpression
        Parameters:
        inputSource - The input source document against which the expression is evaluated. (Note that there is no caching. This will be parsed, and the parsed result will be discarded.)
        Returns:
        the result of the evaluation, converted to a String
        Throws:
        javax.xml.xpath.XPathExpressionException - in the event of an XPath dynamic error
        java.lang.NullPointerException - If inputSource is null.
      • 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.