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, DTMIterator, java.io.Serializable

**For advanced use only** This class extends NodeSetDTM, which implements DTMIterator, 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.
void	allowDetachToRelease(boolean allowRelease) Specify if it's OK for detach to release the iterator for reuse.
DTMIterator	asIterator(XPathContext xctxt, int contextNode) **Experimental** Given an select expression and a context, evaluate the XPath and return the resulting iterator.
java.lang.Object	clone() Get a cloned LocPathIterator that holds the same position as this iterator.
DTMIterator	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.
void	fixupVariables(java.util.Vector vars, int globalsSize) This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.
int	getAxis() Returns the axis being iterated, if it is known.
int	getCurrentContextNode() The node context from where the expression is being executed from (i.e.
int	getCurrentNode() Return the last fetched node.
int	getCurrentPos() Get the current position, 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.
DTMFilter	getFilter() The filter used to screen nodes.
int	getLast() Get the index of the last node in the itteration.
int	getLastPos(XPathContext xctxt) Get the index of the last node that can be itterated to.
int	getLength() The number of nodes in the list.
int	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.
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 index th 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 iterator backwards in the set.
void	reset() Reset the iterator.
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	setEnvironment(java.lang.Object environment) Set the environment in which this iterator operates, which should provide: a node (the context node...
void	setItem(int node, int index) Sets the node at the specified index of this vector to be the specified node.
void	setLast(int last) Set the index of the last node in the itteration.
void	setRoot(int n) Set the current context node for this iterator.
void	setRoot(int context, java.lang.Object environment) Initialize the context values for this expression after it is cloned.
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

asNode, assertion, bool, canTraverseOutsideSubtree, error, execute, execute, executeCharsToContentHandler, isNodesetExpr, isStableNumber, num, setSourceLocator, warn, xstr

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 javax.xml.transform.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:

javax.xml.transform.TransformerException -

Method Detail

setRoot

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

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

Specified by:

setRoot in interface DTMIterator

Parameters:

execContext - The XPath runtime context for this transformation.

allowDetachToRelease

public void allowDetachToRelease(boolean allowRelease)

Specify if it's OK for detach to release the iterator for reuse.

Specified by:

allowDetachToRelease in interface DTMIterator

Parameters:

allowRelease - true if it is OK for detach to release this iterator for pooling.

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 DTMIterator

execute

public XObject execute(XPathContext xctxt)
                throws javax.xml.transform.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:

javax.xml.transform.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 DTMIterator

Parameters:

b - True if this iterator should cache nodes.

isMutable

public boolean isMutable()

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.

setCurrentPos

public void setCurrentPos(int i)

Set the current position in the node set.

Specified by:

setCurrentPos in interface DTMIterator

Parameters:

i - Must be a valid index.

size

public int size()

Get the length of the list.

Returns:

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

isFresh

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.

Specified by:

isFresh in interface DTMIterator

Returns:

True if the iteration has not yet begun.

previousNode

public int previousNode()

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

Specified by:

previousNode in interface DTMIterator

Returns:

The previous Node in the set being iterated over, ornull if there are no more members in that set.

getWhatToShow

public int getWhatToShow()

This attribute determines which node types are presented via the iterator. The available set of constants is defined in the DTMFilter interface.

Specified by:

getWhatToShow in interface DTMIterator

Returns:

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

getFilter

public DTMFilter getFilter()

The filter used to screen nodes.

Returns:

null.

getRoot

public int getRoot()

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

Specified by:

getRoot in interface DTMIterator

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 DTMIterator

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 DTMIterator cloneWithReset()
                           throws java.lang.CloneNotSupportedException

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

Specified by:

cloneWithReset in interface DTMIterator

Returns:

A cloned DTMIterator 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 DTMIterator

Returns:

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

Throws:

java.lang.CloneNotSupportedException -

asIterator

public DTMIterator asIterator(XPathContext xctxt,
                              int contextNode)
                       throws javax.xml.transform.TransformerException

**Experimental** Given an select expression and a context, evaluate the XPath and return the resulting iterator.

Parameters:

xctxt - The execution context.

contextNode - The node that "." expresses.

namespaceContext - The context in which namespaces in the XPath are supposed to be expanded.

Throws:

TransformerException - thrown if the active ProblemListener decides the error condition is severe enough to halt processing.

javax.xml.transform.TransformerException -

Overrides:

asIterator in class Expression

reset

public void reset()

Reset the iterator.

Specified by:

reset in interface DTMIterator

nextNode

public int nextNode()

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

Specified by:

nextNode in interface DTMIterator

Returns:

The next Node in the set being iterated over, or null if there are no more members in that set.

runTo

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.

Specified by:

runTo in interface DTMIterator

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 DTMIterator

Returns:

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

getLength

public int getLength()

The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.

Specified by:

getLength in interface DTMIterator

Returns:

The number of nodes in the list, always greater or equal to zero.

getLastPos

public int getLastPos(XPathContext xctxt)

Get the index of the last node that can be itterated to. This probably will need to be overridded by derived classes.

Parameters:

xctxt - XPath runtime context.

Returns:

the index of the last node that can be itterated to.

item

public int 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 .

Specified by:

item in interface DTMIterator

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.

setItem

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.

Specified by:

setItem in interface DTMIterator

Parameters:

node - Node to set

index - Index of where to set the node

setRoot

public final void setRoot(int n)

Set the current context node for this iterator.

Parameters:

n - Must be a non-null reference to the node context.

setEnvironment

public void setEnvironment(java.lang.Object environment)

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

Parameters:

environment - The environment object.

getDTMManager

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.

Specified by:

getDTMManager in interface DTMIterator

Returns:

a non-null DTMManager reference.

getCurrentNode

public int getCurrentNode()

Return the last fetched node.

Specified by:

getCurrentNode in interface DTMIterator

Returns:

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

fixupVariables

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

This function is used to fixup variables from QNames to stack frame indexes at stylesheet build time.

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

Overrides:

fixupVariables in class Expression

getDTM

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.

Specified by:

getDTM in interface DTMIterator

Parameters:

nodeHandle - the nodeHandle.

Returns:

a non-null DTM reference.

getCurrentContextNode

public int 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.

setLast

public void setLast(int last)

Set the index of the last node in the itteration.

isDocOrdered

public boolean isDocOrdered()

Returns true if all the nodes in the iteration well be returned in document order.

Specified by:

isDocOrdered in interface DTMIterator

Returns:

true as a default.

getAxis

public int getAxis()

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.