1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2002,2008 Oracle.  All rights reserved.
5 *
6 * $Id: CursorConfig.java,v 12.9 2008/01/17 05:04:53 mjc Exp $
7 */
8
9package com.sleepycat.db;
10
11import com.sleepycat.db.internal.DbConstants;
12import com.sleepycat.db.internal.Db;
13import com.sleepycat.db.internal.Dbc;
14import com.sleepycat.db.internal.DbTxn;
15
16/**
17Specify the attributes of database cursor.  An instance created with the
18default constructor is initialized with the system's default settings.
19*/
20public class CursorConfig implements Cloneable {
21    /**
22    Default configuration used if null is passed to methods that create a
23    cursor.
24    */
25    public static final CursorConfig DEFAULT = new CursorConfig();
26
27    /**
28        A convenience instance to configure read operations performed by the
29    cursor to return modified but not yet committed data.
30    */
31    public static final CursorConfig READ_UNCOMMITTED = new CursorConfig();
32    static { READ_UNCOMMITTED.setReadUncommitted(true); }
33
34    /**
35        A convenience instance to configure a cursor for read committed isolation.
36    <p>
37    This ensures the stability of the current data item read by the
38    cursor but permits data read by this cursor to be modified or
39    deleted prior to the commit of the transaction.
40    */
41    public static final CursorConfig READ_COMMITTED = new CursorConfig();
42    static { READ_COMMITTED.setReadCommitted(true); }
43
44    /**
45    A convenience instance to specify the Concurrent Data Store environment
46    cursor will be used to update the database.
47    <p>
48    The underlying Berkeley DB database environment must have been
49    configured as a Concurrent Data Store environment.
50    */
51    public static final CursorConfig WRITECURSOR = new CursorConfig();
52    static { WRITECURSOR.setWriteCursor(true); }
53
54    /**
55        A convenience instance to configure read operations performed by the
56    cursor to return modified but not yet committed data.
57        <p>
58    @deprecated This has been replaced by {@link #READ_UNCOMMITTED} to conform to ANSI
59    database isolation terminology.
60    */
61    public static final CursorConfig DIRTY_READ = READ_UNCOMMITTED;
62    /**
63        A convenience instance to configure a cursor for read committed isolation.
64    <p>
65    This ensures the stability of the current data item read by the
66    cursor but permits data read by this cursor to be modified or
67    deleted prior to the commit of the transaction.
68        <p>
69    @deprecated This has been replaced by {@link #READ_COMMITTED} to conform to ANSI
70    database isolation terminology.
71    */
72    public static final CursorConfig DEGREE_2 = READ_COMMITTED;
73
74    private boolean readUncommitted = false;
75    private boolean readCommitted = false;
76    private boolean writeCursor = false;
77
78    /**
79    An instance created using the default constructor is initialized with
80    the system's default settings.
81    */
82    public CursorConfig() {
83    }
84
85    /* package */
86    static CursorConfig checkNull(CursorConfig config) {
87        return (config == null) ? DEFAULT : config;
88    }
89
90    /**
91        Configure the cursor for read committed isolation.
92    <p>
93    This ensures the stability of the current data item read by the
94    cursor but permits data read by this cursor to be modified or
95    deleted prior to the commit of the transaction.
96    <p>
97    @param readCommitted
98    If true, configure the cursor for read committed isolation.
99    */
100    public void setReadCommitted(final boolean readCommitted) {
101        this.readCommitted = readCommitted;
102    }
103
104    /**
105        Return if the cursor is configured for read committed isolation.
106    <p>
107    @return
108    If the cursor is configured for read committed isolation.
109    */
110    public boolean getReadCommitted() {
111        return readCommitted;
112    }
113
114    /**
115        Configure the cursor for read committed isolation.
116    <p>
117    This ensures the stability of the current data item read by the
118    cursor but permits data read by this cursor to be modified or
119    deleted prior to the commit of the transaction.
120    <p>
121    @param degree2
122    If true, configure the cursor for read committed isolation.
123        <p>
124    @deprecated This has been replaced by {@link #setReadCommitted} to conform to ANSI
125    database isolation terminology.
126    */
127    public void setDegree2(final boolean degree2) {
128        setReadCommitted(degree2);
129    }
130
131    /**
132        Return if the cursor is configured for read committed isolation.
133    <p>
134    @return
135    If the cursor is configured for read committed isolation.
136        <p>
137    @deprecated This has been replaced by {@link #getReadCommitted} to conform to ANSI
138    database isolation terminology.
139    */
140    public boolean getDegree2() {
141        return getReadCommitted();
142    }
143
144    /**
145        Configure read operations performed by the cursor to return modified
146    but not yet committed data.
147    <p>
148    @param readUncommitted
149    If true, configure read operations performed by the cursor to return
150    modified but not yet committed data.
151    */
152    public void setReadUncommitted(final boolean readUncommitted) {
153        this.readUncommitted = readUncommitted;
154    }
155
156    /**
157        Return if read operations performed by the cursor are configured to
158    return modified but not yet committed data.
159    <p>
160    @return
161    If read operations performed by the cursor are configured to return
162    modified but not yet committed data.
163    */
164    public boolean getReadUncommitted() {
165        return readUncommitted;
166    }
167
168    /**
169        Configure read operations performed by the cursor to return modified
170    but not yet committed data.
171    <p>
172    @param dirtyRead
173    If true, configure read operations performed by the cursor to return
174    modified but not yet committed data.
175        <p>
176    @deprecated This has been replaced by {@link #setReadUncommitted} to conform to ANSI
177    database isolation terminology.
178    */
179    public void setDirtyRead(final boolean dirtyRead) {
180        setReadUncommitted(dirtyRead);
181    }
182
183    /**
184        Return if read operations performed by the cursor are configured to
185    return modified but not yet committed data.
186    <p>
187    @return
188    If read operations performed by the cursor are configured to return
189    modified but not yet committed data.
190        <p>
191    @deprecated This has been replaced by {@link #getReadUncommitted} to conform to ANSI
192    database isolation terminology.
193    */
194    public boolean getDirtyRead() {
195        return getReadUncommitted();
196    }
197
198    /**
199    Specify the Concurrent Data Store environment cursor will be used to
200    update the database.
201    <p>
202    @param writeCursor
203    If true, specify the Concurrent Data Store environment cursor will be
204    used to update the database.
205    */
206    public void setWriteCursor(final boolean writeCursor) {
207        this.writeCursor = writeCursor;
208    }
209
210    /**
211    Return if the Concurrent Data Store environment cursor will be used to
212    update the database.
213    <p>
214    @return
215    If the Concurrent Data Store environment cursor will be used to update
216    the database.
217    */
218    public boolean getWriteCursor() {
219        return writeCursor;
220    }
221
222    /* package */
223    Dbc openCursor(final Db db, final DbTxn txn)
224        throws DatabaseException {
225
226        int flags = 0;
227        flags |= readUncommitted ? DbConstants.DB_READ_UNCOMMITTED : 0;
228        flags |= readCommitted ? DbConstants.DB_READ_COMMITTED : 0;
229        flags |= writeCursor ? DbConstants.DB_WRITECURSOR : 0;
230        return db.cursor(txn, flags);
231    }
232}
233