org.apache.xpath.axes
Class UnionPathIterator

java.lang.Object
  |
  +--org.apache.xpath.Expression
        |
        +--org.apache.xpath.axes.UnionPathIterator

public class UnionPathIterator

extends Expression

implements java.lang.Cloneable, NodeIterator, ContextNodeList

**For advanced use only** This class extends NodeSet, which implements NodeIterator, and fetches nodes one at a time in document order based on a XPath UnionExpr. As each node is iterated via nextNode(), the node is also stored in the NodeVector, so that previousNode() can easily be done.

See Also:

Serialized Form

Constructor Summary

UnionPathIterator()
Constructor to create an instance which you can add location paths to.

UnionPathIterator(Compiler compiler, int opPos)
Create a UnionPathIterator object, including creation of location path iterators from the opcode list, and call back into the Compiler to create predicate expressions.

Method Summary

void	addIterator(LocPathIterator iter) Add an iterator to the union list.
java.lang.Object	clone() Get a cloned LocPathIterator that holds the same position as this iterator.
NodeIterator	cloneWithReset() Get a cloned Iterator that is reset to the beginning of the query.
void	detach() Detaches the iterator from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state.
XObject	execute(XPathContext xctxt) Execute this iterator, meaning create a clone that can store state, and initialize it for fast execution from the current runtime state.
Node	getCurrentContextNode() The node context from where the expression is being executed from (i.e.
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 used to screen nodes.
int	getLast() Get the index of the last node in the itteration.
Node	getRoot() The root node of the Iterator, as specified when it was created.
int	getWhatToShow() This attribute determines which node types are presented via the iterator.
void	initContext(XPathContext execContext) Initialize the context values for this expression after it is cloned.
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	nextNode() Returns the next node in the set and advances the position of the iterator in the set.
Node	previousNode() Returns the previous node in the set and moves the position of the iterator backwards in the set.
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	setLast(int last) Set the index of the last node in the itteration.
void	setShouldCacheNodes(boolean b) If setShouldCacheNodes(true) is called, then nodes will be cached.
int	size() Get the length of the list.

Methods inherited from class org.apache.xpath.Expression

assert, canTraverseOutsideSubtree, error, setSourceLocator, warn

Methods inherited from class java.lang.Object

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

Constructor Detail

UnionPathIterator

public UnionPathIterator()

Constructor to create an instance which you can add location paths to.

UnionPathIterator

public UnionPathIterator(Compiler compiler,
                         int opPos)
                  throws TransformerException

Create a UnionPathIterator object, including creation of location path iterators from the opcode list, and call back into the Compiler to create predicate expressions.

Parameters:

compiler - The Compiler which is creating this expression.

opPos - The position of this iterator in the opcode list from the compiler.

Throws:

TransformerException -

Method Detail

initContext

public void initContext(XPathContext execContext)

Initialize the context values for this expression after it is cloned.

Parameters:

execContext - The XPath runtime context for this transformation.

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. Afterdetach has been invoked, calls to nextNode orpreviousNode will raise the exception INVALID_STATE_ERR.

Specified by:

detach in interface NodeIterator

execute

public XObject execute(XPathContext xctxt)
                throws TransformerException

Execute this iterator, meaning create a clone that can store state, and initialize it for fast execution from the current runtime state. When this is called, no actual query from the current context node is performed.

Parameters:

xctxt - The XPath execution context.

Returns:

An XNodeSet reference that holds this iterator.

Throws:

TransformerException -

Overrides:

execute in class Expression

setShouldCacheNodes

public void setShouldCacheNodes(boolean b)

If setShouldCacheNodes(true) is called, then nodes will be cached. They are not cached by default.

Specified by:

setShouldCacheNodes in interface ContextNodeList

Parameters:

b - True if this iterator should cache nodes.

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.

size

public int size()

Get the length of the list.

Specified by:

size in interface ContextNodeList

Returns:

The length of this list, or zero is this is not a cached list.

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 the iteration has not yet begun.

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, 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.

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.

Specified by:

getWhatToShow in interface NodeIterator

Returns:

A bit set that tells what node types to show (NodeFilter.SHOW_ALL at the iterator level).

getFilter

public NodeFilter getFilter()

The filter used to screen nodes.

Specified by:

getFilter in interface NodeIterator

Returns:

null.

getRoot

public Node getRoot()

The root node of the Iterator, as specified when it was created.

Specified by:

getRoot in interface NodeIterator

Returns:

The context node of this iterator.

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.

addIterator

public void addIterator(LocPathIterator iter)

Add an iterator to the union list.

Parameters:

iter - non-null reference to a location path iterator.

cloneWithReset

public NodeIterator cloneWithReset()
                            throws java.lang.CloneNotSupportedException

Get a cloned Iterator that is reset to the beginning of the query.

Specified by:

cloneWithReset in interface ContextNodeList

Returns:

A cloned NodeIterator set of the start of the query.

Throws:

java.lang.CloneNotSupportedException -

clone

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

Get a cloned LocPathIterator that holds the same position as this iterator.

Specified by:

clone in interface ContextNodeList

Returns:

A clone of this iterator that holds the same node position.

Throws:

java.lang.CloneNotSupportedException -

reset

public void reset()

Reset the iterator.

Specified by:

reset in interface ContextNodeList

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.

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 - The index to run to, or -1 if the iterator should run to the end.

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:

A value greater than or equal to zero that indicates the next node position to fetch.

getCurrentNode

public Node getCurrentNode()

Return the last fetched node.

Specified by:

getCurrentNode in interface ContextNodeList

Returns:

The last fetched node, or null if the last fetch was null.

getCurrentContextNode

public Node getCurrentContextNode()

The node context from where the expression is being executed from (i.e. for current() support).

Returns:

The top-level node context of the entire expression.

getLast

public int getLast()

Get the index of the last node in the itteration.

Specified by:

getLast in interface ContextNodeList

setLast

public void setLast(int last)

Set the index of the last node in the itteration.

Specified by:

setLast in interface ContextNodeList