| /* |
| * 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.shared.ldap.cursor; |
| |
| |
| |
| /** |
| * A Cursor for bidirectional traversal over elements in a dataSet. Cursors |
| * unlike Iterators or Enumerations may advance to an element by calling |
| * next() or previous() which returns true or false if the request succeeds |
| * with a viable element at the new position. Operations for relative |
| * positioning in larger increments are provided. If the cursor can 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 retrieves the current object at the Cursors position. |
| * |
| * Although this interface presumes Cursors can advance bidirectionally, |
| * implementations may restrict this by throwing |
| * UnsupportedOperationExceptions. |
| * |
| * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a> |
| */ |
| public interface Cursor<E> extends Iterable<E> |
| { |
| /** |
| * Determines whether or not a call to get() will succeed. |
| * |
| * @return true if a call to the get() method will succeed, false otherwise |
| */ |
| boolean available(); |
| |
| /** |
| * Prepares this Cursor, so a subsequent call to Cursor#next() with a |
| * true return value, will have positioned the Cursor on a dataSet |
| * element equal to or less than the element argument but not greater. |
| * A call to Cursor#previous() with a true return value will position |
| * the Cursor on a dataSet element less than the argument. If |
| * Cursor#next() returns false then the Cursor is past the last element |
| * and so all values in the dataSet are less than the argument. If |
| * Cursor#previous() returns false then the Cursor is positioned before |
| * the first element and all elements in the dataSet are greater than |
| * the argument. |
| * |
| * @param element the element to be positioned before |
| * @throws Exception with problems accessing the underlying btree |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| void before( E element ) throws Exception; |
| |
| |
| /** |
| * Prepares this Cursor, so a subsequent call to Cursor#previous() with a |
| * true return value, will have positioned the Cursor on a dataSet element |
| * equal to or less than the element argument but not greater. A call to |
| * Cursor#next() with a true return value will position the Cursor on a |
| * dataSet element greater than the argument. If Cursor#next() returns |
| * false then the Cursor is past the last element and so all values in the |
| * dataSet are less than or equal to the argument. If Cursor#previous() |
| * returns false then the Cursor is positioned before the first element |
| * and all elements in the dataSet are greater than the argument. |
| * |
| * @param element the element to be positioned after |
| * @throws Exception if there are problems positioning this cursor or if |
| * this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| void after( E element ) throws Exception; |
| |
| |
| /** |
| * Positions this Cursor before the first element. |
| * |
| * @throws Exception if there are problems positioning this cursor or if |
| * this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| void beforeFirst() throws Exception; |
| |
| |
| /** |
| * Positions this Cursor after the last element. |
| * |
| * @throws Exception if there are problems positioning this Cursor or if |
| * this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| void afterLast() throws Exception; |
| |
| |
| /** |
| * Positions this Cursor at the first element. |
| * |
| * @return true if the position has been successfully changed to the first |
| * element, false otherwise |
| * @throws Exception if there are problems positioning this Cursor or if |
| * this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean first() throws Exception; |
| |
| |
| /** |
| * Is this Cursor positioned at the first element. |
| * |
| * @return true if this cursor is positioned at the first element, |
| * false otherwise |
| * @throws Exception if there are problems querying the position of this Cursor |
| * or if this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean isFirst() throws Exception; |
| |
| |
| /** |
| * Is this Cursor positioned before the first element. |
| * |
| * @return true if this cursor is positioned before the first element, |
| * false otherwise |
| * @throws Exception if there are problems querying the position of this Cursor |
| * or if this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean isBeforeFirst() throws Exception; |
| |
| |
| /** |
| * Positions this Cursor at the last element. |
| * |
| * @return true if the position has been successfully changed to the last |
| * element, false otherwise |
| * @throws Exception if there are problems positioning this Cursor or if |
| * this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean last() throws Exception; |
| |
| |
| /** |
| * Is this Cursor positioned at the last element. |
| * |
| * @return true if this cursor is positioned at the last element, |
| * false otherwise |
| * @throws Exception if there are problems querying the position of this Cursor |
| * or if this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean isLast() throws Exception; |
| |
| |
| /** |
| * Is this Cursor positioned after the last element. |
| * |
| * @return true if this cursor is positioned after the last element, |
| * false otherwise |
| * @throws Exception if there are problems querying the position of this Cursor |
| * or if this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean isAfterLast() throws Exception; |
| |
| |
| /** |
| * Checks if this Cursor 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 Exception if there are problems determining the cursor's closed state |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean isClosed() throws Exception; |
| |
| |
| /** |
| * Advances this Cursor to the previous position. If called before |
| * explicitly positioning this Cursor, the position is presumed to be |
| * after the last element and this method moves the cursor back to the |
| * last element. |
| * |
| * @return true if the advance succeeded, false otherwise |
| * @throws Exception if there are problems advancing to the next position |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean previous() throws Exception; |
| |
| |
| /** |
| * Advances this Cursor to the next position. If called before |
| * explicitly positioning this Cursor, the position is presumed to be |
| * before the first element and this method moves the cursor forward to |
| * the first element. |
| * |
| * @return true if the advance succeeded, false otherwise |
| * @throws Exception if there are problems advancing to this Cursor to |
| * the next position, or if this Cursor is closed |
| * @throws UnsupportedOperationException if this method is not supported |
| */ |
| boolean next() throws Exception; |
| |
| |
| /** |
| * 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 Exception if the object at this Cursor's current position |
| * cannot be retrieved, or if this Cursor is closed |
| */ |
| E get() throws Exception; |
| |
| |
| /** |
| * 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 emit 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 Exception if for some reason this Cursor could not be closed |
| */ |
| void close() throws Exception; |
| |
| |
| /** |
| * 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. The reason argument is |
| * the Exception instance thrown instead of the standard |
| * CursorClosedException. |
| * |
| * @param reason exception thrown when this Cursor is accessed after close |
| * @throws Exception if for some reason this Cursor could not be closed |
| */ |
| void close( Exception reason ) throws Exception; |
| |
| |
| /** |
| * Sets a non-null closure monitor to associate with this Cursor. |
| * |
| * @param monitor the monitor to use for detecting Cursor close events |
| */ |
| void setClosureMonitor( ClosureMonitor monitor ); |
| } |