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