org.apache.xpath

## Class Expression

- java.lang.Object
- - org.apache.xpath.Expression

- All Implemented Interfaces:
    java.io.Serializable, javax.xml.transform.SourceLocator, ExpressionNode, XPathVisitable
  Direct Known Subclasses:
    Function, NodeTest, Operation, UnaryOperation, UnionPattern, Variable, XObject

      public abstract class Expression
      extends java.lang.Object
      implements java.io.Serializable, ExpressionNode, XPathVisitable

  This abstract class serves as the base for all expression objects. An Expression can be executed to return a `XObject`, normally has a location within a document or DOM, can send error and warning events, and normally do not hold state and are meant to be immutable once construction has completed. An exception to the immutibility rule is iterators and walkers, which must be cloned in order to be used -- the original must still be immutable.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Expression()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `DTMIterator` | `asIterator(XPathContext xctxt, int contextNode)` Given an select expression and a context, evaluate the XPath and return the resulting iterator.
    `DTMIterator` | `asIteratorRaw(XPathContext xctxt, int contextNode)` Given an select expression and a context, evaluate the XPath and return the resulting iterator, but do not clone.
    `int` | `asNode(XPathContext xctxt)` Return the first node out of the nodeset, if this expression is a nodeset expression.
    `void` | `assertion(boolean b, java.lang.String msg)` Tell the user of an assertion error, and probably throw an exception.
    `boolean` | `bool(XPathContext xctxt)` Evaluate expression to a boolean.
    `boolean` | `canTraverseOutsideSubtree()` Tell if this expression or it's subexpressions can traverse outside the current subtree.
    `abstract boolean` | `deepEquals(Expression expr)` Compare this object with another object and see if they are equal, include the sub heararchy.
    `void` | `error(XPathContext xctxt, java.lang.String msg, java.lang.Object[] args)` Tell the user of an error, and probably throw an exception.
    `abstract XObject` | `execute(XPathContext xctxt)` Execute an expression in the XPath runtime context, and return the result of the expression.
    `XObject` | `execute(XPathContext xctxt, boolean destructiveOK)` Execute an expression in the XPath runtime context, and return the result of the expression, but tell that a "safe" object doesn't have to be returned.
    `XObject` | `execute(XPathContext xctxt, int currentNode)` Execute an expression in the XPath runtime context, and return the result of the expression.
    `XObject` | `execute(XPathContext xctxt, int currentNode, DTM dtm, int expType)` Execute an expression in the XPath runtime context, and return the result of the expression.
    `void` | `executeCharsToContentHandler(XPathContext xctxt, org.xml.sax.ContentHandler handler)` Execute an expression in the XPath runtime context, and return the result of the expression.
    `void` | `exprAddChild(ExpressionNode n, int i)` This method tells the node to add its argument to the node's list of children.
    `ExpressionNode` | `exprGetChild(int i)` This method returns a child node.
    `int` | `exprGetNumChildren()` Return the number of children the node has.
    `ExpressionNode` | `exprGetParent()`
    `void` | `exprSetParent(ExpressionNode n)` This pair of methods are used to inform the node of its parent.
    `abstract void` | `fixupVariables(java.util.Vector vars, int globalsSize)` This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.
    `int` | `getColumnNumber()` Return the character position where the current document event ends.
    `ExpressionNode` | `getExpressionOwner()` Get the first non-Expression parent of this node.
    `int` | `getLineNumber()` Return the line number where the current document event ends.
    `java.lang.String` | `getPublicId()` Return the public identifier for the current document event.
    `java.lang.String` | `getSystemId()` Return the system identifier for the current document event.
    `boolean` | `isNodesetExpr()` Tell if the expression is a nodeset expression.
    `boolean` | `isStableNumber()` Tell if this expression returns a stable number that will not change during iterations within the expression.
    `double` | `num(XPathContext xctxt)` Evaluate expression to a number.
    `void` | `warn(XPathContext xctxt, java.lang.String msg, java.lang.Object[] args)` Warn the user of an problem.
    `XMLString` | `xstr(XPathContext xctxt)` Cast result object to a string.

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

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

    - ### Methods inherited from interface org.apache.xpath.XPathVisitable

      `callVisitors`

- - ### Constructor Detail

    - #### Expression

          public Expression()

  - ### Method Detail

    - #### canTraverseOutsideSubtree

          public boolean canTraverseOutsideSubtree()

      Tell if this expression or it's subexpressions can traverse outside the current subtree.
      Returns:
        true if traversal outside the context node's subtree can occur.

    - #### execute

          public XObject execute(XPathContext xctxt,
                                 int currentNode)
                          throws javax.xml.transform.TransformerException

      Execute an expression in the XPath runtime context, and return the result of the expression.
      Parameters:
        `xctxt` - The XPath runtime context.
        `currentNode` - The currentNode.
      Returns:
        The result of the expression in the form of a `XObject`.
      Throws:
        `javax.xml.transform.TransformerException` - if a runtime exception occurs.

    - #### execute

          public XObject execute(XPathContext xctxt,
                                 int currentNode,
                                 DTM dtm,
                                 int expType)
                          throws javax.xml.transform.TransformerException

      Execute an expression in the XPath runtime context, and return the result of the expression.
      Parameters:
        `xctxt` - The XPath runtime context.
        `currentNode` - The currentNode.
        `dtm` - The DTM of the current node.
        `expType` - The expanded type ID of the current node.
      Returns:
        The result of the expression in the form of a `XObject`.
      Throws:
        `javax.xml.transform.TransformerException` - if a runtime exception occurs.

    - #### execute

          public abstract XObject execute(XPathContext xctxt)
                                   throws javax.xml.transform.TransformerException

      Execute an expression in the XPath runtime context, and return the result of the expression.
      Parameters:
        `xctxt` - The XPath runtime context.
      Returns:
        The result of the expression in the form of a `XObject`.
      Throws:
        `javax.xml.transform.TransformerException` - if a runtime exception occurs.

    - #### execute

          public XObject execute(XPathContext xctxt,
                                 boolean destructiveOK)
                          throws javax.xml.transform.TransformerException

      Execute an expression in the XPath runtime context, and return the result of the expression, but tell that a "safe" object doesn't have to be returned. The default implementation just calls execute(xctxt).
      Parameters:
        `xctxt` - The XPath runtime context.
        `destructiveOK` - true if a "safe" object doesn't need to be returned.
      Returns:
        The result of the expression in the form of a `XObject`.
      Throws:
        `javax.xml.transform.TransformerException` - if a runtime exception occurs.

    - #### num

          public double num(XPathContext xctxt)
                     throws javax.xml.transform.TransformerException

      Evaluate expression to a number.
      Parameters:
        `xctxt` - The XPath runtime context.
      Returns:
        The expression evaluated as a double.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### bool

          public boolean bool(XPathContext xctxt)
                       throws javax.xml.transform.TransformerException

      Evaluate expression to a boolean.
      Parameters:
        `xctxt` - The XPath runtime context.
      Returns:
        false
      Throws:
        `javax.xml.transform.TransformerException`

    - #### xstr

          public XMLString xstr(XPathContext xctxt)
                         throws javax.xml.transform.TransformerException

      Cast result object to a string.
      Parameters:
        `xctxt` - The XPath runtime context.
      Returns:
        The string this wraps or the empty string if null
      Throws:
        `javax.xml.transform.TransformerException`

    - #### isNodesetExpr

          public boolean isNodesetExpr()

      Tell if the expression is a nodeset expression. In other words, tell if you can execute `asNode` without an exception.
      Returns:
        true if the expression can be represented as a nodeset.

    - #### asNode

          public int asNode(XPathContext xctxt)
                     throws javax.xml.transform.TransformerException

      Return the first node out of the nodeset, if this expression is a nodeset expression.
      Parameters:
        `xctxt` - The XPath runtime context.
      Returns:
        the first node out of the nodeset, or DTM.NULL.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### asIterator

          public DTMIterator asIterator(XPathContext xctxt,
                                        int contextNode)
                                 throws javax.xml.transform.TransformerException

      Given an select expression and a context, evaluate the XPath and return the resulting iterator.
      Parameters:
        `xctxt` - The execution context.
        `contextNode` - The node that "." expresses.
      Returns:
        A valid DTMIterator.
      Throws:
        `javax.xml.transform.TransformerException` - thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
        `javax.xml.transform.TransformerException`
      Usage:
        **Experimental**

    - #### asIteratorRaw

          public DTMIterator asIteratorRaw(XPathContext xctxt,
                                           int contextNode)
                                    throws javax.xml.transform.TransformerException

      Given an select expression and a context, evaluate the XPath and return the resulting iterator, but do not clone.
      Parameters:
        `xctxt` - The execution context.
        `contextNode` - The node that "." expresses.
      Returns:
        A valid DTMIterator.
      Throws:
        `javax.xml.transform.TransformerException` - thrown if the active ProblemListener decides the error condition is severe enough to halt processing.
        `javax.xml.transform.TransformerException`
      Usage:
        **Experimental**

    - #### executeCharsToContentHandler

          public void executeCharsToContentHandler(XPathContext xctxt,
                                                   org.xml.sax.ContentHandler handler)
                                            throws javax.xml.transform.TransformerException,
                                                   org.xml.sax.SAXException

      Execute an expression in the XPath runtime context, and return the result of the expression.
      Parameters:
        `xctxt` - The XPath runtime context. NEEDSDOC @param handler
      Throws:
        `javax.xml.transform.TransformerException` - if a runtime exception occurs.
        `org.xml.sax.SAXException`

    - #### isStableNumber

          public boolean isStableNumber()

      Tell if this expression returns a stable number that will not change during iterations within the expression. This is used to determine if a proximity position predicate can indicate that no more searching has to occur.
      Returns:
        true if the expression represents a stable number.

    - #### fixupVariables

          public abstract void fixupVariables(java.util.Vector vars,
                                              int globalsSize)

      This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.
      Parameters:
        `vars` - List of QNames that correspond to variables. This list should be searched backwards for the first qualified name that corresponds to the variable reference qname. The position of the QName in the vector from the start of the vector will be its position in the stack frame (but variables above the globalsTop value will need to be offset to the current stack frame). NEEDSDOC @param globalsSize

    - #### deepEquals

          public abstract boolean deepEquals(Expression expr)

      Compare this object with another object and see if they are equal, include the sub heararchy.
      Parameters:
        `expr` - Another expression object.
      Returns:
        true if this objects class and the expr object's class are the same, and the data contained within both objects are considered equal.

    - #### warn

          public void warn(XPathContext xctxt,
                           java.lang.String msg,
                           java.lang.Object[] args)
                    throws javax.xml.transform.TransformerException

      Warn the user of an problem.
      Parameters:
        `xctxt` - The XPath runtime context.
        `msg` - An error msgkey that corresponds to one of the conststants found in `XPATHErrorResources`, which is a key for a format string.
        `args` - An array of arguments represented in the format string, which may be null.
      Throws:
        `javax.xml.transform.TransformerException` - if the current ErrorListoner determines to throw an exception.
        `javax.xml.transform.TransformerException`

    - #### assertion

          public void assertion(boolean b,
                                java.lang.String msg)

      Tell the user of an assertion error, and probably throw an exception.
      Parameters:
        `b` - If false, a runtime exception will be thrown.
        `msg` - The assertion message, which should be informative.
      Throws:
        `java.lang.RuntimeException` - if the b argument is false.
        `javax.xml.transform.TransformerException`

    - #### error

          public void error(XPathContext xctxt,
                            java.lang.String msg,
                            java.lang.Object[] args)
                     throws javax.xml.transform.TransformerException

      Tell the user of an error, and probably throw an exception.
      Parameters:
        `xctxt` - The XPath runtime context.
        `msg` - An error msgkey that corresponds to one of the constants found in `XPATHErrorResources`, which is a key for a format string.
        `args` - An array of arguments represented in the format string, which may be null.
      Throws:
        `javax.xml.transform.TransformerException` - if the current ErrorListoner determines to throw an exception.
        `javax.xml.transform.TransformerException`

    - #### getExpressionOwner

          public ExpressionNode getExpressionOwner()

      Get the first non-Expression parent of this node.
      Returns:
        null or first ancestor that is not an Expression.

    - #### exprSetParent

          public void exprSetParent(ExpressionNode n)

      This pair of methods are used to inform the node of its parent.
      Specified by:
        `exprSetParent` in interface `ExpressionNode`

    - #### exprGetParent

          public ExpressionNode exprGetParent()

      Specified by:
        `exprGetParent` in interface `ExpressionNode`

    - #### exprAddChild

          public void exprAddChild(ExpressionNode n,
                                   int i)

      This method tells the node to add its argument to the node's list of children.
      Specified by:
        `exprAddChild` in interface `ExpressionNode`

    - #### exprGetChild

          public ExpressionNode exprGetChild(int i)

      This method returns a child node. The children are numbered from zero, left to right.
      Specified by:
        `exprGetChild` in interface `ExpressionNode`

    - #### exprGetNumChildren

          public int exprGetNumChildren()

      Return the number of children the node has.
      Specified by:
        `exprGetNumChildren` in interface `ExpressionNode`

    - #### getPublicId

          public java.lang.String getPublicId()

      Return the public identifier for the current document event.

      The return value is the public identifier of the document entity or of the external parsed entity in which the markup that triggered the event appears.

      Specified by:
        `getPublicId` in interface `javax.xml.transform.SourceLocator`
      Returns:
        A string containing the public identifier, or null if none is available.
      See Also:
        `getSystemId()`

    - #### getSystemId

          public java.lang.String getSystemId()

      Return the system identifier for the current document event.

      The return value is the system identifier of the document entity or of the external parsed entity in which the markup that triggered the event appears.

      If the system identifier is a URL, the parser must resolve it fully before passing it to the application.

      Specified by:
        `getSystemId` in interface `javax.xml.transform.SourceLocator`
      Returns:
        A string containing the system identifier, or null if none is available.
      See Also:
        `getPublicId()`

    - #### getLineNumber

          public int getLineNumber()

      Return the line number where the current document event ends.

      Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

      The return value is an approximation of the line number in the document entity or external parsed entity where the markup that triggered the event appears.

      Specified by:
        `getLineNumber` in interface `javax.xml.transform.SourceLocator`
      Returns:
        The line number, or -1 if none is available.
      See Also:
        `getColumnNumber()`

    - #### getColumnNumber

          public int getColumnNumber()

      Return the character position where the current document event ends.

      Warning: The return value from the method is intended only as an approximation for the sake of error reporting; it is not intended to provide sufficient information to edit the character content of the original XML document.

      The return value is an approximation of the column number in the document entity or external parsed entity where the markup that triggered the event appears.

      Specified by:
        `getColumnNumber` in interface `javax.xml.transform.SourceLocator`
      Returns:
        The column number, or -1 if none is available.
      See Also:
        `getLineNumber()`

Copyright © 2023 Apache XML Project. All Rights Reserved.