001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    package org.apache.directory.shared.ldap.cursor;
020    
021    
022    
023    /**
024     * A Cursor for bidirectional traversal over elements in a dataSet. Cursors
025     * unlike Iterators or Enumerations may advance to an element by calling
026     * next() or previous() which returns true or false if the request succeeds
027     * with a viable element at the new position.  Operations for relative
028     * positioning in larger increments are provided.  If the cursor can not
029     * advance, then the Cursor is either positioned before the first element or
030     * after the last element in which case the user of the Cursor must stop
031     * advancing in the respective direction.  If an advance succeeds a get()
032     * operation retrieves the current object at the Cursors position.
033     *
034     * Although this interface presumes Cursors can advance bidirectionally,
035     * implementations may restrict this by throwing
036     * UnsupportedOperationExceptions.
037     *
038     * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
039     * @version $Rev$, $Date$
040     */
041    public interface Cursor<E> extends Iterable<E>
042    {
043        /**
044         * Determines whether or not a call to get() will succeed.
045         *
046         * @return true if the cursor is valid get() will succeed, false otherwise
047         */
048        boolean available();
049    
050        /**
051         * Prepares this Cursor, so a subsequent call to Cursor#next() with a
052         * true return value, will have positioned the Cursor on a dataSet 
053         * element equal to or less than the element argument but not greater.  
054         * A call to Cursor#previous() with a true return value will position 
055         * the Cursor on a dataSet element less than the argument.  If 
056         * Cursor#next() returns false then the Cursor is past the last element 
057         * and so all values in the dataSet are less than the argument.  If 
058         * Cursor#previous() returns false then the Cursor is positioned before 
059         * the first element and all elements in the dataSet are greater than 
060         * the argument.
061         *
062         * @param element the element to be positioned before
063         * @throws Exception with problems accessing the underlying btree
064         * @throws UnsupportedOperationException if this method is not supported
065         */
066        void before( E element ) throws Exception;
067    
068    
069        /**
070         * Prepares this Cursor, so a subsequent call to Cursor#previous() with a
071         * true return value, will have positioned the Cursor on a dataSet element
072         * equal to or less than the element argument but not greater. A call to
073         * Cursor#next() with a true return value will position the Cursor on a
074         * dataSet element greater than the argument.  If Cursor#next() returns
075         * false then the Cursor is past the last element and so all values in the
076         * dataSet are less than or equal to the argument.  If Cursor#previous()
077         * returns false then the Cursor is positioned before the first element
078         * and all elements in the dataSet are greater than the argument.
079         *
080         * @param element the element to be positioned after
081         * @throws Exception if there are problems positioning this cursor or if
082         * this Cursor is closed
083         * @throws UnsupportedOperationException if this method is not supported
084         */
085        void after( E element ) throws Exception;
086    
087    
088        /**
089         * Positions this Cursor before the first element.
090         *
091         * @throws Exception if there are problems positioning this cursor or if
092         * this Cursor is closed
093         * @throws UnsupportedOperationException if this method is not supported
094         */
095        void beforeFirst() throws Exception;
096    
097    
098        /**
099         * Positions this Cursor after the last element.
100         *
101         * @throws Exception if there are problems positioning this Cursor or if
102         * this Cursor is closed
103         * @throws UnsupportedOperationException if this method is not supported
104         */
105        void afterLast() throws Exception;
106    
107    
108        /**
109         * Positions this Cursor at the first element.
110         *
111         * @return true if the position has been successfully changed to the first
112         * element, false otherwise
113         * @throws Exception if there are problems positioning this Cursor or if
114         * this Cursor is closed
115         * @throws UnsupportedOperationException if this method is not supported
116         */
117        boolean first() throws Exception;
118    
119    
120        /**
121         * Positions this Cursor at the last element.
122         *
123         * @return true if the position has been successfully changed to the last
124         * element, false otherwise
125         * @throws Exception if there are problems positioning this Cursor or if
126         * this Cursor is closed
127         * @throws UnsupportedOperationException if this method is not supported
128         */
129        boolean last() throws Exception;
130    
131    
132        /**
133         * Checks if this Cursor is closed.  Calls to this operation should not
134         * fail with exceptions if and only if the cursor is in the closed state.
135         *
136         * @return true if this Cursor is closed, false otherwise
137         * @throws Exception if there are problems determining the cursor's closed state
138         * @throws UnsupportedOperationException if this method is not supported
139         */
140        boolean isClosed() throws Exception;
141    
142    
143        /**
144         * Advances this Cursor to the previous position.  If called before
145         * explicitly positioning this Cursor, the position is presumed to be
146         * after the last element and this method moves the cursor back to the
147         * last element.
148         *
149         * @return true if the advance succeeded, false otherwise
150         * @throws Exception if there are problems advancing to the next position
151         * @throws UnsupportedOperationException if this method is not supported
152         */
153        boolean previous() throws Exception;
154    
155    
156        /**
157         * Advances this Cursor to the next position.  If called before
158         * explicitly positioning this Cursor, the position is presumed to be
159         * before the first element and this method moves the cursor forward to
160         * the first element.
161         *
162         * @return true if the advance succeeded, false otherwise
163         * @throws Exception if there are problems advancing to this Cursor to
164         * the next position, or if this Cursor is closed
165         * @throws UnsupportedOperationException if this method is not supported
166         */
167        boolean next() throws Exception;
168    
169    
170        /**
171         * Gets the object at the current position.  Cursor implementations may
172         * choose to reuse element objects by re-populating them on advances
173         * instead of creating new objects on each advance.
174         *
175         * @return the object at the current position
176         * @throws Exception if the object at this Cursor's current position
177         * cannot be retrieved, or if this Cursor is closed
178         */
179        E get() throws Exception;
180    
181    
182        /**
183         * Gets whether or not this Cursor will return the same element object
184         * instance on get() operations for any position of this Cursor.  Some
185         * Cursor implementations may reuse the same element copying values into
186         * it for every position rather than creating and emit new element
187         * objects on each advance.  Some Cursor implementations may return
188         * different elements for each position yet the same element instance
189         * is returned for the same position. In these cases this method should
190         * return true.
191         *
192         * @return true if elements are reused by this Cursor
193         */
194        boolean isElementReused();
195    
196    
197        /**
198         * Closes this Cursor and frees any resources it my have allocated.
199         * Repeated calls to this method after this Cursor has already been
200         * called should not fail with exceptions.
201         *
202         * @throws Exception if for some reason this Cursor could not be closed
203         */
204        void close() throws Exception;
205    
206    
207        /**
208         * Closes this Cursor and frees any resources it my have allocated.
209         * Repeated calls to this method after this Cursor has already been
210         * called should not fail with exceptions.  The reason argument is 
211         * the Exception instance thrown instead of the standard 
212         * CursorClosedException.
213         *
214         * @param reason exception thrown when this Cursor is accessed after close
215         * @throws Exception if for some reason this Cursor could not be closed
216         */
217        void close( Exception reason ) throws Exception;
218        
219        
220        /**
221         * Sets a non-null closure monitor to associate with this Cursor.
222         *
223         * @param monitor the monitor to use for detecting Cursor close events
224         */
225        void setClosureMonitor( ClosureMonitor monitor );
226    }