1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2002,2008 Oracle.  All rights reserved.
5 *
6 * $Id: TransactionConfig.java,v 12.12 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.DbEnv;
13import com.sleepycat.db.internal.DbTxn;
14
15/**
16Specifies the attributes of a database environment transaction.
17*/
18public class TransactionConfig implements Cloneable {
19    /*
20     * For internal use, to allow null as a valid value for
21     * the config parameter.
22     */
23    /**
24    Default configuration used if null is passed to methods that create a
25    transaction.
26    */
27    public static final TransactionConfig DEFAULT = new TransactionConfig();
28
29    /* package */
30    static TransactionConfig checkNull(TransactionConfig config) {
31        return (config == null) ? DEFAULT : config;
32    }
33
34    private boolean readUncommitted = false;
35    private boolean readCommitted = false;
36    private boolean noSync = false;
37    private boolean noWait = false;
38    private boolean snapshot = false;
39    private boolean sync = false;
40    private boolean writeNoSync = false;
41    private boolean wait = false;
42
43    /**
44    An instance created using the default constructor is initialized
45    with the system's default settings.
46    */
47    public TransactionConfig() {
48    }
49
50    /**
51        Configure the transaction for read committed isolation.
52    <p>
53    This ensures the stability of the current data item read by the
54    cursor but permits data read by this transaction to be modified or
55    deleted prior to the commit of the transaction.
56    <p>
57    @param readCommitted
58    If true, configure the transaction for read committed isolation.
59    */
60    public void setReadCommitted(final boolean readCommitted) {
61        this.readCommitted = readCommitted;
62    }
63
64    /**
65        Return if the transaction is configured for read committed isolation.
66    <p>
67    @return
68    If the transaction is configured for read committed isolation.
69    */
70    public boolean getReadCommitted() {
71        return readCommitted;
72    }
73
74    /**
75        Configure the transaction for read committed isolation.
76    <p>
77    This ensures the stability of the current data item read by the
78    cursor but permits data read by this transaction to be modified or
79    deleted prior to the commit of the transaction.
80    <p>
81    @param degree2
82    If true, configure the transaction for read committed isolation.
83        <p>
84    @deprecated This has been replaced by {@link #setReadCommitted} to conform to ANSI
85    database isolation terminology.
86    */
87    public void setDegree2(final boolean degree2) {
88        setReadCommitted(degree2);
89    }
90
91    /**
92        Return if the transaction is configured for read committed isolation.
93    <p>
94    @return
95    If the transaction is configured for read committed isolation.
96        <p>
97    @deprecated This has been replaced by {@link #getReadCommitted} to conform to ANSI
98    database isolation terminology.
99    */
100    public boolean getDegree2() {
101        return getReadCommitted();
102    }
103
104    /**
105        Configure read operations performed by the transaction to return modified
106    but not yet committed data.
107    <p>
108    @param readUncommitted
109    If true, configure read operations performed by the transaction to return
110    modified but not yet committed data.
111    */
112    public void setReadUncommitted(final boolean readUncommitted) {
113        this.readUncommitted = readUncommitted;
114    }
115
116    /**
117        Return if read operations performed by the transaction are configured to
118    return modified but not yet committed data.
119    <p>
120    @return
121    If read operations performed by the transaction are configured to return
122    modified but not yet committed data.
123    */
124    public boolean getReadUncommitted() {
125        return readUncommitted;
126    }
127
128    /**
129        Configure read operations performed by the transaction to return modified
130    but not yet committed data.
131    <p>
132    @param dirtyRead
133    If true, configure read operations performed by the transaction to return
134    modified but not yet committed data.
135        <p>
136    @deprecated This has been replaced by {@link #setReadUncommitted} to conform to ANSI
137    database isolation terminology.
138    */
139    public void setDirtyRead(final boolean dirtyRead) {
140        setReadUncommitted(dirtyRead);
141    }
142
143    /**
144        Return if read operations performed by the transaction are configured to
145    return modified but not yet committed data.
146    <p>
147    @return
148    If read operations performed by the transaction are configured to return
149    modified but not yet committed data.
150        <p>
151    @deprecated This has been replaced by {@link #getReadUncommitted} to conform to ANSI
152    database isolation terminology.
153    */
154    public boolean getDirtyRead() {
155        return getReadUncommitted();
156    }
157
158    /**
159    Configure the transaction to not write or synchronously flush the log
160    it when commits.
161    <p>
162    This behavior may be set for a database environment using the
163    Environment.setMutableConfig method. Any value specified to this method
164    overrides that setting.
165    <p>
166    The default is false for this class and the database environment.
167    <p>
168    @param noSync
169    If true, transactions exhibit the ACI (atomicity, consistency, and
170    isolation) properties, but not D (durability); that is, database
171    integrity will be maintained, but if the application or system
172    fails, it is possible some number of the most recently committed
173    transactions may be undone during recovery. The number of
174    transactions at risk is governed by how many log updates can fit
175    into the log buffer, how often the operating system flushes dirty
176    buffers to disk, and how often the log is checkpointed.
177    */
178    public void setNoSync(final boolean noSync) {
179        this.noSync = noSync;
180    }
181
182    /**
183    Return if the transaction is configured to not write or synchronously
184    flush the log it when commits.
185    <p>
186    @return
187    If the transaction is configured to not write or synchronously flush
188    the log it when commits.
189    */
190    public boolean getNoSync() {
191        return noSync;
192    }
193
194    /**
195    Configure the transaction to not wait if a lock request cannot be
196    immediately granted.
197    <p>
198    The default is false for this class and the database environment.
199    <p>
200    @param noWait
201    If true, transactions will not wait if a lock request cannot be
202    immediately granted, instead {@link com.sleepycat.db.DeadlockException DeadlockException} will be thrown.
203    */
204    public void setNoWait(final boolean noWait) {
205        this.noWait = noWait;
206    }
207
208    /**
209    Return if the transaction is configured to not wait if a lock
210    request cannot be immediately granted.
211    <p>
212    @return
213    If the transaction is configured to not wait if a lock request
214    cannot be immediately granted.
215    */
216    public boolean getNoWait() {
217        return noWait;
218    }
219
220    /**
221    This transaction will execute with snapshot isolation.  For databases
222    configured with {@link DatabaseConfig#setMultiversion}, data values
223    will be read as they are when the transaction begins, without taking
224    read locks.
225    <p>
226    Updates operations performed in the transaction will cause a
227    {@link DeadlockException} to be thrown if data is modified
228    between reading and writing it.
229    */
230    public void setSnapshot(final boolean snapshot) {
231        this.snapshot = snapshot;
232    }
233
234    /**
235Return true if the transaction is configured for Snapshot Isolation.
236<p>
237This method may be called at any time during the life of the application.
238<p>
239@return
240True if the transaction is configured for Snapshot Isolation.
241    */
242    public boolean getSnapshot() {
243        return snapshot;
244    }
245
246    /**
247    Configure the transaction to write and synchronously flush the log
248    it when commits.
249    <p>
250    This behavior may be set for a database environment using the
251    Environment.setMutableConfig method. Any value specified to this
252    method overrides that setting.
253    <p>
254    The default is false for this class and true for the database
255    environment.
256    <p>
257    If true is passed to both setSync and setNoSync, setSync will take
258    precedence.
259    <p>
260    @param sync
261    If true, transactions exhibit all the ACID (atomicity, consistency,
262    isolation, and durability) properties.
263    */
264    public void setSync(final boolean sync) {
265        this.sync = sync;
266    }
267
268    /**
269    Return if the transaction is configured to write and synchronously
270    flush the log it when commits.
271    <p>
272    @return
273    If the transaction is configured to write and synchronously flush
274    the log it when commits.
275    */
276    public boolean getSync() {
277        return sync;
278    }
279
280    /**
281    Configure the transaction to wait if a lock request cannot be
282    immediately granted.
283    <p>
284    The default is true unless {@link EnvironmentConfig#setTxnNoWait} is called.
285    <p>
286    @param wait
287    If true, transactions will wait if a lock request cannot be
288    immediately granted, instead {@link com.sleepycat.db.DeadlockException DeadlockException} will be thrown.
289    */
290    public void setWait(final boolean wait) {
291        this.wait = wait;
292    }
293
294    /**
295    Return if the transaction is configured to wait if a lock
296    request cannot be immediately granted.
297    <p>
298    @return
299    If the transaction is configured to wait if a lock request
300    cannot be immediately granted.
301    */
302    public boolean getWait() {
303        return wait;
304    }
305
306    /**
307    Configure the transaction to write but not synchronously flush the log
308    it when commits.
309    <p>
310    This behavior may be set for a database environment using the
311    Environment.setMutableConfig method. Any value specified to this method
312    overrides that setting.
313    <p>
314    The default is false for this class and the database environment.
315    <p>
316    @param writeNoSync
317    If true, transactions exhibit the ACI (atomicity, consistency, and
318    isolation) properties, but not D (durability); that is, database
319    integrity will be maintained, but if the operating system
320    fails, it is possible some number of the most recently committed
321    transactions may be undone during recovery. The number of
322    transactions at risk is governed by how often the operating system
323    flushes dirty buffers to disk, and how often the log is
324    checkpointed.
325    */
326    public void setWriteNoSync(final boolean writeNoSync) {
327        this.writeNoSync = writeNoSync;
328    }
329
330    /**
331    Return if the transaction is configured to write but not synchronously
332    flush the log it when commits.
333    <p>
334    @return
335    If the transaction is configured to not write or synchronously flush
336    the log it when commits.
337    */
338    public boolean getWriteNoSync() {
339        return writeNoSync;
340    }
341
342    DbTxn beginTransaction(final DbEnv dbenv, final DbTxn parent)
343        throws DatabaseException {
344
345        int flags = 0;
346        flags |= readCommitted ? DbConstants.DB_READ_COMMITTED : 0;
347        flags |= readUncommitted ? DbConstants.DB_READ_UNCOMMITTED : 0;
348        flags |= noSync ? DbConstants.DB_TXN_NOSYNC : 0;
349        flags |= noWait ? DbConstants.DB_TXN_NOWAIT : 0;
350        flags |= snapshot ? DbConstants.DB_TXN_SNAPSHOT : 0;
351        flags |= sync ? DbConstants.DB_TXN_SYNC : 0;
352        flags |= wait ? DbConstants.DB_TXN_WAIT : 0;
353        flags |= writeNoSync ? DbConstants.DB_TXN_WRITE_NOSYNC : 0;
354
355        return dbenv.txn_begin(parent, flags);
356    }
357}
358