/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.
 */
package org.apache.directory.server.core.cursor;

import java.io.IOException;


/**
 * A simple cursor concept for bidirectionally enumerating over elements.
 * Cursors unlike iterators request to advance to an element by calling next()
 * or previous() which returns true or false if the request succeeds.  Other
 * operations for relative and absolute advances are provided.  If the cursor
 * does not advance, then the Cursor is either positioned before the first
 * element or after the last element in which case the user of the Cursor must
 * stop advancing in the respective direction.  If an advance succeeds a get()
 * operation retreives the current object at the Cursors position.
 *
 * Although this interface presumes Cursors can advance bidirectionally, one
 * or more either direction may not be supported.  In this case
 * implementations should throw UnsupportedOperationExceptions.
 *
 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
 * @version $Rev$, $Date$
 */
public interface Cursor<E>
{
    /**
     * Positions this Curser before the first element.
     *
     * @throws IOException if there are problems positioning this cursor or if
     * this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    void beforeFirst() throws IOException;


    /**
     * Positions this Curser after the last element.
     *
     * @throws IOException if there are problems positioning this Cursor or if
     * this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    void afterLast() throws IOException;


    /**
     * Positions this Curser at the nth element.  Zero based indexing is used.
     *
     * If the specified position is past the first or last element, the Cursor
     * is positioned before the first or after the last element respectively.
     *
     * @param absolutePosition the absolute position to move this Cursor to
     * @return true if the position has been successfully changed to the
     * element at the specified position, false otherwise
     * @throws IOException if there are problems positioning this Cursor or if
     * this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean absolute( int absolutePosition ) throws IOException;


    /**
     * Positions this Curser n places relative to the present position.  Zero
     * based indexing is used and negative index values may be provided for
     * representing the direction.
     *
     * If the specified position is past the first or last element, the Cursor
     * is positioned before the first or after the last element respectively.
     *
     * @param relativePosition the relative position to move this Cursor to
     * @return true if the position has been successfully changed to the
     * element relative to the current position, false otherwise
     * @throws IOException if there are problems positioning this Cursor or if
     * this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean relative( int relativePosition ) throws IOException;


    /**
     * Positions this Curser at the first element.
     *
     * @return true if the position has been successfully changed to the first
     * element, false otherwise
     * @throws IOException if there are problems positioning this Cursor or if
     * this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean first() throws IOException;


    /**
     * Positions this Curser at the last element.
     *
     * @return true if the position has been successfully changed to the last
     * element, false otherwise
     * @throws IOException if there are problems positioning this Cursor or if
     * this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean last() throws IOException;


    /**
     * Checks if this Curser is positioned at the first element.
     *
     * @return true if the current position is at the first element, false
     * otherwise
     * @throws IOException if there are problems determining this Cursor's
     * position, or if this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean isFirst() throws IOException;


    /**
     * Checks if this Curser is positioned at the last element.
     *
     * @return true if the current position is at the last element, false
     * otherwise
     * @throws IOException if there are problems determining this Cursor's
     * position, or if this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean isLast() throws IOException;


    /**
     * Checks if this Curser is positioned after the last element.
     *
     * @return true if the current position is after the last element, false
     * otherwise
     * @throws IOException if there are problems determining this Cursor's
     * position, or if this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean isAfterLast() throws IOException;


    /**
     * Checks if this Curser is positioned before the first element.
     *
     * @return true if the current position is before the first element, false
     * otherwise
     * @throws IOException if there are problems determining this Cursor's
     * position, or if this Cursor is closed
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean isBeforeFirst() throws IOException;


    /**
     * Checks if this Curser is closed.  Calls to this operation should not
     * fail with exceptions if and only if the cursor is in the closed state.
     *
     * @return true if this Cursor is closed, false otherwise
     * @throws IOException if there are problems determining the cursor's closed state
     * @throws UnsupportedOperationException if this operation is not supported
     */
    boolean isClosed() throws IOException;


    /**
     * Advances this Cursor to the previous position.
     *
     * @return true if the advance succeeded, false otherwise
     * @throws IOException if there are problems advancing to the next position
     * @throws UnsupportedOperationException if advances in this direction are not supported
     */
    boolean previous() throws IOException;


    /**
     * Advances this Cursor to the next position.
     *
     * @return true if the advance succeeded, false otherwise
     * @throws IOException if there are problems advancing to this Cursor to
     * the next position, or if this Cursor is closed
     * @throws UnsupportedOperationException if advances in this direction are not supported
     */
    boolean next() throws IOException;


    /**
     * Gets the object at the current position.  Cursor implementations may
     * choose to reuse element objects by re-populating them on advances
     * instead of creating new objects on each advance.
     *
     * @return the object at the current position
     * @throws IOException if the object at this Cursor's current position
     * cannot be retrieved, or if this Cursor is closed
     */
    E get() throws IOException;


    /**
     * Gets whether or not this Cursor will return the same element object
     * instance on get() operations for any position of this Cursor.  Some
     * Cursor implementations may reuse the same element copying values into
     * it for every position rather than creating and emiting new element
     * objects on each advance.  Some Cursor implementations may return
     * different elements for each position yet the same element instance
     * is returned for the same position. In these cases this method should
     * return true.
     *
     * @return true if elements are reused by this Cursor
     */
    boolean isElementReused();


    /**
     * Closes this Cursor and frees any resources it my have allocated.
     * Repeated calls to this method after this Cursor has already been
     * called should not fail with exceptions.
     *
     * @throws IOException if this Cursor cannot be closed
     */
    void close() throws IOException;
}