/*

 * reserved comment block

 * DO NOT REMOVE OR ALTER!

 */

/*

 * Copyright 1999-2004 The Apache Software Foundation.

 *

 * Licensed under the Apache License, Version 2.0 (the "License");

 * you may not use this file except in compliance with the License.

 * You may obtain a copy of the License at

 *

 *     http://www.apache.org/licenses/LICENSE-2.0

 *

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

/*

 * $Id: NodeSet.java,v 1.2.4.1 2005/09/10 17:39:49 jeffsuttor Exp $

 */

package com.sun.org.apache.xpath.internal;

import com.sun.org.apache.xalan.internal.res.XSLMessages;

import com.sun.org.apache.xml.internal.utils.DOM2Helper;

import com.sun.org.apache.xpath.internal.axes.ContextNodeList;

import com.sun.org.apache.xpath.internal.res.XPATHErrorResources;

import org.w3c.dom.DOMException;

import org.w3c.dom.Node;

import org.w3c.dom.NodeList;

import org.w3c.dom.traversal.NodeFilter;

import org.w3c.dom.traversal.NodeIterator;

/**

 * <p>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. </p>

 *

 * <p>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.</p>

 *

 * <p>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.</p>

 * @xsl.usage advanced

 */

public class NodeSet

        implements NodeList, NodeIterator, Cloneable, ContextNodeList

{

  /**

   * Create an empty nodelist.

   */

  public NodeSet()

  {

    m_blocksize = 32;

    m_mapSize = 0;

  }

  /**

   * Create an empty, using the given block size.

   *

   * @param blocksize Size of blocks to allocate

   */

  public NodeSet(int blocksize)

  {

    m_blocksize = blocksize;

    m_mapSize = 0;

  }

  /**

   * Create a NodeSet, and copy the members of the

   * given nodelist into it.

   *

   * @param nodelist List of Nodes to be made members of the new set.

   */

  public NodeSet(NodeList nodelist)

  {

    this(32);

    addNodes(nodelist);

  }

  /**

   * Create a NodeSet, and copy the members of the

   * given NodeSet into it.

   *

   * @param nodelist Set of Nodes to be made members of the new set.

   */

  public NodeSet(NodeSet nodelist)

  {

    this(32);

    addNodes((NodeIterator) nodelist);

  }

  /**

   * Create a NodeSet, and copy the members of the

   * given NodeIterator into it.

   *

   * @param ni Iterator which yields Nodes to be made members of the new set.

   */

  public NodeSet(NodeIterator ni)

  {

    this(32);

    addNodes(ni);

  }

  /**

   * Create a NodeSet which contains the given Node.

   *

   * @param node Single node to be added to the new set.

   */

  public NodeSet(Node node)

  {

    this(32);

    addNode(node);

  }

  /**

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

   * For non-Iterator NodeSets, this will be null.

   */

  public Node getRoot()

  {

    return null;

  }

  /**

   * Get a cloned Iterator, and reset its state to the beginning of the

   * iteration.

   *

   * @return 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.

   */

  public NodeIterator cloneWithReset() throws CloneNotSupportedException

  {

    NodeSet clone = (NodeSet) clone();

    clone.reset();

    return clone;

  }

  /**

   * Reset the iterator. May have no effect on non-iterator Nodesets.

   */

  public void reset()

  {

    m_next = 0;

  }

  /**

   *  This attribute determines which node types are presented via the

   * iterator. The available set of constants is defined in the

   * <code>NodeFilter</code> interface. For NodeSets, the mask has been

   * hardcoded to show all nodes except EntityReference nodes, which have

   * no equivalent in the XPath data model.

   *

   * @return integer used as a bit-array, containing flags defined in

   * the DOM's NodeFilter class. The value will be

   * <code>SHOW_ALL & ~SHOW_ENTITY_REFERENCE</code>, meaning that

   * only entity references are suppressed.

   */

  public int getWhatToShow()

  {

    return NodeFilter.SHOW_ALL & ~NodeFilter.SHOW_ENTITY_REFERENCE;

  }

  /**

   * The filter object used to screen nodes. Filters are applied to

   * further reduce (and restructure) the NodeIterator's view of the

   * document. In our case, we will be using hardcoded filters built

   * into our iterators... but getFilter() is part of the DOM's

   * NodeIterator interface, so we have to support it.

   *

   * @return 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.

   */

  public NodeFilter getFilter()

  {

    return null;

  }

  /**

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

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

   */

  public boolean getExpandEntityReferences()

  {

    return true;

  }

  /**

   *  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 <code>Node</code> in the set being iterated over, or

   *   <code>null</code> if there are no more members in that set.

   * @throws DOMException

   *    INVALID_STATE_ERR: Raised if this method is called after the

   *   <code>detach</code> method was invoked.

   */

  public Node nextNode() throws DOMException

  {

    if ((m_next) < this.size())

    {

      Node next = this.elementAt(m_next);

      m_next++;

      return next;

    }

    else

      return null;

  }

  /**

   *  Returns the previous node in the set and moves the position of the

   * iterator backwards in the set.

   * @return  The previous <code>Node</code> in the set being iterated over,

   *   or<code>null</code> if there are no more members in that set.

   * @throws DOMException

   *    INVALID_STATE_ERR: Raised if this method is called after the

   *   <code>detach</code> method was invoked.

   * @throws RuntimeException thrown if this NodeSet is not of

   * a cached type, and hence doesn't know what the previous node was.

   */

  public Node previousNode() throws DOMException

  {

    if (!m_cacheNodes)

      throw new RuntimeException(

        XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_CANNOT_ITERATE, null)); //"This NodeSet can not iterate to a previous node!");

    if ((m_next - 1) > 0)

    {

      m_next--;

      return this.elementAt(m_next);

    }

    else

      return null;

  }

  /**

   * Detaches the iterator from the set which it iterated over, releasing

   * any computational resources and placing the iterator in the INVALID

   * state. After<code>detach</code> has been invoked, calls to

   * <code>nextNode</code> or<code>previousNode</code> will raise the

   * exception INVALID_STATE_ERR.

   * <p>

   * This operation is a no-op in NodeSet, and will not cause

   * INVALID_STATE_ERR to be raised by later operations.

   * </p>

   */

  public void detach(){}

  /**

   * Tells if this NodeSet is "fresh", in other words, if

   * the first nextNode() that is called will return the

   * first node in the set.

   *

   * @return true if nextNode() would return the first node in the set,

   * false if it would return a later one.

   */

  public boolean isFresh()

  {

    return (m_next == 0);

  }

  /**

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

   *

   * @param 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.

   */

  public void runTo(int index)

  {

    if (!m_cacheNodes)

      throw new RuntimeException(

        XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_CANNOT_INDEX, null)); //"This NodeSet can not do indexing or counting functions!");

    if ((index >= 0) && (m_next < m_firstFree))

      m_next = index;

    else

      m_next = m_firstFree - 1;

  }

  /**

   * Returns the <code>index</code>th item in the collection. If

   * <code>index</code> is greater than or equal to the number of nodes in

   * the list, this returns <code>null</code>.

   *

   * TODO: What happens if index is out of range?

   *

   * @param index Index into the collection.

   * @return The node at the <code>index</code>th position in the

   *   <code>NodeList</code>, or <code>null</code> if that is not a valid

   *   index.

   */

  public Node item(int index)

  {

    runTo(index);

    return (Node) this.elementAt(index);

  }

  /**

   * The number of nodes in the list. The range of valid child node indices is

   * 0 to <code>length-1</code> inclusive. Note that this operation requires

   * finding all the matching nodes, which may defeat attempts to defer

   * that work.

   *

   * @return integer indicating how many nodes are represented by this list.

   */

  public int getLength()

  {

    runTo(-1);

    return this.size();

  }

  /**

   * Add a node to the NodeSet. Not all types of NodeSets support this

   * operation

   *

   * @param n Node to be added

   * @throws RuntimeException thrown if this NodeSet is not of

   * a mutable type.

   */

  public void addNode(Node n)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    this.addElement(n);

  }

  /**

   * Insert a node at a given position.

   *

   * @param n Node to be added

   * @param 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.

   */

  public void insertNode(Node n, int pos)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    insertElementAt(n, pos);

  }

  /**

   * Remove a node.

   *

   * @param n Node to be added

   * @throws RuntimeException thrown if this NodeSet is not of

   * a mutable type.

   */

  public void removeNode(Node n)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    this.removeElement(n);

  }

  /**

   * Copy NodeList members into this nodelist, adding in

   * document order.  If a node is null, don't add it.

   *

   * @param nodelist List of nodes which should now be referenced by

   * this NodeSet.

   * @throws RuntimeException thrown if this NodeSet is not of

   * a mutable type.

   */

  public void addNodes(NodeList nodelist)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    if (null != nodelist)  // defensive to fix a bug that Sanjiva reported.

    {

      int nChildren = nodelist.getLength();

      for (int i = 0; i < nChildren; i++)

      {

        Node obj = nodelist.item(i);

        if (null != obj)

        {

          addElement(obj);

        }

      }

    }

    // checkDups();

  }

  /**

   * <p>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. </p>

   *

   * <p> 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.)</p>

   *

   * @param ns NodeSet whose members should be merged into this NodeSet.

   * @throws RuntimeException thrown if this NodeSet is not of

   * a mutable type.

   */

  public void addNodes(NodeSet ns)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    addNodes((NodeIterator) ns);

  }

  /**

   * Copy NodeList members into this nodelist, adding in

   * document order.  Null references are not added.

   *

   * @param iterator NodeIterator which yields the nodes to be added.

   * @throws RuntimeException thrown if this NodeSet is not of

   * a mutable type.

   */

  public void addNodes(NodeIterator iterator)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    if (null != iterator)  // defensive to fix a bug that Sanjiva reported.

    {

      Node obj;

      while (null != (obj = iterator.nextNode()))

      {

        addElement(obj);

      }

    }

    // checkDups();

  }

  /**

   * Copy NodeList members into this nodelist, adding in

   * document order.  If a node is null, don't add it.

   *

   * @param nodelist List of nodes to be added

   * @param support The XPath runtime context.

   * @throws RuntimeException thrown if this NodeSet is not of

   * a mutable type.

   */

  public void addNodesInDocOrder(NodeList nodelist, XPathContext support)

  {

    if (!m_mutable)

      throw new RuntimeException(XSLMessages.createXPATHMessage(XPATHErrorResources.ER_NODESET_NOT_MUTABLE, null)); //"This NodeSet is not mutable!");

    int nChildren = nodelist.getLength();

    for (int i = 0; i < nChildren; i++)

    {

      Node node = nodelist.item(i);