View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *  http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.directory.api.ldap.model.cursor;
20  
21  
22  import java.io.IOException;
23  
24  import org.apache.directory.api.ldap.model.exception.LdapException;
25  
26  
27  /**
28   * A Cursor for bidirectional traversal over elements in a dataSet. Cursors
29   * unlike Iterators or Enumerations may advance to an element by calling
30   * next() or previous() which returns true or false if the request succeeds
31   * with a viable element at the new position.  Operations for relative
32   * positioning in larger increments are provided.  If the cursor can not
33   * advance, then the Cursor is either positioned before the first element or
34   * after the last element in which case the user of the Cursor must stop
35   * advancing in the respective direction.  If an advance succeeds a get()
36   * operation retrieves the current object at the Cursors position.
37   *
38   * Although this interface presumes Cursors can advance bidirectionally,
39   * implementations may restrict this by throwing
40   * UnsupportedOperationExceptions.
41   *
42   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
43   * @param <E> The type of element on which this cursor will iterate
44   */
45  public interface Cursor<E> extends Iterable<E>
46  {
47      /**
48       * Determines whether or not a call to get() will succeed.
49       *
50       * @return true if a call to the get() method will succeed, false otherwise
51       */
52      boolean available();
53  
54  
55      /**
56       * Prepares this Cursor, so a subsequent call to Cursor#next() with a
57       * true return value, will have positioned the Cursor on a dataSet 
58       * element equal to or less than the element argument but not greater.  
59       * A call to Cursor#previous() with a true return value will position 
60       * the Cursor on a dataSet element less than the argument.  If 
61       * Cursor#next() returns false then the Cursor is past the last element 
62       * and so all values in the dataSet are less than the argument.  If 
63       * Cursor#previous() returns false then the Cursor is positioned before 
64       * the first element and all elements in the dataSet are greater than 
65       * the argument.
66       *
67       * @param element the element to be positioned before
68       * @throws Exception with problems accessing the underlying btree
69       */
70      void before( E element ) throws LdapException, CursorException;
71  
72  
73      /**
74       * Prepares this Cursor, so a subsequent call to Cursor#previous() with a
75       * true return value, will have positioned the Cursor on a dataSet element
76       * equal to or less than the element argument but not greater. A call to
77       * Cursor#next() with a true return value will position the Cursor on a
78       * dataSet element greater than the argument.  If Cursor#next() returns
79       * false then the Cursor is past the last element and so all values in the
80       * dataSet are less than or equal to the argument.  If Cursor#previous()
81       * returns false then the Cursor is positioned before the first element
82       * and all elements in the dataSet are greater than the argument.
83       *
84       * @param element the element to be positioned after
85       * @throws Exception if there are problems positioning this cursor or if
86       * this Cursor is closed
87       */
88      void after( E element ) throws LdapException, CursorException;
89  
90  
91      /**
92       * Positions this Cursor before the first element.
93       *
94       * @throws Exception if there are problems positioning this cursor or if
95       * this Cursor is closed
96       */
97      void beforeFirst() throws LdapException, CursorException;
98  
99  
100     /**
101      * Positions this Cursor after the last element.
102      *
103      * @throws Exception if there are problems positioning this Cursor or if
104      * this Cursor is closed
105      */
106     void afterLast() throws LdapException, CursorException;
107 
108 
109     /**
110      * Positions this Cursor at the first element.
111      *
112      * @return true if the position has been successfully changed to the first
113      * element, false otherwise
114      * @throws Exception if there are problems positioning this Cursor or if
115      * this Cursor is closed
116      */
117     boolean first() throws LdapException, CursorException;
118 
119 
120     /**
121      * Is this Cursor positioned at the first element.
122      *
123      * @return true if this cursor is positioned at the first element, 
124      * false otherwise
125      * @throws Exception if there are problems querying the position of this Cursor
126      * or if this Cursor is closed
127      */
128     boolean isFirst();
129 
130 
131     /**
132      * Is this Cursor positioned before the first element.
133      *
134      * @return true if this cursor is positioned before the first element, 
135      * false otherwise
136      * @throws Exception if there are problems querying the position of this Cursor
137      * or if this Cursor is closed
138      */
139     boolean isBeforeFirst();
140 
141 
142     /**
143      * Positions this Cursor at the last element.
144      *
145      * @return true if the position has been successfully changed to the last
146      * element, false otherwise
147      * @throws Exception if there are problems positioning this Cursor or if
148      * this Cursor is closed
149      */
150     boolean last() throws LdapException, CursorException;
151 
152 
153     /**
154      * Is this Cursor positioned at the last element.
155      *
156      * @return true if this cursor is positioned at the last element, 
157      * false otherwise
158      * @throws Exception if there are problems querying the position of this Cursor
159      * or if this Cursor is closed
160      */
161     boolean isLast();
162 
163 
164     /**
165      * Is this Cursor positioned after the last element.
166      *
167      * @return true if this cursor is positioned after the last element, 
168      * false otherwise
169      * @throws Exception if there are problems querying the position of this Cursor
170      * or if this Cursor is closed
171      */
172     boolean isAfterLast();
173 
174 
175     /**
176      * Checks if this Cursor is closed.  Calls to this operation should not
177      * fail with exceptions if and only if the cursor is in the closed state.
178      *
179      * @return true if this Cursor is closed, false otherwise
180      */
181     boolean isClosed();
182 
183 
184     /**
185      * Advances this Cursor to the previous position.  If called before
186      * explicitly positioning this Cursor, the position is presumed to be
187      * after the last element and this method moves the cursor back to the
188      * last element.
189      *
190      * @return true if the advance succeeded, false otherwise
191      * @throws Exception if there are problems advancing to the next position
192      */
193     boolean previous() throws LdapException, CursorException;
194 
195 
196     /**
197      * Advances this Cursor to the next position.  If called before
198      * explicitly positioning this Cursor, the position is presumed to be
199      * before the first element and this method moves the cursor forward to
200      * the first element.
201      *
202      * @return true if the advance succeeded, false otherwise
203      * @throws LdapException if we have get any LDAP exception while operating
204      * the cursor
205      * @throws CursorException if there are problems advancing to this Cursor to
206      * the next position, or if this Cursor is closed 
207      * @throws IOException If we have had any IO Exception
208      */
209     boolean next() throws LdapException, CursorException;
210 
211 
212     /**
213      * Gets the object at the current position.  Cursor implementations may
214      * choose to reuse element objects by re-populating them on advances
215      * instead of creating new objects on each advance.
216      *
217      * @return the object at the current position
218      * @throws CursorException if the object at this Cursor's current position
219      * cannot be retrieved, or if this Cursor is closed
220      * @throws IOException If we have had any IO Exception
221      */
222     E get() throws CursorException;
223 
224 
225     /**
226      * Closes this Cursor and frees any resources it my have allocated.
227      * Repeated calls to this method after this Cursor has already been
228      * called should not fail with exceptions.
229      */
230     void close();
231 
232 
233     /**
234      * Closes this Cursor and frees any resources it my have allocated.
235      * Repeated calls to this method after this Cursor has already been
236      * called should not fail with exceptions.  The reason argument is 
237      * the Exception instance thrown instead of the standard 
238      * CursorClosedException.
239      *
240      * @param reason exception thrown when this Cursor is accessed after close
241      */
242     void close( Exception reason );
243 
244 
245     /**
246      * Sets a non-null closure monitor to associate with this Cursor.
247      *
248      * @param monitor the monitor to use for detecting Cursor close events
249      */
250     void setClosureMonitor( ClosureMonitor monitor );
251 
252 
253     /**
254      * Pretty-print a cursor and its wrapped cursor.
255      * @param tabs The spaces to add at each level
256      * @return The cursor and all it's wrapped elements, recursively printed
257      */
258     String toString( String tabs );
259 }