org.apache.xpath

## Class NodeSet

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

All Implemented Interfaces:
  java.lang.Cloneable, ContextNodeList, NodeList, NodeIterator

    public class NodeSet
    extends java.lang.Object
    implements NodeList, NodeIterator, java.lang.Cloneable, ContextNodeList

The NodeSet class can act as either a NodeVector, NodeList, or NodeIterator. However, in order for it to act as a NodeVector or NodeList, it's required that setShouldCacheNodes(true) be called before the first nextNode() is called, in order that nodes can be added as they are fetched. Derived classes that implement iterators must override runTo(int index), in order that they may run the iteration to the given index.

Note that we directly implement the DOM's NodeIterator interface. We do not emulate all the behavior of the standard NodeIterator. In particular, we do not guarantee to present a "live view" of the document ... but in XSLT, the source document should never be mutated, so this should never be an issue.

Thought: Should NodeSet really implement NodeList and NodeIterator, or should there be specific subclasses of it which do so? The advantage of doing it all here is that all NodeSets will respond to the same calls; the disadvantage is that some of them may return less-than-enlightening results when you do so.

Usage:
  **For advanced use only**

### Constructor Summary

Constructors
Constructor and Description
`NodeSet()` Create an empty nodelist.
`NodeSet(int blocksize)` Create an empty, using the given block size.
`NodeSet(Node node)` Create a NodeSet which contains the given Node.
`NodeSet(NodeIterator ni)` Create a NodeSet, and copy the members of the given NodeIterator into it.
`NodeSet(NodeList nodelist)` Create a NodeSet, and copy the members of the given nodelist into it.
`NodeSet(NodeSet nodelist)` Create a NodeSet, and copy the members of the given NodeSet into it.

### Method Summary

Methods
`void` `addElement(Node value)` Append a Node onto the vector.
`void` `addNode(Node n)` Add a node to the NodeSet.
`int` `addNodeInDocOrder(Node node, boolean test, XPathContext support)` Add the node into a vector of nodes where it should occur in document order.
`int` `addNodeInDocOrder(Node node, XPathContext support)` Add the node into a vector of nodes where it should occur in document order.
`void` `addNodes(NodeIterator iterator)` Copy NodeList members into this nodelist, adding in document order.
`void` `addNodes(NodeList nodelist)` Copy NodeList members into this nodelist, adding in document order.
`void` `addNodes(NodeSet ns)` Copy NodeList members into this nodelist, adding in document order.
`void` `addNodesInDocOrder(NodeIterator iterator, XPathContext support)` Copy NodeList members into this nodelist, adding in document order.
`void` `addNodesInDocOrder(NodeList nodelist, XPathContext support)` Copy NodeList members into this nodelist, adding in document order.
`void` `appendNodes(NodeSet nodes)` Append the nodes to the list.
`java.lang.Object` `clone()` Get a cloned LocPathIterator.
`NodeIterator` `cloneWithReset()` Get a cloned Iterator, and reset its state to the beginning of the iteration.
`boolean` `contains(Node s)` Tell if the table contains the given node.
`void` `detach()` Detaches the iterator from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state.
`Node` `elementAt(int i)` Get the nth element.
`Node` `getCurrentNode()` Return the last fetched node.
`int` `getCurrentPos()` Get the current position, which is one less than the next nextNode() call will retrieve.
`boolean` `getExpandEntityReferences()` The value of this flag determines whether the children of entity reference nodes are visible to the iterator.
`NodeFilter` `getFilter()` The filter object used to screen nodes.
`int` `getLast()` Get the index of the last node in this list.
`int` `getLength()` The number of nodes in the list.
`Node` `getRoot()` The root node of the `NodeIterator`, as specified when it was created.
`boolean` `getShouldCacheNodes()` Get whether or not this is a cached node set.
`int` `getWhatToShow()` This attribute determines which node types are presented via the iterator.
`int` `indexOf(Node elem)` Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.
`int` `indexOf(Node elem, int index)` Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.
`void` `insertElementAt(Node value, int at)` Inserts the specified node in this vector at the specified index.
`void` `insertNode(Node n, int pos)` Insert a node at a given position.
`boolean` `isFresh()` Tells if this NodeSet is "fresh", in other words, if the first nextNode() that is called will return the first node in the set.
`Node` `item(int index)` Returns the `index`th item in the collection.
`Node` `nextNode()` Returns the next node in the set and advances the position of the iterator in the set.
`Node` `peepOrNull()` Return the node at the top of the stack without popping the stack.
`Node` `peepTail()` Return the node at the tail of the vector without popping Special purpose method for TransformerImpl, pushElemTemplateElement.
`Node` `peepTailSub1()` Return the node one position from the tail without popping.
`Node` `pop()` Pop a node from the tail of the vector and return the result.
`Node` `popAndTop()` Pop a node from the tail of the vector and return the top of the stack after the pop.
`void` `popPair()` Pop a pair of nodes from the tail of the stack.
`void` `popQuick()` Pop a node from the tail of the vector.
`Node` `previousNode()` Returns the previous node in the set and moves the position of the iterator backwards in the set.
`void` `push(Node value)` Append a Node onto the vector.
`void` `pushPair(Node v1, Node v2)` Push a pair of nodes into the stack.
`void` `removeAllElements()` Inserts the specified node in this vector at the specified index.
`boolean` `removeElement(Node s)` Removes the first occurrence of the argument from this vector.
`void` `removeElementAt(int i)` Deletes the component at the specified index.
`void` `removeNode(Node n)` Remove a node.
`void` `reset()` Reset the iterator.
`void` `runTo(int index)` If an index is requested, NodeSet will call this method to run the iterator to the index.
`void` `setCurrentPos(int i)` Set the current position in the node set.
`void` `setElementAt(Node node, int index)` Sets the component at the specified index of this vector to be the specified object.
`void` `setLast(int last)` Set the index of the last node in this list.
`void` `setShouldCacheNodes(boolean b)` If setShouldCacheNodes(true) is called, then nodes will be cached.
`void` `setTail(Node n)` Set the tail of the stack to the given node.
`void` `setTailSub1(Node n)` Set the given node one position from the tail.
`int` `size()` Get the length of the list.

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

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

### Constructor Detail

#### NodeSet

    public NodeSet()

Create an empty nodelist.

#### NodeSet

    public NodeSet(int blocksize)

Create an empty, using the given block size.

Parameters:
  `blocksize` - Size of blocks to allocate

#### NodeSet

    public NodeSet(NodeList nodelist)

Create a NodeSet, and copy the members of the given nodelist into it.

Parameters:
  `nodelist` - List of Nodes to be made members of the new set.

#### NodeSet

    public NodeSet(NodeSet nodelist)

Create a NodeSet, and copy the members of the given NodeSet into it.

Parameters:
  `nodelist` - Set of Nodes to be made members of the new set.

#### NodeSet

    public NodeSet(NodeIterator ni)

Create a NodeSet, and copy the members of the given NodeIterator into it.

Parameters:
  `ni` - Iterator which yields Nodes to be made members of the new set.

#### NodeSet

    public NodeSet(Node node)

Create a NodeSet which contains the given Node.

Parameters:
  `node` - Single node to be added to the new set.

### Method Detail

#### getRoot

    public Node getRoot()

Description copied from interface: `NodeIterator`
The root node of the `NodeIterator`, as specified when it was created.

Specified by:
  `getRoot` in interface `NodeIterator`
Returns:
  The root node of the Iterator, as specified when it was created. For non-Iterator NodeSets, this will be null.

#### cloneWithReset

    public NodeIterator cloneWithReset()
                                throws java.lang.CloneNotSupportedException

Get a cloned Iterator, and reset its state to the beginning of the iteration.

Specified by:
  `cloneWithReset` in interface `ContextNodeList`
Returns:
  a new NodeSet of the same type, having the same state... except that the reset() operation has been called.
Throws:
  `java.lang.CloneNotSupportedException` - if this subclass of NodeSet does not support the clone() operation.

#### reset

    public void reset()

Reset the iterator. May have no effect on non-iterator Nodesets.

Specified by:
  `reset` in interface `ContextNodeList`

#### getWhatToShow

    public int getWhatToShow()

This attribute determines which node types are presented via the iterator. The available set of constants is defined in the `NodeFilter` interface. For NodeSets, the mask has been hardcoded to show all nodes except EntityReference nodes, which have no equivalent in the XPath data model.

Specified by:
  `getWhatToShow` in interface `NodeIterator`
Returns:
  integer used as a bit-array, containing flags defined in the DOM's NodeFilter class. The value will be `SHOW_ALL & ~SHOW_ENTITY_REFERENCE`, meaning that only entity references are suppressed.

#### getFilter

    public NodeFilter getFilter()

The filter object used to screen nodes. Filters are applied to further reduce (and restructure) the NodeIterator's view of the document. In our case, we will be using hardcoded filters built into our iterators... but getFilter() is part of the DOM's NodeIterator interface, so we have to support it.

Specified by:
  `getFilter` in interface `NodeIterator`
Returns:
  null, which is slightly misleading. True, there is no user-written filter object, but in fact we are doing some very sophisticated custom filtering. A DOM purist might suggest returning a placeholder object just to indicate that this is not going to return all nodes selected by whatToShow.

#### getExpandEntityReferences

    public boolean getExpandEntityReferences()

The value of this flag determines whether the children of entity reference nodes are visible to the iterator. If false, they will be skipped over.
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.

Specified by:
  `getExpandEntityReferences` in interface `NodeIterator`
Returns:
  true for all iterators based on NodeSet, meaning that the contents of EntityRefrence nodes may be returned (though whatToShow says that the EntityReferences themselves are not shown.)

#### nextNode

    public Node nextNode()
                  throws DOMException

Returns the next node in the set and advances the position of the iterator in the set. After a NodeIterator is created, the first call to nextNode() returns the first node in the set.

Specified by:
  `nextNode` in interface `NodeIterator`
Returns:
  The next `Node` in the set being iterated over, or `null` if there are no more members in that set.
Throws:
  `DOMException` - INVALID_STATE_ERR: Raised if this method is called after the `detach` method was invoked.

#### previousNode

    public Node previousNode()
                      throws DOMException

Returns the previous node in the set and moves the position of the iterator backwards in the set.

Specified by:
  `previousNode` in interface `NodeIterator`
Returns:
  The previous `Node` in the set being iterated over, or`null` if there are no more members in that set.
Throws:
  `DOMException` - INVALID_STATE_ERR: Raised if this method is called after the `detach` method was invoked.
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a cached type, and hence doesn't know what the previous node was.

#### detach

    public void detach()

Detaches the iterator 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 the exception INVALID_STATE_ERR.

This operation is a no-op in NodeSet, and will not cause INVALID_STATE_ERR to be raised by later operations.

Specified by:
  `detach` in interface `NodeIterator`

#### isFresh

    public boolean isFresh()

Tells if this NodeSet 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 `ContextNodeList`
Returns:
  true if nextNode() would return the first node in the set, false if it would return a later one.

#### runTo

    public void runTo(int index)

If an index is requested, NodeSet 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.

Specified by:
  `runTo` in interface `ContextNodeList`
Parameters:
  `index` - Position to advance (or retreat) to, with 0 requesting the reset ("fresh") position and -1 (or indeed any out-of-bounds value) requesting the final position.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not one of the types which supports indexing/counting.

#### item

    public Node item(int index)

Returns the `index`th item in the collection. If `index` is greater than or equal to the number of nodes in the list, this returns `null`. TODO: What happens if index is out of range?

Specified by:
  `item` in interface `NodeList`
Parameters:
  `index` - Index into the collection.
Returns:
  The node at the `index`th position in the `NodeList`, or `null` if that is not a valid index.

#### getLength

    public int getLength()

The number of nodes in the list. The range of valid child node indices is 0 to `length-1` inclusive. Note that this operation requires finding all the matching nodes, which may defeat attempts to defer that work.

Specified by:
  `getLength` in interface `NodeList`
Returns:
  integer indicating how many nodes are represented by this list.

#### addNode

    public void addNode(Node n)

Add a node to the NodeSet. Not all types of NodeSets support this operation

Parameters:
  `n` - Node to be added
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### insertNode

    public void insertNode(Node n,
                  int pos)

Insert a node at a given position.

Parameters:
  `n` - Node to be added
  `pos` - Offset at which the node is to be inserted, with 0 being the first position.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### removeNode

    public void removeNode(Node n)

Remove a node.

Parameters:
  `n` - Node to be added
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodes

    public void addNodes(NodeList nodelist)

Copy NodeList members into this nodelist, adding in document order. If a node is null, don't add it.

Parameters:
  `nodelist` - List of nodes which should now be referenced by this NodeSet.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodes

    public void addNodes(NodeSet ns)

Copy NodeList members into this nodelist, adding in document order. Only genuine node references will be copied; nulls appearing in the source NodeSet will not be added to this one.

In case you're wondering why this function is needed: NodeSet implements both NodeIterator and NodeList. If this method isn't provided, Java can't decide which of those to use when addNodes() is invoked. Providing the more-explicit match avoids that ambiguity.)

Parameters:
  `ns` - NodeSet whose members should be merged into this NodeSet.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodes

    public void addNodes(NodeIterator iterator)

Copy NodeList members into this nodelist, adding in document order. Null references are not added.

Parameters:
  `iterator` - NodeIterator which yields the nodes to be added.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodesInDocOrder

    public void addNodesInDocOrder(NodeList nodelist,
                          XPathContext support)

Copy NodeList members into this nodelist, adding in document order. If a node is null, don't add it.

Parameters:
  `nodelist` - List of nodes to be added
  `support` - The XPath runtime context.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodesInDocOrder

    public void addNodesInDocOrder(NodeIterator iterator,
                          XPathContext support)

Copy NodeList members into this nodelist, adding in document order. If a node is null, don't add it.

Parameters:
  `iterator` - NodeIterator which yields the nodes to be added.
  `support` - The XPath runtime context.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodeInDocOrder

    public int addNodeInDocOrder(Node node,
                        boolean test,
                        XPathContext support)

Add the node into a vector of nodes where it should occur in document order.

Parameters:
  `node` - The node to be added.
  `test` - true if we should test for doc order
  `support` - The XPath runtime context.
Returns:
  insertIndex.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### addNodeInDocOrder

    public int addNodeInDocOrder(Node node,
                        XPathContext support)

Add the node into a vector of nodes where it should occur in document order.

Parameters:
  `node` - The node to be added.
  `support` - The XPath runtime context.
Returns:
  The index where it was inserted.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a mutable type.

#### getCurrentPos

    public int getCurrentPos()

Get the current position, 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 `ContextNodeList`
Returns:
  The the current position index.

#### setCurrentPos

    public void setCurrentPos(int i)

Set the current position in the node set.

Specified by:
  `setCurrentPos` in interface `ContextNodeList`
Parameters:
  `i` - Must be a valid index.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a cached type, and thus doesn't permit indexed access.

#### getCurrentNode

    public Node getCurrentNode()

Return the last fetched node. Needed to support the UnionPathIterator.

Specified by:
  `getCurrentNode` in interface `ContextNodeList`
Returns:
  the last fetched node.
Throws:
  `java.lang.RuntimeException` - thrown if this NodeSet is not of a cached type, and thus doesn't permit indexed access.

#### getShouldCacheNodes

    public boolean getShouldCacheNodes()

Get whether or not this is a cached node set.

Returns:
  True if this list is cached.

#### setShouldCacheNodes

    public void setShouldCacheNodes(boolean b)

If setShouldCacheNodes(true) is called, then nodes will be cached. They are not cached by default. This switch must be set before the first call to nextNode is made, to ensure that all nodes are cached.

Specified by:
  `setShouldCacheNodes` in interface `ContextNodeList`
Parameters:
  `b` - true if this node set should be cached.
Throws:
  `java.lang.RuntimeException` - thrown if an attempt is made to request caching after we've already begun stepping through the nodes in this set.

#### getLast

    public int getLast()

Description copied from interface: `ContextNodeList`
Get the index of the last node in this list.

Specified by:
  `getLast` in interface `ContextNodeList`
Returns:
  the index of the last node in this list.

#### setLast

    public void setLast(int last)

Description copied from interface: `ContextNodeList`
Set the index of the last node in this list.

Specified by:
  `setLast` in interface `ContextNodeList`
Parameters:
  `last` - the index of the last node in this list.

#### clone

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

Get a cloned LocPathIterator.

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

#### size

    public int size()

Get the length of the list.

Specified by:
  `size` in interface `ContextNodeList`
Returns:
  Number of nodes in this NodeVector

#### addElement

    public void addElement(Node value)

Append a Node onto the vector.

Parameters:
  `value` - Node to add to the vector

#### push

    public final void push(Node value)

Append a Node onto the vector.

Parameters:
  `value` - Node to add to the vector

#### pop

    public final Node pop()

Pop a node from the tail of the vector and return the result.

Returns:
  the node at the tail of the vector

#### popAndTop

    public final Node popAndTop()

Pop a node from the tail of the vector and return the top of the stack after the pop.

Returns:
  The top of the stack after it's been popped

#### popQuick

    public final void popQuick()

Pop a node from the tail of the vector.

#### peepOrNull

    public final Node peepOrNull()

Return the node at the top of the stack without popping the stack. Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

Returns:
  Node at the top of the stack or null if stack is empty.

#### pushPair

    public final void pushPair(Node v1,
                Node v2)

Push a pair of nodes into the stack. Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

Parameters:
  `v1` - First node to add to vector
  `v2` - Second node to add to vector

#### popPair

    public final void popPair()

Pop a pair of nodes from the tail of the stack. Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

#### setTail

    public final void setTail(Node n)

Set the tail of the stack to the given node. Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

Parameters:
  `n` - Node to set at the tail of vector

#### setTailSub1

    public final void setTailSub1(Node n)

Set the given node one position from the tail. Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

Parameters:
  `n` - Node to set

#### peepTail

    public final Node peepTail()

Return the node at the tail of the vector without popping Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

Returns:
  Node at the tail of the vector

#### peepTailSub1

    public final Node peepTailSub1()

Return the node one position from the tail without popping. Special purpose method for TransformerImpl, pushElemTemplateElement. Performance critical.

Returns:
  Node one away from the tail

#### insertElementAt

    public void insertElementAt(Node value,
                       int at)

Inserts the specified node in this vector at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

Parameters:
  `value` - Node to insert
  `at` - Position where to insert

#### appendNodes

    public void appendNodes(NodeSet nodes)

Append the nodes to the list.

Parameters:
  `nodes` - NodeVector to append to this list

#### removeAllElements

    public void removeAllElements()

Inserts the specified node in this vector at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted upward to have an index one greater than the value it had previously.

#### removeElement

    public boolean removeElement(Node s)

Removes the first occurrence of the argument from this vector. If the object is found in this vector, each component in the vector with an index greater or equal to the object's index is shifted downward to have an index one smaller than the value it had previously.

Parameters:
  `s` - Node to remove from the list
Returns:
  True if the node was successfully removed

#### removeElementAt

    public void removeElementAt(int i)

Deletes the component at the specified index. Each component in this vector with an index greater or equal to the specified index is shifted downward to have an index one smaller than the value it had previously.

Parameters:
  `i` - Index of node to remove

#### setElementAt

    public void setElementAt(Node node,
                    int index)

Sets the component at the specified index of this vector to be the specified object. 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.

Parameters:
  `node` - Node to set
  `index` - Index of where to set the node

#### elementAt

    public Node elementAt(int i)

Get the nth element.

Parameters:
  `i` - Index of node to get
Returns:
  Node at specified index

#### contains

    public boolean contains(Node s)

Tell if the table contains the given node.

Parameters:
  `s` - Node to look for
Returns:
  True if the given node was found.

#### indexOf

    public int indexOf(Node elem,
              int index)

Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.

Parameters:
  `elem` - Node to look for
  `index` - Index of where to start the search
Returns:
  the index of the first occurrence of the object argument in this vector at position index or later in the vector; returns -1 if the object is not found.

#### indexOf

    public int indexOf(Node elem)

Searches for the first occurence of the given argument, beginning the search at index, and testing for equality using the equals method.

Parameters:
  `elem` - Node to look for
Returns:
  the index of the first occurrence of the object argument in this vector at position index or later in the vector; returns -1 if the object is not found.