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.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 }