/**
   * Callers should not call next() after it returns END.
   *
   * <p><em>Use of an instance of this class as a {@link DTMAxisIterator} is <b>deprecated.</b></em>
   *
   * @deprecated
   */
  public int next() {
    if (_nodes == null) return DTMAxisIterator.END;

    return (_position < _nodes.cardinality())
        ? _dom.getNodeHandle(_nodes.at(_position++))
        : DTMAxisIterator.END;
  }
      /**
       * Advance to the next node represented by this {@link HeapNode}
       *
       * @return the next DTM node.
       */
      public int step() {
        if (_position < _nodes.cardinality()) {
          _node = _nodes.at(_position);
          _position++;
        } else {
          _node = DTMAxisIterator.END;
        }

        return _node;
      }
 public int getNode(int index) {
   if (index < _numCachedNodes) {
     return _nodes.at(index);
   } else if (!_isEnded) {
     int node = _source.next();
     if (node != END) {
       _nodes.add(node);
       _numCachedNodes++;
     } else {
       _isEnded = true;
     }
     return node;
   } else return END;
 }
  private int computePositionOfLast() {
    final int last = _nodes.cardinality();
    final int currNode = _currentNode;
    final AbstractTranslet translet = _translet;

    int lastPosition = _position;
    for (int index = _currentIndex; index < last; ) {
      final int position = _docOrder ? index + 1 : last - index;
      int nodeIndex = _nodes.at(index++); // note increment

      if (_filter.test(nodeIndex, position, last, currNode, translet, this)) {
        lastPosition++;
      }
    }
    return lastPosition;
  }
  public int next() {
    final int last = _nodes.cardinality();
    final int currentNode = _currentNode;
    final AbstractTranslet translet = _translet;

    for (int index = _currentIndex; index < last; ) {
      final int position = _docOrder ? index + 1 : last - index;
      final int node = _nodes.at(index++); // note increment

      if (_filter.test(node, position, last, currentNode, translet, this)) {
        _currentIndex = index;
        return returnNode(node);
      }
    }
    return END;
  }
  /**
   * Adds a node to the node list for a given value. Nodes will always be added in document order.
   */
  public void add(Object value, int node, int rootNode) {
    if (_currentDocumentNode != rootNode) {
      _currentDocumentNode = rootNode;
      _index = new Hashtable();
      _rootToIndexMap.put(new Integer(rootNode), _index);
    }

    IntegerArray nodes = (IntegerArray) _index.get(value);

    if (nodes == null) {
      nodes = new IntegerArray();
      _index.put(value, nodes);
      nodes.add(node);

      // Because nodes are added in document order,
      // duplicates can be eliminated easily at this stage.
    } else if (node != nodes.at(nodes.cardinality() - 1)) {
      nodes.add(node);
    }
  }
    /**
     * Get the next node in the iteration.
     *
     * @return The next node handle in the iteration, or END.
     */
    public int next() {
      int nodeHandle;

      // If at most one key value or at most one string argument to id
      // resulted in nodes being returned, use the IntegerArray
      // stored at _nodes directly.  This relies on the fact that the
      // IntegerArray never includes duplicate nodes and is always stored
      // in document order.
      if (_nodes != null) {
        if (_position < _nodes.cardinality()) {
          nodeHandle = returnNode(_nodes.at(_position));
        } else {
          nodeHandle = DTMAxisIterator.END;
        }
      } else {
        nodeHandle = super.next();
      }

      return nodeHandle;
    }
    /**
     * Return the node at the given position.
     *
     * @param position The position
     * @return The node at the given position.
     */
    public int getNodeByPosition(int position) {
      int node = DTMAxisIterator.END;

      // If nodes are stored in _nodes, take advantage of the fact that
      // there are no duplicates and they are stored in document order.
      // Otherwise, fall back to the base heap implementation to do a
      // good job with this.
      if (_nodes != null) {
        if (position > 0) {
          if (position <= _nodes.cardinality()) {
            _position = position;
            node = _nodes.at(position - 1);
          } else {
            _position = _nodes.cardinality();
          }
        }
      } else {
        node = super.getNodeByPosition(position);
      }

      return node;
    }