1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml">
4  <head>
5    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6    <title>Transactional Cursors and Concurrent Applications</title>
7    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
8    <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
9    <link rel="home" href="index.html" title="Getting Started with Berkeley DB Transaction Processing" />
10    <link rel="up" href="txnconcurrency.html" title="Chapter��4.��Concurrency" />
11    <link rel="previous" href="isolation.html" title="Isolation" />
12    <link rel="next" href="readmodifywrite.html" title="Read/Modify/Write" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Transactional Cursors and Concurrent Applications</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="isolation.html">Prev</a>��</td>
22          <th width="60%" align="center">Chapter��4.��Concurrency</th>
23          <td width="20%" align="right">��<a accesskey="n" href="readmodifywrite.html">Next</a></td>
24        </tr>
25      </table>
26      <hr />
27    </div>
28    <div class="sect1" lang="en" xml:lang="en">
29      <div class="titlepage">
30        <div>
31          <div>
32            <h2 class="title" style="clear: both"><a id="txn_ccursor"></a>Transactional Cursors and Concurrent Applications</h2>
33          </div>
34        </div>
35        <div></div>
36      </div>
37      <p>
38            When you use transactional cursors with a concurrent application, remember that 
39            in the event of a deadlock you must make sure that you close your cursor before you abort and retry your
40            transaction. <span>This is true of both
41                    base API and DPL cursors.</span>
42         </p>
43      <p>
44            Also, remember that when you are using the default isolation level, 
45            every time your cursor reads a record it locks
46            that record until the encompassing transaction is resolved. This
47            means that walking your database with a transactional cursor
48            increases the chance of lock contention. 
49          </p>
50      <p>
51                For this reason, if you must routinely walk your database with a
52                transactional cursor, consider using a reduced isolation level
53                such as read committed. <span>This is
54                        true of both base API and DPL cursors.</span>
55          </p>
56      <div class="sect2" lang="en" xml:lang="en">
57        <div class="titlepage">
58          <div>
59            <div>
60              <h3 class="title"><a id="cursordirtyreads"></a>Using Cursors with Uncommitted Data</h3>
61            </div>
62          </div>
63          <div></div>
64        </div>
65        <p>
66
67                As described in <a href="isolation.html#dirtyreads">Reading Uncommitted Data</a> 
68                above, it is possible to relax your transaction's isolation
69                level such that it can read data modified but not yet committed
70                by another transaction. You can configure this when you create
71                your transaction handle, and when you do so then all cursors opened
72                inside that transaction will automatically use uncommitted reads. 
73            </p>
74        <p>
75                You can also do this when you create a cursor handle from within 
76                a serializable transaction.  When you do this, only those 
77                cursors configured for uncommitted reads uses uncommitted reads.
78            </p>
79        <p>
80                    Either way, you must first configure your database
81                    <span>or store</span> handle to support
82                uncommitted reads before you can configure your transactions or
83                your cursors to use them.
84            </p>
85        <p>
86                The following example shows how to configure an individual cursor handle 
87                to read uncommitted data from within a serializable (full isolation) transaction. 
88                For an example of
89                configuring a transaction to perform uncommitted reads in
90                general, see <a href="isolation.html#dirtyreads">Reading Uncommitted Data</a>.
91            </p>
92        <pre class="programlisting">package db.txn;
93
94import com.sleepycat.db.Cursor;
95import com.sleepycat.db.CursorConfig;
96import com.sleepycat.db.Database;
97import com.sleepycat.db.DatabaseConfig;
98import com.sleepycat.db.Environment;
99import com.sleepycat.db.EnvironmentConfig;
100
101import java.io.File;
102
103...
104
105Database myDatabase = null;
106Environment myEnv = null;
107try {
108
109    EnvironmentConfig myEnvConfig = new EnvironmentConfig();
110    myEnvConfig.setTransactional(true);
111    myEnvConfig.setInitializeCache(true);
112    myEnvConfig.setInitializeLocking(true);
113    myEnvConfig.setInitializeLogging(true);
114
115    myEnv = new Environment(new File("/my/env/home"),
116                              myEnvConfig);
117
118    // Open the database.
119    DatabaseConfig dbConfig = new DatabaseConfig();
120    dbConfig.setTransactional(true);
121    dbConfig.setType(DatabaseType.BTREE);
122    dbConfig.setReadUncommitted(true);      // Enable uncommitted reads.
123    myDatabase = myEnv.openDatabase(null,              // txn handle
124                                    "sampleDatabase",  // db file name
125                                    null,              // db name
126                                    dbConfig);
127
128    // Open the transaction. Note that this is a degree 3
129    // transaction.
130    Transaction txn = myEnv.beginTransaction(null, null);
131    Cursor cursor = null;
132    try {
133        // Use the transaction handle here
134        // Get our cursor. Note that we pass the transaction 
135        // handle here. Note also that we cause the cursor 
136        // to perform uncommitted reads.
137        CursorConfig cconfig = new CursorConfig();
138        cconfig.setReadUncommitted(true);
139        cursor = db.openCursor(txn, cconfig);
140
141        // From here, you perform your cursor reads and writes 
142        // as normal, committing and aborting the transactions as 
143        // is necessary, and testing for deadlock exceptions as 
144        // normal (omitted for brevity). 
145        
146        ... </pre>
147        <p>
148        If you are using the DPL:
149</p>
150        <pre class="programlisting">package persist.txn;
151
152import com.sleepycat.db.CursorConfig;
153import com.sleepycat.db.DatabaseConfig;
154import com.sleepycat.db.Environment;
155import com.sleepycat.db.EnvironmentConfig;
156
157import com.sleepycat.persist.EntityCursor;
158import com.sleepycat.persist.EntityStore;
159import com.sleepycat.persist.PrimaryIndex;
160import com.sleepycat.persist.StoreConfig;
161
162import java.util.Iterator;
163
164import java.io.File;
165
166...
167
168EntityStore myStore = null;
169Environment myEnv = null;
170PrimaryIndex&lt;String,AnEntityClass&gt; pKey;
171
172try {
173
174    EnvironmentConfig myEnvConfig = new EnvironmentConfig();
175    myEnvConfig.setTransactional(true);
176    myEnvConfig.setInitializeCache(true);
177    myEnvConfig.setInitializeLocking(true);
178    myEnvConfig.setInitializeLogging(true);
179
180    myEnv = new Environment(new File("/my/env/home"),
181                              myEnvConfig);
182
183    // Set up the entity store
184    StoreConfig myStoreConfig = new StoreConfig();
185    myStoreConfig.setAllowCreate(true);
186    myStoreConfig.setTransactional(true);
187
188    // Configure uncommitted reads
189    DatabaseConfig dbConfig = new DatabaseConfig();
190    dbConfig.setTransactional(true);
191    dbConfig.setType(DatabaseType.BTREE);
192    dbConfig.setAllowCreate(true);
193    dbConfig.setReadUncommitted(true);      // Enable uncommitted reads.
194
195    // Instantiate the store
196    myStore = new EntityStore(myEnv, storeName, myStoreConfig);
197
198    // Set the DatabaseConfig object, so that the underlying
199    // database is configured for uncommitted reads.
200    myStore.setPrimaryConfig(AnEntityClass.class, myDbConfig);
201
202    // Open the transaction. Note that this is a degree 3
203    // transaction.
204    Transaction txn = myEnv.beginTransaction(null, null);
205
206    //Configure our cursor for uncommitted reads.
207    CursorConfig cconfig = new CursorConfig();
208    cconfig.setReadUncommitted(true);
209
210    // Get our cursor. Note that we pass the transaction 
211    // handle here. Note also that we cause the cursor 
212    // to perform uncommitted reads.
213    EntityCursor&lt;AnEntityClass&gt; cursor = pKey.entities(txn, cconfig);
214
215    try {
216        // From here, you perform your cursor reads and writes 
217        // as normal, committing and aborting the transactions as 
218        // is necessary, and testing for deadlock exceptions as 
219        // normal (omitted for brevity). 
220        
221        ... </pre>
222      </div>
223    </div>
224    <div class="navfooter">
225      <hr />
226      <table width="100%" summary="Navigation footer">
227        <tr>
228          <td width="40%" align="left"><a accesskey="p" href="isolation.html">Prev</a>��</td>
229          <td width="20%" align="center">
230            <a accesskey="u" href="txnconcurrency.html">Up</a>
231          </td>
232          <td width="40%" align="right">��<a accesskey="n" href="readmodifywrite.html">Next</a></td>
233        </tr>
234        <tr>
235          <td width="40%" align="left" valign="top">Isolation��</td>
236          <td width="20%" align="center">
237            <a accesskey="h" href="index.html">Home</a>
238          </td>
239          <td width="40%" align="right" valign="top">��Read/Modify/Write</td>
240        </tr>
241      </table>
242    </div>
243  </body>
244</html>
245