DTMIterators
are used to step through a (possibly
filtered) set of nodes. Their API is modeled largely after the DOM
NodeIterator.
A DTMIterator is a somewhat unusual type of iterator, in that it can serve both single node iteration and random access.
The DTMIterator's traversal semantics, i.e. how it walks the tree, are specified when it is created, possibly and probably by an XPath LocationPath or a UnionExpr.
A DTMIterator is meant to be created once as a master static object, and then cloned many times for runtime use. Or the master object itself may be used for simpler use cases.
At this time, we do not expect DTMIterator to emulate NodeIterator's "maintain relative position" semantics under document mutation. It's likely to respond more like the TreeWalker's "current node" semantics. However, since the base DTM is immutable, this issue currently makes no practical difference.
State: In progress!!
Modifier and Type | Field and Description |
---|---|
public static final short | FILTER_ACCEPT
Accept the node. |
public static final short | FILTER_REJECT
Reject the node. |
public static final short | FILTER_SKIP
Skip this single node. |
Modifier and Type | Method and Description |
---|---|
public void | allowDetachToRelease(boolean
true if it is OK for detach to release this iterator
for pooling. allowRelease)Specify if it's OK for detach to release the iterator for reuse. |
public Object | Returns: A clone of this object.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. |
public DTMIterator | Returns: A clone of this iteration that has been reset.Get a cloned Iterator that is reset to the start of the iteration. |
public void | detach()
Detaches the |
public int | Returns: Axis.CHILD, etc., or -1 if the axis is not known or is of multiple types.Returns the axis being iterated, if it is known. |
public int | |
public int | Returns: The position of the iteration.Get the current position within the cached list, which is one less than the next nextNode() call will retrieve. |
public DTM | Returns: a non-null DTM reference.the nodeHandle. nodeHandle)Get an instance of a DTM that "owns" a node handle. |
public DTMManager | |
public boolean | Returns: true if entity references will be expanded.The value of this flag determines whether the children of entity reference nodes are visible to the iterator. |
public int | |
public int | Returns: nodeHandle int Handle of the context node.The root node of the |
public int | Returns: one of the SHOW_XXX constants, or several ORed together.This attribute determines which node types are presented via the iterator. |
public boolean | Returns: true if all the nodes in the iteration well be returned in document order.Returns true if all the nodes in the iteration well be returned in document order. |
public boolean | Returns: true if the iteration of this list has not yet begun.Tells if this NodeSetDTM is "fresh", in other words, if the first nextNode() that is called will return the first node in the set. |
public boolean | Returns: True if the nodelist can be mutated.Tells if this iterator can have nodes added to it or set via
the |
public int | Returns: The node handle at theindex th position in the
DTMIterator , or -1 if that is not a valid
index.of the item. index)Returns the |
public int | Returns: The next node handle in the set being iterated over, orDTM.NULL if there are no more members in that set.Returns the next node in the set and advances the position of the iterator in the set. |
public int | Returns: The previous node handle in the set being iterated over, orDTM.NULL if there are no more members in that set.Returns the previous node in the set and moves the position of the
|
public void | |
public void | runTo(int
The index to run to, or -1 if the iterator should be run
to the end. index)If an index is requested, NodeSetDTM will call this method to run the iterator to the index. |
public void | |
public void | setItem(int
Node to set node, int Index of where to set the node index)Sets the node at the specified index of this vector to be the specified node. |
public void | setRoot(int
int Handle of the context node. nodeHandle, Object The environment object.
The environment in which this iterator operates, which should provide:
environment)
At this time the exact implementation of this environment is application dependent. Probably a proper interface will be created fairly soon. Reset the root node of the |
public void | setShouldCacheNodes(boolean
true if the nodes should be cached. b)If setShouldCacheNodes(true) is called, then nodes will be cached, enabling random access, and giving the ability to do sorts and the like. |
FILTER_ACCEPT | back to summary |
---|---|
public static final short FILTER_ACCEPT Accept the node. |
FILTER_REJECT | back to summary |
---|---|
public static final short FILTER_REJECT Reject the node. Same behavior as FILTER_SKIP. (In the DOM these differ when applied to a TreeWalker but have the same result when applied to a NodeIterator). |
FILTER_SKIP | back to summary |
---|---|
public static final short FILTER_SKIP Skip this single node. |
allowDetachToRelease | back to summary |
---|---|
public void allowDetachToRelease(boolean allowRelease) Specify if it's OK for detach to release the iterator for reuse.
|
clone | back to summary |
---|---|
public Object clone() throws 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.
|
cloneWithReset | back to summary |
---|---|
public DTMIterator cloneWithReset() throws CloneNotSupportedException Get a cloned Iterator that is reset to the start of the iteration.
|
detach | back to summary |
---|---|
public void detach() Detaches the |
getAxis | back to summary |
---|---|
public int getAxis() Returns the axis being iterated, if it is known.
|
getCurrentNode | back to summary |
---|---|
public int getCurrentNode() 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).
|
getCurrentPos | back to summary |
---|---|
public int getCurrentPos() 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.
|
getDTM | back to summary |
---|---|
public DTM getDTM(int nodeHandle) 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.
|
getDTMManager | back to summary |
---|---|
public DTMManager getDTMManager() 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.
|
getExpandEntityReferences | back to summary |
---|---|
public boolean getExpandEntityReferences() 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 To produce a view of the document that has entity references
expanded and does not expose the entity reference node itself, use
the 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.
|
getLength | back to summary |
---|---|
public int getLength() The number of nodes in the list. The range of valid child node indices
is 0 to
|
getRoot | back to summary |
---|---|
public int getRoot() The root node of the
|
getWhatToShow | back to summary |
---|---|
public int getWhatToShow() This attribute determines which node types are presented via the
iterator. The available set of constants is defined above.
Nodes not accepted by
|
isDocOrdered | back to summary |
---|---|
public boolean isDocOrdered() Returns true if all the nodes in the iteration well be returned in document order.
|
isFresh | back to summary |
---|---|
public 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.
|
isMutable | back to summary |
---|---|
public boolean isMutable() Tells if this iterator can have nodes added to it or set via
the
|
item | back to summary |
---|---|
public int item(int index) Returns the
|
nextNode | back to summary |
---|---|
public int nextNode() Returns the next node in the set and advances the position of the
iterator in the set. After a
|
previousNode | back to summary |
---|---|
public int previousNode() Returns the previous node in the set and moves the position of the
|
reset | back to summary |
---|---|
public void reset() Reset the iterator to the start. After resetting, the next node returned will be the root node -- or, if that's filtered out, the first node within the root's subtree which is _not_ skipped by the filters. |
runTo | back to summary |
---|---|
public void runTo(int index) 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.
|
setCurrentPos | back to summary |
---|---|
public void setCurrentPos(int i) Set the current position in the node set.
|
setItem | back to summary |
---|---|
public void setItem(int node, int index) 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.
|
setRoot | back to summary |
---|---|
public void setRoot(int nodeHandle, Object environment) Reset the root node of the
|
setShouldCacheNodes | back to summary |
---|---|
public 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. 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?
|