KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sleepycat > persist > ForwardCursor


1 /*-
2  * See the file LICENSE for redistribution information.
3  *
4  * Copyright (c) 2002,2006 Oracle. All rights reserved.
5  *
6  * $Id: ForwardCursor.java,v 1.7 2006/10/30 21:14:30 bostic Exp $
7  */

8
9 package com.sleepycat.persist;
10
11 import java.util.Iterator JavaDoc;
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 JavaDoc<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 JavaDoc<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 JavaDoc<V> iterator(LockMode lockMode);
81
82     /**
83      * Closes the cursor.
84      */

85     void close()
86         throws DatabaseException;
87 }
88
Popular Tags