org.apache.xpath.objects

## Class XObject

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

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, javax.xml.transform.SourceLocator, ExpressionNode, XPathVisitable
  Direct Known Subclasses:
    NodeSequence, XBoolean, XNumber, XRTreeFrag, XString, XUnresolvedVariable, XUnresolvedVariableSimple

      public class XObject
      extends Expression
      implements java.io.Serializable, java.lang.Cloneable

  This class represents an XPath object, and is capable of converting the object to various types, such as a string. This class acts as the base class to other XPath type objects, such as XString, and provides polymorphic casting capabilities.
  See Also:
    Serialized Form
  Usage:

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `CLASS_BOOLEAN` Constant for BOOLEAN object type
    `static int` | `CLASS_NODESET` Constant for NODESET object type
    `static int` | `CLASS_NULL` Constant for NULL object type
    `static int` | `CLASS_NUMBER` Constant for NUMBER object type
    `static int` | `CLASS_RTREEFRAG` Constant for RESULT TREE FRAGMENT object type
    `static int` | `CLASS_STRING` Constant for STRING object type
    `static int` | `CLASS_UNKNOWN` Constant for UNKNOWN object type
    `static int` | `CLASS_UNRESOLVEDVARIABLE` Represents an unresolved variable type as an integer.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XObject()` Create an XObject.
    `XObject(java.lang.Object obj)` Create an XObject.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `allowDetachToRelease(boolean allowRelease)` Specify if it's OK for detach to release the iterator for reuse.
    `void` | `appendToFsb(FastStringBuffer fsb)` Cast result object to a string.
    `boolean` | `bool()` Cast result object to a boolean.
    `boolean` | `boolWithSideEffects()` Cast result object to a boolean, but allow side effects, such as the incrementing of an iterator.
    `void` | `callVisitors(ExpressionOwner owner, XPathVisitor visitor)` This will traverse the heararchy, calling the visitor for each member.
    `java.lang.Object` | `castToType(int t, XPathContext support)` Cast object to type t.
    `static XObject` | `create(java.lang.Object val)` Create the right XObject based on the type of the object passed.
    `static XObject` | `create(java.lang.Object val, XPathContext xctxt)` Create the right XObject based on the type of the object passed.
    `boolean` | `deepEquals(Expression expr)` Compare this object with another object and see if they are equal, include the sub heararchy.
    `void` | `destruct()` Forces the object to release it's resources.
    `void` | `detach()` Detaches the `DTMIterator` from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state.
    `void` | `dispatchCharactersEvents(org.xml.sax.ContentHandler ch)` Directly call the characters method on the passed ContentHandler for the string-value.
    `boolean` | `equals(XObject obj2)` Tell if two objects are functionally equal.
    `XObject` | `execute(XPathContext xctxt)` For support of literal objects in xpaths.
    `void` | `fixupVariables(java.util.Vector vars, int globalsSize)` XObjects should not normally need to fix up variables.
    `XObject` | `getFresh()` Get a fresh copy of the object.
    `int` | `getType()` Tell what kind of class this is.
    `java.lang.String` | `getTypeString()` Given a request type, return the equivalent string.
    `boolean` | `greaterThan(XObject obj2)` Tell if one object is greater than the other.
    `boolean` | `greaterThanOrEqual(XObject obj2)` Tell if one object is greater than or equal to the other.
    `DTMIterator` | `iter()` Cast result object to a nodelist.
    `boolean` | `lessThan(XObject obj2)` Tell if one object is less than the other.
    `boolean` | `lessThanOrEqual(XObject obj2)` Tell if one object is less than or equal to the other.
    `NodeSetDTM` | `mutableNodeset()` Cast result object to a nodelist.
    `org.w3c.dom.NodeList` | `nodelist()` Cast result object to a nodelist.
    `org.w3c.dom.traversal.NodeIterator` | `nodeset()` Cast result object to a nodelist.
    `boolean` | `notEquals(XObject obj2)` Tell if two objects are functionally not equal.
    `double` | `num()` Cast result object to a number.
    `double` | `numWithSideEffects()` Cast result object to a number, but allow side effects, such as the incrementing of an iterator.
    `java.lang.Object` | `object()` Return a java object that's closest to the representation that should be handed to an extension.
    `void` | `reset()` Reset for fresh reuse.
    `int` | `rtf()` For functions to override.
    `int` | `rtf(XPathContext support)` Cast result object to a result tree fragment.
    `org.w3c.dom.DocumentFragment` | `rtree()` For functions to override.
    `org.w3c.dom.DocumentFragment` | `rtree(XPathContext support)` Cast result object to a result tree fragment.
    `java.lang.String` | `str()` Cast result object to a string.
    `java.lang.String` | `toString()` Return the string representation of the object
    `XMLString` | `xstr()` Cast result object to a string.

    - ### Methods inherited from class org.apache.xpath.Expression

      `asIterator, asIteratorRaw, asNode, assertion, bool, canTraverseOutsideSubtree, error, execute, execute, execute, executeCharsToContentHandler, exprAddChild, exprGetChild, exprGetNumChildren, exprGetParent, exprSetParent, getColumnNumber, getExpressionOwner, getLineNumber, getPublicId, getSystemId, isNodesetExpr, isStableNumber, num, warn, xstr`

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

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

- - ### Field Detail

    - #### CLASS_NULL

          public static final int CLASS_NULL

      Constant for NULL object type
      See Also:
        Constant Field Values

    - #### CLASS_UNKNOWN

          public static final int CLASS_UNKNOWN

      Constant for UNKNOWN object type
      See Also:
        Constant Field Values

    - #### CLASS_BOOLEAN

          public static final int CLASS_BOOLEAN

      Constant for BOOLEAN object type
      See Also:
        Constant Field Values

    - #### CLASS_NUMBER

          public static final int CLASS_NUMBER

      Constant for NUMBER object type
      See Also:
        Constant Field Values

    - #### CLASS_STRING

          public static final int CLASS_STRING

      Constant for STRING object type
      See Also:
        Constant Field Values

    - #### CLASS_NODESET

          public static final int CLASS_NODESET

      Constant for NODESET object type
      See Also:
        Constant Field Values

    - #### CLASS_RTREEFRAG

          public static final int CLASS_RTREEFRAG

      Constant for RESULT TREE FRAGMENT object type
      See Also:
        Constant Field Values

    - #### CLASS_UNRESOLVEDVARIABLE

          public static final int CLASS_UNRESOLVEDVARIABLE

      Represents an unresolved variable type as an integer.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XObject

          public XObject()

      Create an XObject.

    - #### XObject

          public XObject(java.lang.Object obj)

      Create an XObject.
      Parameters:
        `obj` - Can be any object, should be a specific type for derived classes, or null.

  - ### Method Detail

    - #### execute

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

      For support of literal objects in xpaths.
      Specified by:
        `execute` in class `Expression`
      Parameters:
        `xctxt` - The XPath execution context.
      Returns:
        This object.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### allowDetachToRelease

          public void allowDetachToRelease(boolean allowRelease)

      Specify if it's OK for detach to release the iterator for reuse. This function should be called with a value of false for objects that are stored in variables. Calling this with a value of false on a XNodeSet will cause the nodeset to be cached.
      Parameters:
        `allowRelease` - true if it is OK for detach to release this iterator for pooling.

    - #### detach

          public void detach()

      Detaches the `DTMIterator` from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state. After `detach` has been invoked, calls to `nextNode` or `previousNode` will raise a runtime exception.

    - #### destruct

          public void destruct()

      Forces the object to release it's resources. This is more harsh than detach().

    - #### reset

          public void reset()

      Reset for fresh reuse.

    - #### dispatchCharactersEvents

          public void dispatchCharactersEvents(org.xml.sax.ContentHandler ch)
                                        throws org.xml.sax.SAXException

      Directly call the characters method on the passed ContentHandler for the string-value. Multiple calls to the ContentHandler's characters methods may well occur for a single call to this method.
      Parameters:
        `ch` - A non-null reference to a ContentHandler.
      Throws:
        `org.xml.sax.SAXException`

    - #### create

          public static XObject create(java.lang.Object val)

      Create the right XObject based on the type of the object passed. This function can not make an XObject that exposes DOM Nodes, NodeLists, and NodeIterators to the XSLT stylesheet as node-sets.
      Parameters:
        `val` - The java object which this object will wrap.
      Returns:
        the right XObject based on the type of the object passed.

    - #### create

          public static XObject create(java.lang.Object val,
                                       XPathContext xctxt)

      Create the right XObject based on the type of the object passed. This function can make an XObject that exposes DOM Nodes, NodeLists, and NodeIterators to the XSLT stylesheet as node-sets.
      Parameters:
        `val` - The java object which this object will wrap.
        `xctxt` - The XPath context.
      Returns:
        the right XObject based on the type of the object passed.

    - #### getType

          public int getType()

      Tell what kind of class this is.
      Returns:
        CLASS_UNKNOWN

    - #### getTypeString

          public java.lang.String getTypeString()

      Given a request type, return the equivalent string. For diagnostic purposes.
      Returns:
        type string "#UNKNOWN" + object class name

    - #### num

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

      Cast result object to a number. Always issues an error.
      Returns:
        0.0
      Throws:
        `javax.xml.transform.TransformerException`

    - #### numWithSideEffects

          public double numWithSideEffects()
                                    throws javax.xml.transform.TransformerException

      Cast result object to a number, but allow side effects, such as the incrementing of an iterator.
      Returns:
        numeric value of the string conversion from the next node in the NodeSetDTM, or NAN if no node was found
      Throws:
        `javax.xml.transform.TransformerException`

    - #### bool

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

      Cast result object to a boolean. Always issues an error.
      Returns:
        false
      Throws:
        `javax.xml.transform.TransformerException`

    - #### boolWithSideEffects

          public boolean boolWithSideEffects()
                                      throws javax.xml.transform.TransformerException

      Cast result object to a boolean, but allow side effects, such as the incrementing of an iterator.
      Returns:
        True if there is a next node in the nodeset
      Throws:
        `javax.xml.transform.TransformerException`

    - #### xstr

          public XMLString xstr()

      Cast result object to a string.
      Returns:
        The string this wraps or the empty string if null

    - #### str

          public java.lang.String str()

      Cast result object to a string.
      Returns:
        The object as a string

    - #### toString

          public java.lang.String toString()

      Return the string representation of the object
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        the string representation of the object

    - #### rtf

          public int rtf(XPathContext support)

      Cast result object to a result tree fragment.
      Parameters:
        `support` - XPath context to use for the conversion
      Returns:
        the objec as a result tree fragment.

    - #### rtree

          public org.w3c.dom.DocumentFragment rtree(XPathContext support)

      Cast result object to a result tree fragment.
      Parameters:
        `support` - XPath context to use for the conversion
      Returns:
        the objec as a result tree fragment.

    - #### rtree

          public org.w3c.dom.DocumentFragment rtree()

      For functions to override.
      Returns:
        null

    - #### rtf

          public int rtf()

      For functions to override.
      Returns:
        null

    - #### object

          public java.lang.Object object()

      Return a java object that's closest to the representation that should be handed to an extension.
      Returns:
        The object that this class wraps

    - #### iter

          public DTMIterator iter()
                           throws javax.xml.transform.TransformerException

      Cast result object to a nodelist. Always issues an error.
      Returns:
        null
      Throws:
        `javax.xml.transform.TransformerException`

    - #### getFresh

          public XObject getFresh()

      Get a fresh copy of the object. For use with variables.
      Returns:
        This object, unless overridden by subclass.

    - #### nodeset

          public org.w3c.dom.traversal.NodeIterator nodeset()
                                                     throws javax.xml.transform.TransformerException

      Cast result object to a nodelist. Always issues an error.
      Returns:
        null
      Throws:
        `javax.xml.transform.TransformerException`

    - #### nodelist

          public org.w3c.dom.NodeList nodelist()
                                        throws javax.xml.transform.TransformerException

      Cast result object to a nodelist. Always issues an error.
      Returns:
        null
      Throws:
        `javax.xml.transform.TransformerException`

    - #### mutableNodeset

          public NodeSetDTM mutableNodeset()
                                    throws javax.xml.transform.TransformerException

      Cast result object to a nodelist. Always issues an error.
      Returns:
        The object as a NodeSetDTM.
      Throws:
        `javax.xml.transform.TransformerException`

    - #### castToType

          public java.lang.Object castToType(int t,
                                             XPathContext support)
                                      throws javax.xml.transform.TransformerException

      Cast object to type t.
      Parameters:
        `t` - Type of object to cast this to
        `support` - XPath context to use for the conversion
      Returns:
        This object as the given type t
      Throws:
        `javax.xml.transform.TransformerException`

    - #### lessThan

          public boolean lessThan(XObject obj2)
                           throws javax.xml.transform.TransformerException

      Tell if one object is less than the other.
      Parameters:
        `obj2` - Object to compare this to
      Returns:
        True if this object is less than the given object
      Throws:
        `javax.xml.transform.TransformerException`

    - #### lessThanOrEqual

          public boolean lessThanOrEqual(XObject obj2)
                                  throws javax.xml.transform.TransformerException

      Tell if one object is less than or equal to the other.
      Parameters:
        `obj2` - Object to compare this to
      Returns:
        True if this object is less than or equal to the given object
      Throws:
        `javax.xml.transform.TransformerException`

    - #### greaterThan

          public boolean greaterThan(XObject obj2)
                              throws javax.xml.transform.TransformerException

      Tell if one object is greater than the other.
      Parameters:
        `obj2` - Object to compare this to
      Returns:
        True if this object is greater than the given object
      Throws:
        `javax.xml.transform.TransformerException`

    - #### greaterThanOrEqual

          public boolean greaterThanOrEqual(XObject obj2)
                                     throws javax.xml.transform.TransformerException

      Tell if one object is greater than or equal to the other.
      Parameters:
        `obj2` - Object to compare this to
      Returns:
        True if this object is greater than or equal to the given object
      Throws:
        `javax.xml.transform.TransformerException`

    - #### equals

          public boolean equals(XObject obj2)

      Tell if two objects are functionally equal.
      Parameters:
        `obj2` - Object to compare this to
      Returns:
        True if this object is equal to the given object
      Throws:
        `javax.xml.transform.TransformerException`

    - #### notEquals

          public boolean notEquals(XObject obj2)
                            throws javax.xml.transform.TransformerException

      Tell if two objects are functionally not equal.
      Parameters:
        `obj2` - Object to compare this to
      Returns:
        True if this object is not equal to the given object
      Throws:
        `javax.xml.transform.TransformerException`

    - #### fixupVariables

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

      XObjects should not normally need to fix up variables.
      Specified by:
        `fixupVariables` in class `Expression`
      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

    - #### appendToFsb

          public void appendToFsb(FastStringBuffer fsb)

      Cast result object to a string. NEEDSDOC @param fsb

    - #### callVisitors

          public void callVisitors(ExpressionOwner owner,
                                   XPathVisitor visitor)

      Description copied from interface: `XPathVisitable`
      This will traverse the heararchy, calling the visitor for each member. If the called visitor method returns false, the subtree should not be called.
      Specified by:
        `callVisitors` in interface `XPathVisitable`
      Parameters:
        `owner` - The owner of the visitor, where that path may be rewritten if needed.
        `visitor` - The visitor whose appropriate method will be called.
      See Also:
        `XPathVisitable.callVisitors(ExpressionOwner, XPathVisitor)`

    - #### deepEquals

          public boolean deepEquals(Expression expr)

      Description copied from class: `Expression`
      Compare this object with another object and see if they are equal, include the sub heararchy.
      Specified by:
        `deepEquals` in class `Expression`
      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.
      See Also:
        `Expression.deepEquals(Expression)`

Copyright © 2023 Apache XML Project. All Rights Reserved.