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