/*
 * Copyright (c) 2002-2009 "Neo Technology,"
 *     Network Engine for Objects in Lund AB [http://neotechnology.com]
 *
 * This file is part of Neo4j.
 * 
 * Neo4j is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 * 
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */
package org.neo4j.kernel.impl.traversal;

import java.util.Collection;

import org.neo4j.graphdb.Node;

/**
 * A utility class that represents an arbitrary traversal over a nodespace. A
 * Traverser is used as a tool for a Neo4j client programmer to easily traverse
 * the node space according a complex set of rules.
 * <P>
 * A Traverser is created by invoking any of the factory methods in
 * {@link InternalTraverserFactory}. Subsequent retrieval of the nodes from a Traverser
 * is simple: it can either be treated as an {@link java.util.Iterator} using
 * the standard <CODE>if ( i.hasNext() ) { i.next(); }</CODE> idiom or as a
 * Traverser with the type-safe {@link #nextNode} or the array-based
 * {@link #getAllNodes} operations.
 * <P>
 * A Traverser is generally not thread safe. If a client wishes to use it in a
 * concurrent environment, they are strongly adviced to synchronize externally.
 */
public interface InternalTraverser extends org.neo4j.graphdb.Traverser
{
    /**
     * Returns the next node in the traversal.
     * @throws java.util.NoSuchElementException
     *             if the traversal has no more nodes
     * @return the next node in the traversal
     * @see #nextNode
     */
    public Object next();

    /**
     * Returns <CODE>true</CODE> if the traversal has more nodes. In other
     * words, returns <CODE>true</CODE> if {@link #next} or {@link #nextNode}
     * would return a node rather than throwing an exception.
     * @return <CODE>true</CODE> if the traversal has more nodes
     */
    public boolean hasNext();

    /**
     * Unsupported, throws an {@link java.lang.UnsupportedOperationException}.
     * @throws java.lang.UnsupportedOperationException
     *             always when this operation is invoked
     */
    public void remove();

    /**
     * Returns the next node in the traversal. This operation is identical to
     * {@link #next} except that it's type safe.
     * @return the next node in the traversal
     * @throws java.util.NoSuchElementException
     *             if the traversal has no more nodes
     */
    public Node nextNode();

    /**
     * Returns all remaining nodes in the traversal as an array, <B>PLEASE NOTE</B>
     * that this operation can potentially be VERY CPU consuming and leave
     * little room for performance-boosters such as background streaming of
     * content from persistence and cache spooling. Only use this method if you
     * know that the traverser is well-behaving and won't run wild and try to
     * return the entire node space.
     * @return an array of all the nodes in this traversal
     */
    public Collection<Node> getAllNodes();

    /**
     * Returns a Traverser for all remaining nodes sorted as specified by 
     * <CODE>NodeSortInfo</CODE>.
     * <B>PLEASE NOTE</B> that this operation can potentially be VERY CPU
     * consuming and leave little room for performance-boosters such as
     * background streaming of content from persistence and cache spooling. Only
     * use this method if you know that the traverser is well-behaving and won't
     * run wild and try to return the entire node space.
     * 
     * @param nsi
     *            encapsulates how the nodes should be sorted
     * @return a sorted traverser for all remaining nodes
     */
    public InternalTraverser sort( NodeSortInfo<Node> nsi );
}