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 }