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.Closeable;
23  import java.io.IOException;
24  
25  import org.apache.directory.api.ldap.model.exception.LdapException;
26  
27  
28  /**
29   * A Cursor for bidirectional traversal over elements in a dataSet. Cursors
30   * unlike Iterators or Enumerations may advance to an element by calling
31   * next() or previous() which returns true or false if the request succeeds
32   * with a viable element at the new position.  Operations for relative
33   * positioning in larger increments are provided.  If the cursor can not
34   * advance, then the Cursor is either positioned before the first element or
35   * after the last element in which case the user of the Cursor must stop
36   * advancing in the respective direction.  If an advance succeeds a get()
37   * operation retrieves the current object at the Cursors position.
38   *
39   * Although this interface presumes Cursors can advance bidirectionally,
40   * implementations may restrict this by throwing
41   * UnsupportedOperationExceptions.
42   *
43   * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
44   * @param <E> The type of element on which this cursor will iterate
45   */
46  public interface Cursor<E> extends Iterable<E>, Closeable
47  {
48      /**
49       * Determines whether or not a call to get() will succeed.
50       *
51       * @return true if a call to the get() method will succeed, false otherwise
52       */
53      boolean available();
54  
55  
56      /**
57       * Prepares this Cursor, so a subsequent call to Cursor#next() with a
58       * true return value, will have positioned the Cursor on a dataSet 
59       * element equal to or less than the element argument but not greater.  
60       * A call to Cursor#previous() with a true return value will position 
61       * the Cursor on a dataSet element less than the argument.  If 
62       * Cursor#next() returns false then the Cursor is past the last element 
63       * and so all values in the dataSet are less than the argument.  If 
64       * Cursor#previous() returns false then the Cursor is positioned before 
65       * the first element and all elements in the dataSet are greater than 
66       * the argument.
67       *
68       * @param element the element to be positioned before
69       * @throws LdapException if we have get any LDAP exception while operating
70       * the cursor
71       * @throws CursorException if there are problems advancing to this Cursor before
72       * the given element, or if this Cursor is closed 
73       */
74      void before( E element ) throws LdapException, CursorException;
75  
76  
77      /**
78       * Prepares this Cursor, so a subsequent call to Cursor#previous() with a
79       * true return value, will have positioned the Cursor on a dataSet element
80       * equal to or less than the element argument but not greater. A call to
81       * Cursor#next() with a true return value will position the Cursor on a
82       * dataSet element greater than the argument.  If Cursor#next() returns
83       * false then the Cursor is past the last element and so all values in the
84       * dataSet are less than or equal to the argument.  If Cursor#previous()
85       * returns false then the Cursor is positioned before the first element
86       * and all elements in the dataSet are greater than the argument.
87       *
88       * @param element the element to be positioned after
89       * @throws LdapException if we have get any LDAP exception while operating
90       * the cursor
91       * @throws CursorException if there are problems advancing to this Cursor after
92       * the given element, or if this Cursor is closed 
93       */
94      void after( E element ) throws LdapException, CursorException;
95  
96  
97      /**
98       * Positions this Cursor before the first element.
99       *
100      * @throws LdapException if we have get any LDAP exception while operating
101      * the cursor
102      * @throws CursorException if there are problems advancing to this Cursor before
103      * the first position, or if this Cursor is closed 
104      */
105     void beforeFirst() throws LdapException, CursorException;
106 
107 
108     /**
109      * Positions this Cursor after the last element.
110      *
111      * @throws LdapException if we have get any LDAP exception while operating
112      * the cursor
113      * @throws CursorException if there are problems advancing to this Cursor after
114      * the last position, or if this Cursor is closed 
115      */
116     void afterLast() throws LdapException, CursorException;
117 
118 
119     /**
120      * Positions this Cursor at the first element.
121      *
122      * @return true if the position has been successfully changed to the first
123      * element, false otherwise
124      * @throws LdapException if we have get any LDAP exception while operating
125      * the cursor
126      * @throws CursorException if there are problems advancing to this Cursor to
127      * the first position, or if this Cursor is closed 
128      */
129     boolean first() throws LdapException, CursorException;
130 
131 
132     /**
133      * Is this Cursor positioned at the first element.
134      *
135      * @return true if this cursor is positioned at the first element, 
136      * false otherwise
137      */
138     boolean isFirst();
139 
140 
141     /**
142      * Is this Cursor positioned before the first element.
143      *
144      * @return true if this cursor is positioned before the first element, 
145      * false otherwise
146      */
147     boolean isBeforeFirst();
148 
149 
150     /**
151      * Positions this Cursor at the last element.
152      *
153      * @return true if the position has been successfully changed to the last
154      * element, false otherwise
155      * @throws LdapException if we have get any LDAP exception while operating
156      * the cursor
157      * @throws CursorException if there are problems advancing to this Cursor to
158      * the last position, or if this Cursor is closed 
159      */
160     boolean last() throws LdapException, CursorException;
161 
162 
163     /**
164      * Is this Cursor positioned at the last element.
165      *
166      * @return true if this cursor is positioned at the last element, 
167      * false otherwise
168      */
169     boolean isLast();
170 
171 
172     /**
173      * Is this Cursor positioned after the last element.
174      *
175      * @return true if this cursor is positioned after the last element, 
176      * false otherwise
177      */
178     boolean isAfterLast();
179 
180 
181     /**
182      * Checks if this Cursor is closed.  Calls to this operation should not
183      * fail with exceptions if and only if the cursor is in the closed state.
184      *
185      * @return true if this Cursor is closed, false otherwise
186      */
187     boolean isClosed();
188 
189 
190     /**
191      * Advances this Cursor to the previous position.  If called before
192      * explicitly positioning this Cursor, the position is presumed to be
193      * after the last element and this method moves the cursor back to the
194      * last element.
195      *
196      * @return true if the advance succeeded, false otherwise
197      * @throws LdapException if we have get any LDAP exception while operating
198      * the cursor
199      * @throws CursorException if there are problems advancing to this Cursor to
200      * the previous position, or if this Cursor is closed 
201      */
202     boolean previous() throws LdapException, CursorException;
203 
204 
205     /**
206      * Advances this Cursor to the next position.  If called before
207      * explicitly positioning this Cursor, the position is presumed to be
208      * before the first element and this method moves the cursor forward to
209      * the first element.
210      *
211      * @return true if the advance succeeded, false otherwise
212      * @throws LdapException if we have get any LDAP exception while operating
213      * the cursor
214      * @throws CursorException if there are problems advancing to this Cursor to
215      * the next position, or if this Cursor is closed 
216      */
217     boolean next() throws LdapException, CursorException;
218 
219 
220     /**
221      * Gets the object at the current position.  Cursor implementations may
222      * choose to reuse element objects by re-populating them on advances
223      * instead of creating new objects on each advance.
224      *
225      * @return the object at the current position
226      * @throws CursorException if the object at this Cursor's current position
227      * cannot be retrieved, or if this Cursor is closed
228      */
229     E get() throws CursorException;
230 
231 
232     /**
233      * Closes this Cursor and frees any resources it my have allocated.
234      * Repeated calls to this method after this Cursor has already been
235      * called should not fail with exceptions.  The reason argument is 
236      * the Exception instance thrown instead of the standard 
237      * CursorClosedException.
238      *
239      * @param reason exception thrown when this Cursor is accessed after close
240      * @throws IOException If we can't close the Cursor 
241      */
242     void close( Exception reason ) throws IOException;
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 }