FileDocCategorySizeDatePackage
LocPathIterator.javaAPI DocJava SE 5 API28911Fri Aug 26 14:56:06 BST 2005com.sun.org.apache.xpath.internal.axes

LocPathIterator

public abstract class LocPathIterator extends PredicatedNodeTest implements PathComponent, Cloneable, DTMIterator, Serializable
This class extends NodeSetDTM, which implements NodeIterator, and fetches nodes one at a time in document order based on a XPath
xsl.usage
advanced

Fields Summary
protected boolean
m_allowDetach
Control over whether it is OK for detach to reset the iterator.
protected transient IteratorPool
m_clones
The pool for cloned iterators. Iterators need to be cloned because the hold running state, and thus the original iterator expression from the stylesheet pool can not be used.
protected transient DTM
m_cdtm
The dtm of the context node. Careful about using this... it may not be the dtm of the current node.
transient int
m_stackFrame
The stack frame index for this iterator.
private boolean
m_isTopLevel
Value determined at compile time, indicates that this is an iterator at the top level of the expression, rather than inside a predicate.
public transient int
m_lastFetched
The last node that was fetched, usually by nextNode.
protected transient int
m_context
The context node for this iterator, which doesn't change through the course of the iteration.
protected transient int
m_currentContextNode
The node context from where the expression is being executed from (i.e. for current() support). Different from m_context in that this is the context for the entire expression, rather than the context for the subexpression.
protected transient int
m_pos
The current position of the context node.
protected transient int
m_length
private PrefixResolver
m_prefixResolver
Fast access to the current prefix resolver. It isn't really clear that this is needed.
protected transient XPathContext
m_execContext
The XPathContext reference, needed for execution of many operations.
Constructors Summary
protected LocPathIterator()
Create a LocPathIterator object.

param
nscontext The namespace context for this iterator, should be OK if null.

  
protected LocPathIterator(PrefixResolver nscontext)
Create a LocPathIterator object.

param
nscontext The namespace context for this iterator, should be OK if null.


    setLocPathIterator(this);
    m_prefixResolver = nscontext;
  
protected LocPathIterator(Compiler compiler, int opPos, int analysis)
Create a LocPathIterator object, including creation of step walkers from the opcode list, and call back into the Compiler to create predicate expressions.

param
compiler The Compiler which is creating this expression.
param
opPos The position of this iterator in the opcode list from the compiler.
throws
javax.xml.transform.TransformerException

    this(compiler, opPos, analysis, true);
  
protected LocPathIterator(Compiler compiler, int opPos, int analysis, boolean shouldLoadWalkers)
Create a LocPathIterator object, including creation of step walkers from the opcode list, and call back into the Compiler to create predicate expressions.

param
compiler The Compiler which is creating this expression.
param
opPos The position of this iterator in the opcode list from the compiler.
param
shouldLoadWalkers True if walkers should be loaded, or false if this is a derived iterator and it doesn't wish to load child walkers.
throws
javax.xml.transform.TransformerException

    setLocPathIterator(this);
  
Methods Summary
public voidallowDetachToRelease(boolean allowRelease)
Specify if it's OK for detach to release the iterator for reuse.

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

  
                                  
     
  
    m_allowDetach = allowRelease;
  
public com.sun.org.apache.xml.internal.dtm.DTMIteratorasIterator(com.sun.org.apache.xpath.internal.XPathContext xctxt, int contextNode)
Given an select expression and a context, evaluate the XPath and return the resulting iterator.

param
xctxt The execution context.
param
contextNode The node that "." expresses.
param
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.
throws
javax.xml.transform.TransformerException
xsl.usage
experimental

    XNodeSet iter = new XNodeSet((LocPathIterator)m_clones.getInstance());

    iter.setRoot(contextNode, xctxt);

    return iter;
  
public intasNode(com.sun.org.apache.xpath.internal.XPathContext xctxt)
Return the first node out of the nodeset, if this expression is a nodeset expression. This is the default implementation for nodesets. Derived classes should try and override this and return a value without having to do a clone operation.

param
xctxt The XPath runtime context.
return
the first node out of the nodeset, or DTM.NULL.

    DTMIterator iter = (DTMIterator)m_clones.getInstance();
    
    int current = xctxt.getCurrentNode();
    
    iter.setRoot(current, xctxt);

    int next = iter.nextNode();
    // m_clones.freeInstance(iter);
    iter.detach();
    return next;
  
public booleanbool(com.sun.org.apache.xpath.internal.XPathContext xctxt)
Evaluate this operation directly to a boolean.

param
xctxt The runtime execution context.
return
The result of the operation as a boolean.
throws
javax.xml.transform.TransformerException

    return (asNode(xctxt) != DTM.NULL);
  
public voidcallVisitors(com.sun.org.apache.xpath.internal.ExpressionOwner owner, com.sun.org.apache.xpath.internal.XPathVisitor visitor)

see
com.sun.org.apache.xpath.internal.XPathVisitable#callVisitors(ExpressionOwner, XPathVisitor)

  	 	if(visitor.visitLocationPath(owner, this))
  	 	{
  	 		visitor.visitStep(owner, this);
  	 		callPredicateVisitors(visitor);
  	 	}
  
public com.sun.org.apache.xml.internal.dtm.DTMIteratorcloneWithReset()
Get a cloned Iterator that is reset to the beginning of the query.

return
A cloned NodeIterator set of the start of the query.
throws
CloneNotSupportedException

    LocPathIterator clone;
//    clone = (LocPathIterator) clone();
    clone = (LocPathIterator)m_clones.getInstanceOrThrow();
    clone.m_execContext = m_execContext;
    clone.m_cdtm = m_cdtm;
    
    clone.m_context = m_context;
    clone.m_currentContextNode = m_currentContextNode;
    clone.m_stackFrame = m_stackFrame;

    // clone.reset();

    return clone;
  
public voiddetach()
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.

    
    if(m_allowDetach)
    {
      // sb: allow reusing of cached nodes when possible?
      // m_cachedNodes = null;
      m_execContext = null;
      // m_prefixResolver = null;  sb: Why would this ever want to be null?
      m_cdtm = null;
      m_length = -1;
      m_pos = 0;
      m_lastFetched = DTM.NULL;
      m_context = DTM.NULL;
      m_currentContextNode = DTM.NULL;
      
      m_clones.freeInstance(this);
    }
  
public com.sun.org.apache.xpath.internal.objects.XObjectexecute(com.sun.org.apache.xpath.internal.XPathContext xctxt)
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.

param
xctxt The XPath execution context.
return
An XNodeSet reference that holds this iterator.
throws
javax.xml.transform.TransformerException


    XNodeSet iter = new XNodeSet((LocPathIterator)m_clones.getInstance());

    iter.setRoot(xctxt.getCurrentNode(), xctxt);

    return iter;
  
public voidexecuteCharsToContentHandler(com.sun.org.apache.xpath.internal.XPathContext xctxt, org.xml.sax.ContentHandler handler)
Execute an expression in the XPath runtime context, and return the result of the expression.

param
xctxt The XPath runtime context.
param
handler The target content handler.
return
The result of the expression in the form of a XObject.
throws
javax.xml.transform.TransformerException if a runtime exception occurs.
throws
org.xml.sax.SAXException

    LocPathIterator clone = (LocPathIterator)m_clones.getInstance();

    int current = xctxt.getCurrentNode();
    clone.setRoot(current, xctxt);
    
    int node = clone.nextNode();
    DTM dtm = clone.getDTM(node);
    clone.detach();
	
    if(node != DTM.NULL)
    {
      dtm.dispatchCharactersEvents(node, handler, false);
    }
  
public intgetAnalysisBits()
Get the analysis bits for this walker, as defined in the WalkerFactory.

return
One of WalkerFactory#BIT_DESCENDANT, etc.

  	int axis = getAxis();
  	int bit = WalkerFactory.getAnalysisBitFromAxes(axis);
  	return bit;
  
public intgetAxis()
Returns the axis being iterated, if it is known.

return
Axis.CHILD, etc., or -1 if the axis is not known or is of multiple types.

    return -1;
  
public final intgetContext()
The node context for the iterator.

return
The node context, same as getRoot().

    return m_context;
  
public final intgetCurrentContextNode()
The node context from where the expression is being executed from (i.e. for current() support).

return
The top-level node context of the entire expression.

    return m_currentContextNode;
  
public intgetCurrentNode()
Return the last fetched node. Needed to support the UnionPathIterator.

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

    return m_lastFetched;
  
public final intgetCurrentPos()
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.

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

    return m_pos;
  
public com.sun.org.apache.xml.internal.dtm.DTMgetDTM(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.

param
nodeHandle the nodeHandle.
return
a non-null DTM reference.

    // %OPT%
    return m_execContext.getDTM(nodeHandle);
  
public com.sun.org.apache.xml.internal.dtm.DTMManagergetDTMManager()
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.

return
a non-null DTMManager reference.

    return m_execContext.getDTMManager();
  
public booleangetExpandEntityReferences()
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.

return
Always true, since entity reference nodes are not visible in the XPath model.

    return true;
  
public com.sun.org.apache.xml.internal.dtm.DTMFiltergetFilter()
The filter used to screen nodes. Not used at this time, this is here only to fullfill the DOM NodeIterator interface.

return
Always null.
see
org.w3c.dom.traversal.NodeIterator

    return null;
  
public final booleangetFoundLast()
Tells if we've found the last node yet.

return
true if the last nextNode returned null.

    return m_foundLast;
  
public booleangetIsTopLevel()
Get if this is an iterator at the upper level of the XPath.

return
true if this location path is at the top level of the expression.
xsl.usage
advanced

    return m_isTopLevel;
  
public intgetLastPos(com.sun.org.apache.xpath.internal.XPathContext xctxt)

see
PredicatedNodeTest#getLastPos(XPathContext)

    return getLength();
  
public intgetLength()
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.

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

      
    // Tell if this is being called from within a predicate.
  	boolean isPredicateTest = (this == m_execContext.getSubContextList());

    // And get how many total predicates are part of this step.
  	int predCount = getPredicateCount();
  	
    // If we have already calculated the length, and the current predicate 
    // is the first predicate, then return the length.  We don't cache 
    // the anything but the length of the list to the first predicate.
    if (-1 != m_length && isPredicateTest && m_predicateIndex < 1)
  		return m_length;
  	
    // I'm a bit worried about this one, since it doesn't have the 
    // checks found above.  I suspect it's fine.  -sb
    if (m_foundLast)
  		return m_pos;
  		
    // Create a clone, and count from the current position to the end 
    // of the list, not taking into account the current predicate and 
    // predicates after the current one.
    int pos = (m_predicateIndex >= 0) ? getProximityPosition() : m_pos;
              
    LocPathIterator clone;

    try
    {
      clone = (LocPathIterator) clone();        
    }
    catch (CloneNotSupportedException cnse)
    {
      return -1;
    }

    // We want to clip off the last predicate, but only if we are a sub 
    // context node list, NOT if we are a context list.  See pos68 test, 
    // also test against bug4638.
    if (predCount > 0 && isPredicateTest)
    {
      // Don't call setPredicateCount, because it clones and is slower.
      clone.m_predCount = m_predicateIndex;
      // The line above used to be:
      // clone.m_predCount = predCount - 1;
      // ...which looks like a dumb bug to me. -sb
    }

    int next;

    while (DTM.NULL != (next = clone.nextNode()))
    {
      pos++;
    }
    
    if (isPredicateTest && m_predicateIndex < 1)
      m_length = pos;
    
    return pos;
  
public final com.sun.org.apache.xml.internal.utils.PrefixResolvergetPrefixResolver()
Return the saved reference to the prefix resolver that was in effect when this iterator was created.

return
The prefix resolver or this iterator, which may be null.

  	if(null == m_prefixResolver)
  	{
    	m_prefixResolver = (PrefixResolver)getExpressionOwner();
  	}

    return m_prefixResolver;
  
public intgetRoot()
The root node of the Iterator, as specified when it was created.

return
The "root" of this iterator, which, in XPath terms, is the node context for this iterator.

    return m_context;
  
public intgetWhatToShow()
This attribute determines which node types are presented via the iterator. The available set of constants is defined in the NodeFilter interface.

This is somewhat useless at this time, since it doesn't really return information that tells what this iterator will show. It is here only to fullfill the DOM NodeIterator interface.

return
For now, always NodeFilter.SHOW_ALL & ~NodeFilter.SHOW_ENTITY_REFERENCE.
see
org.w3c.dom.traversal.NodeIterator


    // TODO: ??
    return DTMFilter.SHOW_ALL & ~DTMFilter.SHOW_ENTITY_REFERENCE;
  
public final com.sun.org.apache.xpath.internal.XPathContextgetXPathContext()
The XPath execution context we are operating on.

return
XPath execution context this iterator is operating on, or null if setRoot has not been called.

    return m_execContext;
  
public voidincrementCurrentPos()
Increment the current position in the node set.

  	m_pos++;
  
public booleanisDocOrdered()
Returns true if all the nodes in the iteration well be returned in document order.

return
true as a default.

  
                           
    
  
    return true;
  
public booleanisFresh()
Tells if this NodeSetDTM is "fresh", in other words, if the first nextNode() that is called will return the first node in the set.

return
true of nextNode has not been called.

    return (m_pos == 0);
  
public booleanisMutable()
Tells if this iterator can have nodes added to it or set via the setItem(int node, int index) method.

return
True if the nodelist can be mutated.

    return false;
  
public booleanisNodesetExpr()
Tell if the expression is a nodeset expression.

return
true if the expression can be represented as a nodeset.

    return true;
  
public intitem(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 .

param
index Index into the collection.
return
The node at the index th position in the NodeList , or null if that is not a valid index.

	assertion(false, "item(int index) not supported by this iterator!");
	return 0;
  
public abstract intnextNode()
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.

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

public intpreviousNode()
Returns the previous node in the set and moves the position of the iterator backwards in the set.

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

    throw new RuntimeException(
      XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESETDTM_CANNOT_ITERATE, null)); //"This NodeSetDTM can not iterate to a previous node!");
  
private voidreadObject(java.io.ObjectInputStream stream)
Read the object from a serialization stream.

param
stream Input stream to read from
throws
java.io.IOException
throws
javax.xml.transform.TransformerException

    try
    {
      stream.defaultReadObject();
      m_clones =  new IteratorPool(this);
    }
    catch (ClassNotFoundException cnfe)
    {
      throw new javax.xml.transform.TransformerException(cnfe);
    }
  
public voidreset()
Reset the iterator.

  	assertion(false, "This iterator can not reset!");
  
protected intreturnNextNode(int nextNode)
Bottleneck the return of a next node, to make returns easier from nextNode().

param
nextNode The next node found, may be null.
return
The same node that was passed as an argument.


    if (DTM.NULL != nextNode)
    {
      m_pos++;
    }

    m_lastFetched = nextNode;

    if (DTM.NULL == nextNode)
      m_foundLast = true;

    return nextNode;
  
public voidrunTo(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.

param
index The index to run to, or -1 if the iterator should run to the end.


    if (m_foundLast || ((index >= 0) && (index <= getCurrentPos())))
      return;

    int n;

    if (-1 == index)
    {
      while (DTM.NULL != (n = nextNode()));
    }
    else
    {
      while (DTM.NULL != (n = nextNode()))
      {
        if (getCurrentPos() >= index)
          break;
      }
    }
  
public final voidsetCurrentContextNode(int n)
Set the current context node for this iterator.

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

    m_currentContextNode = n;
  
public voidsetCurrentPos(int i)
Set the current position in the node set.

param
i Must be a valid index greater than or equal to zero and less than m_cachedNodes.size().

  	assertion(false, "setCurrentPos not supported by this iterator!");
  
public voidsetEnvironment(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.

param
environment The environment object.

    // no-op for now.
  
public voidsetIsTopLevel(boolean b)
Set if this is an iterator at the upper level of the XPath.

param
b true if this location path is at the top level of the expression.
xsl.usage
advanced

    m_isTopLevel = b;
  
public voidsetItem(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.

param
node Node to set
param
index Index of where to set the node

	assertion(false, "setItem not supported by this iterator!");
  
protected voidsetNextPosition(int next)
Set the next position index of this iterator.

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

    assertion(false, "setNextPosition not supported in this iterator!");
  
public voidsetRoot(int context, java.lang.Object environment)
Initialize the context values for this expression after it is cloned.

param
execContext The XPath runtime context for this transformation.


    m_context = context;
    
    XPathContext xctxt = (XPathContext)environment;
    m_execContext = xctxt;
    m_cdtm = xctxt.getDTM(context);
    
    m_currentContextNode = context; // only if top level?
    
    // Yech, shouldn't have to do this.  -sb
    if(null == m_prefixResolver)
    	m_prefixResolver = xctxt.getNamespaceContext();
        
    m_lastFetched = DTM.NULL;
    m_foundLast = false;
    m_pos = 0;
    m_length = -1;

    if (m_isTopLevel)
      this.m_stackFrame = xctxt.getVarStack().getStackFrame();
      
    // reset();
  
public voidsetShouldCacheNodes(boolean b)
If setShouldCacheNodes(true) is called, then nodes will be cached. They are not cached by default.

param
b True if this iterator should cache nodes.


    assertion(false, "setShouldCacheNodes not supported by this iterater!");
  
public intsize()
Get the length of the cached nodes.

Note: for the moment at least, this only returns the size of the nodes that have been fetched to date, it doesn't attempt to run to the end to make sure we have found everything. This should be reviewed.

return
The size of the current cache list.

	assertion(false, "size() not supported by this iterator!");
	return 0;