01: /*-
02: * See the file LICENSE for redistribution information.
03: *
04: * Copyright (c) 2002,2008 Oracle. All rights reserved.
05: *
06: * $Id: ForwardCursor.java,v 1.7.2.2 2008/01/07 15:14:18 cwl Exp $
07: */
08:
09: package com.sleepycat.persist;
10:
11: import java.util.Iterator;
12:
13: import com.sleepycat.je.DatabaseException;
14: import com.sleepycat.je.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: */
30: public 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() throws DatabaseException;
43:
44: /**
45: * Moves the cursor to the next value and returns it, or returns null
46: * if there are no more values in the cursor range. If the cursor is
47: * uninitialized, this method returns the first value.
48: *
49: * @param lockMode the lock mode to use for this operation, or null to
50: * use {@link LockMode#DEFAULT}.
51: *
52: * @return the next value, or null if there are no more values in the
53: * cursor range.
54: */
55: V next(LockMode lockMode) throws DatabaseException;
56:
57: /**
58: * Returns an iterator over the key range, starting with the value
59: * following the current position or at the first value if the cursor is
60: * uninitialized.
61: *
62: * <p>{@link LockMode#DEFAULT} is used implicitly.</p>
63: *
64: * @return the iterator.
65: */
66: Iterator<V> iterator();
67:
68: /**
69: * Returns an iterator over the key range, starting with the value
70: * following the current position or at the first value if the cursor is
71: * uninitialized.
72: *
73: * @param lockMode the lock mode to use for all operations performed
74: * using the iterator, or null to use {@link LockMode#DEFAULT}.
75: *
76: * @return the iterator.
77: */
78: Iterator<V> iterator(LockMode lockMode);
79:
80: /**
81: * Closes the cursor.
82: */
83: void close() throws DatabaseException;
84: }
|