org.apache.xpath.axes

## Class NodeSequence

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

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, SourceLocator, DTMIterator, PathComponent, ExpressionNode, XPathVisitable

Direct Known Subclasses:
  XNodeSet

    public class NodeSequence
    extends XObject
    implements DTMIterator, java.lang.Cloneable, PathComponent

This class is the dynamic wrapper for a Xalan DTMIterator instance, and provides random access capabilities.

See Also:
  Serialized Form

### Field Summary

### Fields inherited from class org.apache.xpath.objects.XObject

`CLASS_BOOLEAN, CLASS_NODESET, CLASS_NULL, CLASS_NUMBER, CLASS_RTREEFRAG, CLASS_STRING, CLASS_UNKNOWN, CLASS_UNRESOLVEDVARIABLE`

### Fields inherited from interface org.apache.xml.dtm.DTMIterator

`FILTER_ACCEPT, FILTER_REJECT, FILTER_SKIP`

### Constructor Summary

Constructors
Constructor and Description
`NodeSequence()` Create a new NodeSequence in an invalid (null) state.
`NodeSequence(java.lang.Object nodeVector)` Create a new NodeSequence from a (already cloned) iterator.

### Method Summary

Methods
`void` `allowDetachToRelease(boolean allowRelease)` Calling this with a value of false will cause the nodeset to be cached.
`java.lang.Object` `clone()` Get a clone of this iterator, but don't reset the iteration in the process, so that it may be used from the current position.
`DTMIterator` `cloneWithReset()` Note: Not a deep clone.
`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` `fixupVariables(java.util.Vector vars, int globalsSize)` XObjects should not normally need to fix up variables.
`int` `getAnalysisBits()` Get the analysis bits for this path component, as defined in the WalkerFactory.
`int` `getAxis()` Returns the axis being iterated, if it is known.
`DTMIterator` `getContainedIter()` Get the functional iterator that fetches nodes.
`int` `getCurrentNode()` Get the current node in the iterator.
`int` `getCurrentPos()` Get the current position within the cached list, which is one less than the next nextNode() call will retrieve.
`DTM` `getDTM(int nodeHandle)` Get an instance of a DTM that "owns" a node handle.
`DTMManager` `getDTMManager()` Get an instance of the DTMManager.
`boolean` `getExpandEntityReferences()` The value of this flag determines whether the children of entity reference nodes are visible to the iterator.
`int` `getLength()` The number of nodes in the list.
`int` `getRoot()` The root node of the `DTMIterator`, as specified when it was created.
`int` `getWhatToShow()` This attribute determines which node types are presented via the iterator.
`boolean` `hasCache()` If the iterator needs to cache nodes as they are fetched, then this method returns true.
`boolean` `isDocOrdered()` Returns true if all the nodes in the iteration well be returned in document order.
`boolean` `isFresh()` Tells if this NodeSetDTM is "fresh", in other words, if the first nextNode() that is called will return the first node in the set.
`boolean` `isMutable()` Tells if this iterator can have nodes added to it or set via the `setItem(int node, int index)` method.
`int` `item(int index)` Returns the `node handle` of an item in the collection.
`int` `nextNode()` Returns the next node in the set and advances the position of the iterator in the set.
`int` `previousNode()` Returns the previous node in the set and moves the position of the `DTMIterator` backwards in the set.
`void` `reset()` Reset for fresh reuse.
`void` `runTo(int index)` If an index is requested, NodeSetDTM will call this method to run the iterator to the index.
`void` `setCurrentPos(int i)` Set the current position in the node set.
`void` `setItem(int node, int index)` Sets the node at the specified index of this vector to be the specified node.
`void` `setIter(DTMIterator iter)` Set the functional iterator that fetches nodes.
`void` `setRoot(int nodeHandle, java.lang.Object environment)` Reset the root node of the `DTMIterator`, overriding the value specified when it was created.
`void` `setShouldCacheNodes(boolean b)` If setShouldCacheNodes(true) is called, then nodes will be cached, enabling random access, and giving the ability to do sorts and the like.

### Methods inherited from class org.apache.xpath.objects.XObject

`appendToFsb, bool, boolWithSideEffects, callVisitors, castToType, create, create, deepEquals, destruct, dispatchCharactersEvents, equals, execute, getFresh, getType, getTypeString, greaterThan, greaterThanOrEqual, iter, lessThan, lessThanOrEqual, mutableNodeset, nodelist, nodeset, notEquals, num, numWithSideEffects, object, rtf, rtf, rtree, rtree, str, toString, xstr`

### 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`

### Constructor Detail

#### NodeSequence

    public NodeSequence(java.lang.Object nodeVector)

Create a new NodeSequence from a (already cloned) iterator.

Parameters:
  `nodeVector` -

#### NodeSequence

    public NodeSequence()

Create a new NodeSequence in an invalid (null) state.

### Method Detail

#### hasCache

    public boolean hasCache()

If the iterator needs to cache nodes as they are fetched, then this method returns true.

#### setIter

    public final void setIter(DTMIterator iter)

Set the functional iterator that fetches nodes.

Parameters:
  `iter` - The iterator that is to be contained.

#### getContainedIter

    public final DTMIterator getContainedIter()

Get the functional iterator that fetches nodes.

Returns:
  The contained iterator.

#### getDTM

    public DTM getDTM(int nodeHandle)

Description copied from interface: `DTMIterator`
Get an instance of a DTM that "owns" a node handle. Since a node iterator may be passed without a DTMManager, this allows the caller to easily get the DTM using just the iterator.

Specified by:
  `getDTM` in interface `DTMIterator`
Parameters:
  `nodeHandle` - the nodeHandle.
Returns:
  a non-null DTM reference.
See Also:
  `DTMIterator.getDTM(int)`

#### getDTMManager

    public DTMManager getDTMManager()

Description copied from interface: `DTMIterator`
Get an instance of the DTMManager. Since a node iterator may be passed without a DTMManager, this allows the caller to easily get the DTMManager using just the iterator.

Specified by:
  `getDTMManager` in interface `DTMIterator`
Returns:
  a non-null DTMManager reference.
See Also:
  `DTMIterator.getDTMManager()`

#### getRoot

    public int getRoot()

Description copied from interface: `DTMIterator`
The root node of the `DTMIterator`, as specified when it was created. Note the root node is not the root node of the document tree, but the context node from where the iteration begins and ends.

Specified by:
  `getRoot` in interface `DTMIterator`
Returns:
  nodeHandle int Handle of the context node.
See Also:
  `DTMIterator.getRoot()`

#### setRoot

    public void setRoot(int nodeHandle,
               java.lang.Object environment)

Description copied from interface: `DTMIterator`
Reset the root node of the `DTMIterator`, overriding the value specified when it was created. Note the root node is not the root node of the document tree, but the context node from where the iteration begins.

Specified by:
  `setRoot` in interface `DTMIterator`
Parameters:
  `nodeHandle` - int Handle of the context node.
  `environment` - The environment object. The environment in which this iterator operates, which should provide:
  - a node (the context node... same value as "root" defined below)
  - a pair of non-zero positive integers (the context position and the context size)
  - a set of variable bindings
  - a function library
  - the set of namespace declarations in scope for the expression.

  At this time the exact implementation of this environment is application dependent. Probably a proper interface will be created fairly soon.

See Also:
  `DTMIterator.setRoot(int, Object)`

#### reset

    public void reset()

Description copied from class: `XObject`
Reset for fresh reuse.

Specified by:
  `reset` in interface `DTMIterator`
Overrides:
  `reset` in class `XObject`
See Also:
  `DTMIterator.reset()`

#### getWhatToShow

    public int getWhatToShow()

Description copied from interface: `DTMIterator`
This attribute determines which node types are presented via the iterator. The available set of constants is defined above. Nodes not accepted by `whatToShow` will be skipped, but their children may still be considered.

Specified by:
  `getWhatToShow` in interface `DTMIterator`
Returns:
  one of the SHOW_XXX constants, or several ORed together.
See Also:
  `DTMIterator.getWhatToShow()`

#### getExpandEntityReferences

    public boolean getExpandEntityReferences()

Description copied from interface: `DTMIterator`

The value of this flag determines whether the children of entity reference nodes are visible to the iterator. If false, they and their descendants will be rejected. Note that this rejection takes precedence over `whatToShow` and the filter.

To produce a view of the document that has entity references expanded and does not expose the entity reference node itself, use the `whatToShow` flags to hide the entity reference node and set `expandEntityReferences` to true when creating the iterator. To produce a view of the document that has entity reference nodes but no entity expansion, use the `whatToShow` flags to show the entity reference node and set `expandEntityReferences` to false.

NOTE: In Xalan's use of DTM we will generally have fully expanded entity references when the document tree was built, and thus this flag will have no effect.

Specified by:
  `getExpandEntityReferences` in interface `DTMIterator`
Returns:
  true if entity references will be expanded.
See Also:
  `DTMIterator.getExpandEntityReferences()`

#### nextNode

    public int nextNode()

Description copied from interface: `DTMIterator`
Returns the next node in the set and advances the position of the iterator in the set. After a `DTMIterator` has setRoot called, the first call to `nextNode()` returns that root or (if it is rejected by the filters) the first node within its subtree which is not filtered out.

Specified by:
  `nextNode` in interface `DTMIterator`
Returns:
  The next node handle in the set being iterated over, or `DTM.NULL` if there are no more members in that set.
See Also:
  `DTMIterator.nextNode()`

#### previousNode

    public int previousNode()

Description copied from interface: `DTMIterator`
Returns the previous node in the set and moves the position of the `DTMIterator` backwards in the set.

Specified by:
  `previousNode` in interface `DTMIterator`
Returns:
  The previous node handle in the set being iterated over, or `DTM.NULL` if there are no more members in that set.
See Also:
  `DTMIterator.previousNode()`

#### detach

    public void detach()

Description copied from class: `XObject`
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.

Specified by:
  `detach` in interface `DTMIterator`
Overrides:
  `detach` in class `XObject`
See Also:
  `DTMIterator.detach()`

#### allowDetachToRelease

    public void allowDetachToRelease(boolean allowRelease)

Calling this with a value of false will cause the nodeset to be cached.

Specified by:
  `allowDetachToRelease` in interface `DTMIterator`
Overrides:
  `allowDetachToRelease` in class `XObject`
Parameters:
  `allowRelease` - true if it is OK for detach to release this iterator for pooling.
See Also:
  `DTMIterator.allowDetachToRelease(boolean)`

#### getCurrentNode

    public int getCurrentNode()

Description copied from interface: `DTMIterator`
Get the current node in the iterator. Note that this differs from the DOM's NodeIterator, where the current position lies between two nodes (as part of the maintain-relative-position semantic).

Specified by:
  `getCurrentNode` in interface `DTMIterator`
Returns:
  The current node handle, or -1.
See Also:
  `DTMIterator.getCurrentNode()`

#### isFresh

    public boolean isFresh()

Description copied from interface: `DTMIterator`
Tells if this NodeSetDTM is "fresh", in other words, if the first nextNode() that is called will return the first node in the set.

Specified by:
  `isFresh` in interface `DTMIterator`
Returns:
  true if the iteration of this list has not yet begun.
See Also:
  `DTMIterator.isFresh()`

#### setShouldCacheNodes

    public void setShouldCacheNodes(boolean b)

Description copied from interface: `DTMIterator`
If setShouldCacheNodes(true) is called, then nodes will be cached, enabling random access, and giving the ability to do sorts and the like. They are not cached by default. %REVIEW% Shouldn't the other random-access methods throw an exception if they're called on a DTMIterator with this flag set false?

Specified by:
  `setShouldCacheNodes` in interface `DTMIterator`
Parameters:
  `b` - true if the nodes should be cached.
See Also:
  `DTMIterator.setShouldCacheNodes(boolean)`

#### isMutable

    public boolean isMutable()

Description copied from interface: `DTMIterator`
Tells if this iterator can have nodes added to it or set via the `setItem(int node, int index)` method.

Specified by:
  `isMutable` in interface `DTMIterator`
Returns:
  True if the nodelist can be mutated.
See Also:
  `DTMIterator.isMutable()`

#### getCurrentPos

    public int getCurrentPos()

Description copied from interface: `DTMIterator`
Get the current position within the cached list, which is one less than the next nextNode() call will retrieve. i.e. if you call getCurrentPos() and the return is 0, the next fetch will take place at index 1.

Specified by:
  `getCurrentPos` in interface `DTMIterator`
Returns:
  The position of the iteration.
See Also:
  `DTMIterator.getCurrentPos()`

#### runTo

    public void runTo(int index)

Description copied from interface: `DTMIterator`
If an index is requested, NodeSetDTM will call this method to run the iterator to the index. By default this sets m_next to the index. If the index argument is -1, this signals that the iterator should be run to the end and completely fill the cache.

Specified by:
  `runTo` in interface `DTMIterator`
Parameters:
  `index` - The index to run to, or -1 if the iterator should be run to the end.
See Also:
  `DTMIterator.runTo(int)`

#### setCurrentPos

    public void setCurrentPos(int i)

Description copied from interface: `DTMIterator`
Set the current position in the node set.

Specified by:
  `setCurrentPos` in interface `DTMIterator`
Parameters:
  `i` - Must be a valid index.
See Also:
  `DTMIterator.setCurrentPos(int)`

#### item

    public int item(int index)

Description copied from interface: `DTMIterator`
Returns the `node handle` of an item in the collection. If `index` is greater than or equal to the number of nodes in the list, this returns `null`.

Specified by:
  `item` in interface `DTMIterator`
Parameters:
  `index` - of the item.
Returns:
  The node handle at the `index`th position in the `DTMIterator`, or `-1` if that is not a valid index.
See Also:
  `DTMIterator.item(int)`

#### setItem

    public void setItem(int node,
               int index)

Description copied from interface: `DTMIterator`
Sets the node at the specified index of this vector to be the specified node. The previous component at that position is discarded.

The index must be a value greater than or equal to 0 and less than the current size of the vector. The iterator must be in cached mode.

Meant to be used for sorted iterators.

Specified by:
  `setItem` in interface `DTMIterator`
Parameters:
  `node` - Node to set
  `index` - Index of where to set the node
See Also:
  `DTMIterator.setItem(int, int)`

#### getLength

    public int getLength()

Description copied from interface: `DTMIterator`
The number of nodes in the list. The range of valid child node indices is 0 to `length-1` inclusive. Note that this requires running the iterator to completion, and presumably filling the cache.

Specified by:
  `getLength` in interface `DTMIterator`
Returns:
  The number of nodes in the list.
See Also:
  `DTMIterator.getLength()`

#### cloneWithReset

    public DTMIterator cloneWithReset()
                               throws java.lang.CloneNotSupportedException

Note: Not a deep clone.

Specified by:
  `cloneWithReset` in interface `DTMIterator`
Returns:
  A clone of this iteration that has been reset.
Throws:
  `java.lang.CloneNotSupportedException`
See Also:
  `DTMIterator.cloneWithReset()`

#### clone

    public java.lang.Object clone()
                           throws java.lang.CloneNotSupportedException

Get a clone of this iterator, but don't reset the iteration in the process, so that it may be used from the current position. Note: Not a deep clone.

Specified by:
  `clone` in interface `DTMIterator`
Overrides:
  `clone` in class `java.lang.Object`
Returns:
  A clone of this object.
Throws:
  `java.lang.CloneNotSupportedException`

#### isDocOrdered

    public boolean isDocOrdered()

Description copied from interface: `DTMIterator`
Returns true if all the nodes in the iteration well be returned in document order.

Specified by:
  `isDocOrdered` in interface `DTMIterator`
Returns:
  true if all the nodes in the iteration well be returned in document order.
See Also:
  `DTMIterator.isDocOrdered()`

#### getAxis

    public int getAxis()

Description copied from interface: `DTMIterator`
Returns the axis being iterated, if it is known.

Specified by:
  `getAxis` in interface `DTMIterator`
Returns:
  Axis.CHILD, etc., or -1 if the axis is not known or is of multiple types.
See Also:
  `DTMIterator.getAxis()`

#### getAnalysisBits

    public int getAnalysisBits()

Description copied from interface: `PathComponent`
Get the analysis bits for this path component, as defined in the WalkerFactory.

Specified by:
  `getAnalysisBits` in interface `PathComponent`
Returns:
  One of WalkerFactory#BIT_DESCENDANT, etc.
See Also:
  `PathComponent.getAnalysisBits()`

#### fixupVariables

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

Description copied from class: `XObject`
XObjects should not normally need to fix up variables.

Overrides:
  `fixupVariables` in class `XObject`
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
See Also:
  `Expression.fixupVariables(Vector, int)`