org.apache.xpath
public class NodeSet extends Object implements NodeList, NodeIterator, 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.
UNKNOWN: advanced
Constructor Summary | |
---|---|
NodeSet()
Create an empty nodelist. | |
NodeSet(int blocksize)
Create an empty, using the given block size.
| |
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.
| |
NodeSet(NodeIterator ni)
Create a NodeSet, and copy the members of the
given NodeIterator into it.
| |
NodeSet(Node node)
Create a NodeSet which contains the given Node.
|
Method Summary | |
---|---|
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(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 | addNodes(NodeIterator iterator)
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 | addNodesInDocOrder(NodeIterator iterator, XPathContext support)
Copy NodeList members into this nodelist, adding in
document order. |
void | appendNodes(NodeSet nodes)
Append the nodes to the list.
|
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. i.e. if
you call getCurrentPos() and the return is 0, the next
fetch will take place at index 1.
|
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() |
int | getLength()
The number of nodes in the list. |
Node | getRoot() |
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, int index)
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)
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) |
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.
|
Parameters: blocksize Size of blocks to allocate
Parameters: nodelist List of Nodes to be made members of the new set.
Parameters: nodelist Set of Nodes to be made members of the new set.
Parameters: ni Iterator which yields Nodes to be made members of the new set.
Parameters: node Single node to be added to the new set.
Parameters: value Node to add to the vector
Parameters: n Node to be added
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: node The node to be added. test true if we should test for doc order support The XPath runtime context.
Returns: insertIndex.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: node The node to be added. support The XPath runtime context.
Returns: The index where it was inserted.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: nodelist List of nodes which should now be referenced by this NodeSet.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
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: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: iterator NodeIterator which yields the nodes to be added.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: nodelist List of nodes to be added support The XPath runtime context.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: iterator NodeIterator which yields the nodes to be added. support The XPath runtime context.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Parameters: nodes NodeVector to append to this list
Returns: A clone of this
Throws: CloneNotSupportedException
Returns: a new NodeSet of the same type, having the same state... except that the reset() operation has been called.
Throws: CloneNotSupportedException if this subclass of NodeSet does not support the clone() operation.
Parameters: s Node to look for
Returns: True if the given node was found.
detach
has been invoked, calls to
nextNode
orpreviousNode
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.
Parameters: i Index of node to get
Returns: Node at specified index
Returns: the last fetched node.
Throws: RuntimeException thrown if this NodeSet is not of a cached type, and thus doesn't permit indexed access.
Returns: The the current position index.
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.)
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.
length-1
inclusive. Note that this operation requires
finding all the matching nodes, which may defeat attempts to defer
that work.
Returns: integer indicating how many nodes are represented by this list.
Returns: The root node of the Iterator, as specified when it was created. For non-Iterator NodeSets, this will be null.
Returns: True if this list is cached.
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.
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.
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.
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.
Parameters: value Node to insert at Position where to insert
Parameters: n Node to be added pos Offset at which the node is to be inserted, with 0 being the first position.
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
Returns: true if nextNode() would return the first node in the set, false if it would return a later one.
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?
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.
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.
Returns: Node at the top of the stack or null if stack is empty.
Returns: Node at the tail of the vector
Returns: Node one away from the tail
Returns: the node at the tail of the vector
Returns: The top of the stack after it's been popped
Returns: The previous Node
in the set being iterated over,
ornull
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. RuntimeException thrown if this NodeSet is not of
a cached type, and hence doesn't know what the previous node was.
Parameters: value Node to add to the vector
Parameters: v1 First node to add to vector v2 Second node to add to vector
Parameters: s Node to remove from the list
Returns: True if the node was successfully removed
Parameters: i Index of node to remove
Parameters: n Node to be added
Throws: RuntimeException thrown if this NodeSet is not of a mutable type.
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: RuntimeException thrown if this NodeSet is not one of the types which supports indexing/counting.
Parameters: i Must be a valid index.
Throws: RuntimeException thrown if this NodeSet is not of a cached type, and thus doesn't permit indexed access.
Parameters: node Node to set index Index of where to set the node
Parameters: b true if this node set should be cached.
Throws: RuntimeException thrown if an attempt is made to request caching after we've already begun stepping through the nodes in this set.
Parameters: n Node to set at the tail of vector
Parameters: n Node to set
Returns: Number of nodes in this NodeVector