1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2002-2009 Oracle. All rights reserved. 5 * 6 * $Id$ 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 specify the database cursor will be used to make 29 bulk changes to the underlying database. 30 */ 31 public static final CursorConfig BULK_CURSOR = new CursorConfig(); 32 static { BULK_CURSOR.setBulkCursor(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 configure read operations performed by the 46 cursor to return modified but not yet committed data. 47 */ 48 public static final CursorConfig READ_UNCOMMITTED = new CursorConfig(); 49 static { READ_UNCOMMITTED.setReadUncommitted(true); } 50 51 /** 52 A convenience instance to configure read operations performed by the 53 cursor to return values as they were when the cursor was opened, if 54 {@link DatabaseConfig#setMultiversion} is configured. 55 */ 56 public static final CursorConfig SNAPSHOT = new CursorConfig(); 57 static { SNAPSHOT.setSnapshot(true); } 58 59 /** 60 A convenience instance to specify the Concurrent Data Store environment 61 cursor will be used to update the database. 62 <p> 63 The underlying Berkeley DB database environment must have been 64 configured as a Concurrent Data Store environment. 65 */ 66 public static final CursorConfig WRITECURSOR = new CursorConfig(); 67 static { WRITECURSOR.setWriteCursor(true); } 68 69 /** 70 A convenience instance to configure read operations performed by the 71 cursor to return modified but not yet committed data. 72 <p> 73 @deprecated This has been replaced by {@link #READ_UNCOMMITTED} to conform to ANSI 74 database isolation terminology. 75 */ 76 public static final CursorConfig DIRTY_READ = READ_UNCOMMITTED; 77 78 /** 79 A convenience instance to configure a cursor for read committed isolation. 80 <p> 81 This ensures the stability of the current data item read by the 82 cursor but permits data read by this cursor to be modified or 83 deleted prior to the commit of the transaction. 84 <p> 85 @deprecated This has been replaced by {@link #READ_COMMITTED} to conform to ANSI database isolation terminology. 86 */ 87 public static final CursorConfig DEGREE_2 = READ_COMMITTED; 88 89 private boolean bulkCursor = false; 90 private boolean readCommitted = false; 91 private boolean readUncommitted = false; 92 private boolean snapshot = false; 93 private boolean writeCursor = false; 94 95 /** 96 An instance created using the default constructor is initialized with 97 the system's default settings. 98 */ 99 public CursorConfig() { 100 } 101 102 /* package */ 103 static CursorConfig checkNull(CursorConfig config) { 104 return (config == null) ? DEFAULT : config; 105 } 106 107 /** 108 Specify that the cursor will be used to do bulk operations on the 109 underlying database. 110 <p> 111 @param bulkCursor 112 If true, specify the cursor will be used to do bulk operations on the 113 underlying database. 114 */ 115 public void setBulkCursor(final boolean bulkCursor) { 116 this.bulkCursor = bulkCursor; 117 } 118 119 /** 120 Return if the cursor will be used to do bulk operations on the underlying 121 database. 122 <p> 123 @return 124 If the cursor will be used to do bulk operations on the 125 underlying database. 126 */ 127 public boolean getBulkCursor() { 128 return bulkCursor; 129 } 130 131 /** 132 Configure the cursor for read committed isolation. 133 <p> 134 This ensures the stability of the current data item read by the 135 cursor but permits data read by this cursor to be modified or 136 deleted prior to the commit of the transaction. 137 <p> 138 @param readCommitted 139 If true, configure the cursor for read committed isolation. 140 */ 141 public void setReadCommitted(final boolean readCommitted) { 142 this.readCommitted = readCommitted; 143 } 144 145 /** 146 Return if the cursor is configured for read committed isolation. 147 <p> 148 @return 149 If the cursor is configured for read committed isolation. 150 */ 151 public boolean getReadCommitted() { 152 return readCommitted; 153 } 154 155 /** 156 Configure the cursor for read committed isolation. 157 <p> 158 This ensures the stability of the current data item read by the 159 cursor but permits data read by this cursor to be modified or 160 deleted prior to the commit of the transaction. 161 <p> 162 @param degree2 163 If true, configure the cursor for read committed isolation. 164 <p> 165 @deprecated This has been replaced by {@link #setReadCommitted} to conform to ANSI 166 database isolation terminology. 167 */ 168 public void setDegree2(final boolean degree2) { 169 setReadCommitted(degree2); 170 } 171 172 /** 173 Return if the cursor is configured for read committed isolation. 174 <p> 175 @return 176 If the cursor is configured for read committed isolation. 177 <p> 178 @deprecated This has been replaced by {@link #getReadCommitted} to conform to ANSI 179 database isolation terminology. 180 */ 181 public boolean getDegree2() { 182 return getReadCommitted(); 183 } 184 185 /** 186 Configure read operations performed by the cursor to return modified 187 but not yet committed data. 188 <p> 189 @param readUncommitted 190 If true, configure read operations performed by the cursor to return 191 modified but not yet committed data. 192 */ 193 public void setReadUncommitted(final boolean readUncommitted) { 194 this.readUncommitted = readUncommitted; 195 } 196 197 /** 198 Return if read operations performed by the cursor are configured to 199 return modified but not yet committed data. 200 <p> 201 @return 202 If read operations performed by the cursor are configured to return 203 modified but not yet committed data. 204 */ 205 public boolean getReadUncommitted() { 206 return readUncommitted; 207 } 208 209 /** 210 Configure read operations performed by the cursor to return modified 211 but not yet committed data. 212 <p> 213 @param dirtyRead 214 If true, configure read operations performed by the cursor to return 215 modified but not yet committed data. 216 <p> 217 @deprecated This has been replaced by {@link #setReadUncommitted} to 218 conform to ANSI database isolation terminology. 219 */ 220 public void setDirtyRead(final boolean dirtyRead) { 221 setReadUncommitted(dirtyRead); 222 } 223 224 /** 225 Return if read operations performed by the cursor are configured to return 226 modified but not yet committed data. 227 <p> 228 @return 229 If read operations performed by the cursor are configured to return 230 modified but not yet committed data. 231 <p> 232 @deprecated This has been replaced by {@link #getReadUncommitted} to 233 conform to ANSI database isolation terminology. 234 */ 235 public boolean getDirtyRead() { 236 return getReadUncommitted(); 237 } 238 239 /** 240 Configure read operations performed by the cursor to return data as it was 241 when the cursor opened without locking, if {@link 242 DatabaseConfig#setMultiversion} was configured. 243 <p> 244 @param snapshot 245 If true, configure read operations performed by the cursor to return 246 data as it was when the cursor was opened, without locking. 247 */ 248 public void setSnapshot(final boolean snapshot) { 249 this.snapshot = snapshot; 250 } 251 252 /** 253 Return if read operations performed by the cursor are configured to return 254 data as it was when the cursor was opened, without locking. 255 <p> 256 @return 257 If read operations performed by the cursor are configured to return 258 data as it was when the cursor was opened. 259 */ 260 public boolean getSnapshot() { 261 return snapshot; 262 } 263 264 /** 265 Specify the Concurrent Data Store environment cursor will be used to 266 update the database. 267 <p> 268 @param writeCursor 269 If true, specify the Concurrent Data Store environment cursor will be 270 used to update the database. 271 */ 272 public void setWriteCursor(final boolean writeCursor) { 273 this.writeCursor = writeCursor; 274 } 275 276 /** 277 Return if the Concurrent Data Store environment cursor will be used to 278 update the database. 279 <p> 280 @return 281 If the Concurrent Data Store environment cursor will be used to update 282 the database. 283 */ 284 public boolean getWriteCursor() { 285 return writeCursor; 286 } 287 288 /* package */ 289 Dbc openCursor(final Db db, final DbTxn txn) 290 throws DatabaseException { 291 292 int flags = 0; 293 flags |= bulkCursor ? DbConstants.DB_CURSOR_BULK : 0; 294 flags |= readCommitted ? DbConstants.DB_READ_COMMITTED : 0; 295 flags |= readUncommitted ? DbConstants.DB_READ_UNCOMMITTED : 0; 296 flags |= snapshot ? DbConstants.DB_TXN_SNAPSHOT : 0; 297 flags |= writeCursor ? DbConstants.DB_WRITECURSOR : 0; 298 return db.cursor(txn, flags); 299 } 300} 301