lang/java/src/com/sleepycat/db/TransactionConfig.java

   1 /*-
   2  * See the file LICENSE for redistribution information.
   3  *
   4  * Copyright (c) 2002, 2012 Oracle and/or its affiliates.  All rights reserved.
   5  *
   6  * $Id$
   7  */
   8
   9 package com.sleepycat.db;
  10
  11 import com.sleepycat.db.internal.DbConstants;
  12 import com.sleepycat.db.internal.DbEnv;
  13 import com.sleepycat.db.internal.DbTxn;
  14
  15 /**
  16 Specifies the attributes of a database environment transaction.
  17 */
  18 public 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 bulk = false;
  35     private boolean readUncommitted = false;
  36     private boolean readCommitted = false;
  37     private boolean noSync = false;
  38     private boolean noWait = false;
  39     private boolean snapshot = false;
  40     private boolean sync = false;
  41     private boolean writeNoSync = false;
  42     private boolean wait = false;
  43
  44     /**
  45     An instance created using the default constructor is initialized
  46     with the system's default settings.
  47     */
  48     public TransactionConfig() {
  49     }
  50
  51     /**
  52         Configure the transaction for read committed isolation.
  53     <p>
  54     This ensures the stability of the current data item read by the
  55     cursor but permits data read by this transaction to be modified or
  56     deleted prior to the commit of the transaction.
  57     <p>
  58     @param readCommitted
  59     If true, configure the transaction for read committed isolation.
  60     */
  61     public void setReadCommitted(final boolean readCommitted) {
  62         this.readCommitted = readCommitted;
  63     }
  64
  65     /**
  66         Return if the transaction is configured for read committed isolation.
  67     <p>
  68     @return
  69     If the transaction is configured for read committed isolation.
  70     */
  71     public boolean getReadCommitted() {
  72         return readCommitted;
  73     }
  74
  75     /**
  76         Configure the transaction for read committed isolation.
  77     <p>
  78     This ensures the stability of the current data item read by the
  79     cursor but permits data read by this transaction to be modified or
  80     deleted prior to the commit of the transaction.
  81     <p>
  82     @param degree2
  83     If true, configure the transaction for read committed isolation.
  84         <p>
  85     @deprecated This has been replaced by {@link #setReadCommitted} to conform to ANSI
  86     database isolation terminology.
  87     */
  88     public void setDegree2(final boolean degree2) {
  89         setReadCommitted(degree2);
  90     }
  91
  92     /**
  93         Return if the transaction is configured for read committed isolation.
  94     <p>
  95     @return
  96     If the transaction is configured for read committed isolation.
  97         <p>
  98     @deprecated This has been replaced by {@link #getReadCommitted} to conform to ANSI
  99     database isolation terminology.
 100     */
 101     public boolean getDegree2() {
 102         return getReadCommitted();
 103     }
 104
 105     /**
 106         Configure read operations performed by the transaction to return modified
 107     but not yet committed data.
 108     <p>
 109     @param readUncommitted
 110     If true, configure read operations performed by the transaction to return
 111     modified but not yet committed data.
 112     */
 113     public void setReadUncommitted(final boolean readUncommitted) {
 114         this.readUncommitted = readUncommitted;
 115     }
 116
 117     /**
 118         Return if read operations performed by the transaction are configured to
 119     return modified but not yet committed data.
 120     <p>
 121     @return
 122     If read operations performed by the transaction are configured to return
 123     modified but not yet committed data.
 124     */
 125     public boolean getReadUncommitted() {
 126         return readUncommitted;
 127     }
 128
 129     /**
 130         Configure read operations performed by the transaction to return modified
 131     but not yet committed data.
 132     <p>
 133     @param dirtyRead
 134     If true, configure read operations performed by the transaction to return
 135     modified but not yet committed data.
 136         <p>
 137     @deprecated This has been replaced by {@link #setReadUncommitted} to conform to ANSI
 138     database isolation terminology.
 139     */
 140     public void setDirtyRead(final boolean dirtyRead) {
 141         setReadUncommitted(dirtyRead);
 142     }
 143
 144     /**
 145         Return if read operations performed by the transaction are configured to
 146     return modified but not yet committed data.
 147     <p>
 148     @return
 149     If read operations performed by the transaction are configured to return
 150     modified but not yet committed data.
 151         <p>
 152     @deprecated This has been replaced by {@link #getReadUncommitted} to conform to ANSI
 153     database isolation terminology.
 154     */
 155     public boolean getDirtyRead() {
 156         return getReadUncommitted();
 157     }
 158
 159     /**
 160     Configure the transaction to not write or synchronously flush the log
 161     it when commits.
 162     <p>
 163     This behavior may be set for a database environment using the
 164     Environment.setMutableConfig method. Any value specified to this method
 165     overrides that setting.
 166     <p>
 167     The default is false for this class and the database environment.
 168     <p>
 169     @param noSync
 170     If true, transactions exhibit the ACI (atomicity, consistency, and
 171     isolation) properties, but not D (durability); that is, database
 172     integrity will be maintained, but if the application or system
 173     fails, it is possible some number of the most recently committed
 174     transactions may be undone during recovery. The number of
 175     transactions at risk is governed by how many log updates can fit
 176     into the log buffer, how often the operating system flushes dirty
 177     buffers to disk, and how often the log is checkpointed.
 178     */
 179     public void setNoSync(final boolean noSync) {
 180         this.noSync = noSync;
 181     }
 182
 183     /**
 184     Return if the transaction is configured to not write or synchronously
 185     flush the log it when commits.
 186     <p>
 187     @return
 188     If the transaction is configured to not write or synchronously flush
 189     the log it when commits.
 190     */
 191     public boolean getNoSync() {
 192         return noSync;
 193     }
 194
 195     /**
 196     Configure the transaction to not wait if a lock request cannot be
 197     immediately granted.
 198     <p>
 199     The default is false for this class and the database environment.
 200     <p>
 201     @param noWait
 202     If true, transactions will not wait if a lock request cannot be
 203     immediately granted, instead {@link com.sleepycat.db.DeadlockException DeadlockException} will be thrown.
 204     */
 205     public void setNoWait(final boolean noWait) {
 206         this.noWait = noWait;
 207     }
 208
 209     /**
 210     Return if the transaction is configured to not wait if a lock
 211     request cannot be immediately granted.
 212     <p>
 213     @return
 214     If the transaction is configured to not wait if a lock request
 215     cannot be immediately granted.
 216     */
 217     public boolean getNoWait() {
 218         return noWait;
 219     }
 220
 221     /**
 222     This transaction will execute with snapshot isolation.  For databases
 223     configured with {@link DatabaseConfig#setMultiversion}, data values
 224     will be read as they are when the transaction begins, without taking
 225     read locks.
 226     <p>
 227     Updates operations performed in the transaction will cause a
 228     {@link DeadlockException} to be thrown if data is modified
 229     between reading and writing it.
 230     */
 231     public void setSnapshot(final boolean snapshot) {
 232         this.snapshot = snapshot;
 233     }
 234
 235     /**
 236 Return true if the transaction is configured for Snapshot Isolation.
 237 <p>
 238 This method may be called at any time during the life of the application.
 239 <p>
 240 @return
 241 True if the transaction is configured for Snapshot Isolation.
 242     */
 243     public boolean getSnapshot() {
 244         return snapshot;
 245     }
 246
 247     /**
 248     Configure the transaction to write and synchronously flush the log
 249     it when commits.
 250     <p>
 251     This behavior may be set for a database environment using the
 252     Environment.setMutableConfig method. Any value specified to this
 253     method overrides that setting.
 254     <p>
 255     The default is false for this class and true for the database
 256     environment.
 257     <p>
 258     If true is passed to both setSync and setNoSync, setSync will take
 259     precedence.
 260     <p>
 261     @param sync
 262     If true, transactions exhibit all the ACID (atomicity, consistency,
 263     isolation, and durability) properties.
 264     */
 265     public void setSync(final boolean sync) {
 266         this.sync = sync;
 267     }
 268
 269     /**
 270     Return if the transaction is configured to write and synchronously
 271     flush the log it when commits.
 272     <p>
 273     @return
 274     If the transaction is configured to write and synchronously flush
 275     the log it when commits.
 276     */
 277     public boolean getSync() {
 278         return sync;
 279     }
 280
 281     /**
 282     Configure the transaction to wait if a lock request cannot be
 283     immediately granted.
 284     <p>
 285     The default is true unless {@link EnvironmentConfig#setTxnNoWait} is called.
 286     <p>
 287     @param wait
 288     If true, transactions will wait if a lock request cannot be
 289     immediately granted, instead {@link com.sleepycat.db.DeadlockException DeadlockException} will be thrown.
 290     */
 291     public void setWait(final boolean wait) {
 292         this.wait = wait;
 293     }
 294
 295     /**
 296     Return if the transaction is configured to wait if a lock
 297     request cannot be immediately granted.
 298     <p>
 299     @return
 300     If the transaction is configured to wait if a lock request
 301     cannot be immediately granted.
 302     */
 303     public boolean getWait() {
 304         return wait;
 305     }
 306
 307     /**
 308     Configure the transaction to write but not synchronously flush the log
 309     it when commits.
 310     <p>
 311     This behavior may be set for a database environment using the
 312     Environment.setMutableConfig method. Any value specified to this method
 313     overrides that setting.
 314     <p>
 315     The default is false for this class and the database environment.
 316     <p>
 317     @param writeNoSync
 318     If true, transactions exhibit the ACI (atomicity, consistency, and
 319     isolation) properties, but not D (durability); that is, database
 320     integrity will be maintained, but if the operating system
 321     fails, it is possible some number of the most recently committed
 322     transactions may be undone during recovery. The number of
 323     transactions at risk is governed by how often the operating system
 324     flushes dirty buffers to disk, and how often the log is
 325     checkpointed.
 326     */
 327     public void setWriteNoSync(final boolean writeNoSync) {
 328         this.writeNoSync = writeNoSync;
 329     }
 330
 331     /**
 332     Return if the transaction is configured to write but not synchronously
 333     flush the log it when commits.
 334     <p>
 335     @return
 336     If the transaction is configured to not write or synchronously flush
 337     the log it when commits.
 338     */
 339     public boolean getWriteNoSync() {
 340         return writeNoSync;
 341     }
 342
 343     /**
 344     Configures the transaction to enable the transactional bulk insert
 345     optimization.  When this attribute is set, the transaction will avoid
 346     logging the contents of insertions on newly allocated database pages.
 347     In a transaction that inserts a large number of new records, the I/O
 348     savings of choosing this option can be significant.  Users of this
 349     option should be aware of several issues.  When the optimization is in
 350     effect, page allocations that extend the database file are logged as
 351     usual; this allows transaction aborts to work correctly, both online
 352     and during recovery.  At commit time, the database's pages are flushed
 353     to disk, eliminating the need to roll-forward the transaction during
 354     normal recovery.  However, there are other recovery operations that
 355     depend on roll-forward, and care must be taken when Bulk-enabled
 356     transactions interact with them.  In particular, Bulk is
 357     incompatible with replication, and is simply ignored when replication
 358     is enabled.  Also, hot backup procedures must follow a particular
 359     protocol, introduced in 11gr2.5.1, to set a flag in the environment
 360     before starting to copy files.  It is especially important to note
 361     that incremental hot backups can be invalidated by use of the bulk
 362     insert optimization.  Please see the hot backup description in the
 363     <i>Getting Started with Transactions Guide</i>, and the description of the
 364     HotbackupInProgress attribute in
 365     {@link com.sleepycat.db.EnvironmentConfig EnvironmentConfig}
 366     for further information.
 367     <p>
 368     The bulk insert optimization is effective only for
 369     top-level transactions.
 370     <p>
 371     @param bulk
 372     If true, configure the transaction to enable the bulk optimization.
 373     */
 374     public void setBulk(final boolean bulk) {
 375         this.bulk = bulk;
 376     }
 377
 378     /**
 379     Return true if the Bulk attribute is set.
 380     <p>
 381     @return
 382     The current setting of the Bulk attribute.
 383     */
 384     public boolean getBulk() {
 385         return this.bulk;
 386     }
 387
 388     DbTxn beginTransaction(final DbEnv dbenv, final DbTxn parent)
 389         throws DatabaseException {
 390
 391         int flags = 0;
 392         flags |= readCommitted ? DbConstants.DB_READ_COMMITTED : 0;
 393         flags |= readUncommitted ? DbConstants.DB_READ_UNCOMMITTED : 0;
 394         flags |= noSync ? DbConstants.DB_TXN_NOSYNC : 0;
 395         flags |= noWait ? DbConstants.DB_TXN_NOWAIT : 0;
 396         flags |= snapshot ? DbConstants.DB_TXN_SNAPSHOT : 0;
 397         flags |= sync ? DbConstants.DB_TXN_SYNC : 0;
 398         flags |= wait ? DbConstants.DB_TXN_WAIT : 0;
 399         flags |= writeNoSync ? DbConstants.DB_TXN_WRITE_NOSYNC : 0;
 400         flags |= bulk ? DbConstants.DB_TXN_BULK : 0;
 401
 402         return dbenv.txn_begin(parent, flags);
 403     }
 404 }