1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2002,2008 Oracle. All rights reserved. 5 * 6 * $Id: ForwardCursor.java,v 1.1 2008/02/07 17:12:26 mark Exp $ 7 */ 8 9package com.sleepycat.persist; 10 11import java.util.Iterator; 12 13import com.sleepycat.db.DatabaseException; 14import com.sleepycat.db.LockMode; 15 16/** 17 * Cursor operations limited to traversing forward. See {@link EntityCursor} 18 * for general information on cursors. 19 * 20 * <p>{@code ForwardCursor} objects are <em>not</em> thread-safe. Cursors 21 * should be opened, used and closed by a single thread.</p> 22 * 23 * <p><em>WARNING:</em> Cursors must always be closed to prevent resource leaks 24 * which could lead to the index becoming unusable or cause an 25 * <code>OutOfMemoryError</code>. To ensure that a cursor is closed in the 26 * face of exceptions, close it in a finally block.</p> 27 * 28 * @author Mark Hayes 29 */ 30public interface ForwardCursor<V> extends Iterable<V> { 31 32 /** 33 * Moves the cursor to the next value and returns it, or returns null 34 * if there are no more values in the cursor range. If the cursor is 35 * uninitialized, this method returns the first value. 36 * 37 * <p>{@link LockMode#DEFAULT} is used implicitly.</p> 38 * 39 * @return the next value, or null if there are no more values in the 40 * cursor range. 41 */ 42 V next() 43 throws DatabaseException; 44 45 /** 46 * Moves the cursor to the next value and returns it, or returns null 47 * if there are no more values in the cursor range. If the cursor is 48 * uninitialized, this method returns the first value. 49 * 50 * @param lockMode the lock mode to use for this operation, or null to 51 * use {@link LockMode#DEFAULT}. 52 * 53 * @return the next value, or null if there are no more values in the 54 * cursor range. 55 */ 56 V next(LockMode lockMode) 57 throws DatabaseException; 58 59 /** 60 * Returns an iterator over the key range, starting with the value 61 * following the current position or at the first value if the cursor is 62 * uninitialized. 63 * 64 * <p>{@link LockMode#DEFAULT} is used implicitly.</p> 65 * 66 * @return the iterator. 67 */ 68 Iterator<V> iterator(); 69 70 /** 71 * Returns an iterator over the key range, starting with the value 72 * following the current position or at the first value if the cursor is 73 * uninitialized. 74 * 75 * @param lockMode the lock mode to use for all operations performed 76 * using the iterator, or null to use {@link LockMode#DEFAULT}. 77 * 78 * @return the iterator. 79 */ 80 Iterator<V> iterator(LockMode lockMode); 81 82 /** 83 * Closes the cursor. 84 */ 85 void close() 86 throws DatabaseException; 87} 88