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</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="usingtxns.html" title="Chapter 3. Transaction Basics" />
11    <link rel="previous" href="nestedtxn.html" title="Nested Transactions" />
12    <link rel="next" href="txnindices.html" title="Secondary Indices with Transaction Applications" />
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</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="nestedtxn.html">Prev</a> </td>
22          <th width="60%" align="center">Chapter 3. Transaction Basics</th>
23          <td width="20%" align="right"> <a accesskey="n" href="txnindices.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="txncursor"></a>Transactional Cursors</h2>
33          </div>
34        </div>
35        <div></div>
36      </div>
37      <p>
38            You can transaction-protect your cursor operations by
39            specifying a transaction handle at the time that you create
40            your cursor.  Beyond that, you do not ever
41            provide a transaction handle directly to a cursor method.
42        </p>
43      <p>
44            Note that if you transaction-protect a cursor, then you must
45            make sure that the cursor is closed before you either commit or
46            abort the transaction. For example:
47        </p>
48      <pre class="programlisting">package db.txn;
49
50import com.sleepycat.db.Cursor;
51import com.sleepycat.db.Database;
52import com.sleepycat.db.DatabaseConfig;
53import com.sleepycat.db.DatabaseEntry;
54import com.sleepycat.db.DatabaseException;
55import com.sleepycat.db.Environment;
56import com.sleepycat.db.EnvironmentConfig;
57import com.sleepycat.db.LockMode;
58import com.sleepycat.db.OperationStatus;
59import com.sleepycat.db.Transaction;
60
61import java.io.File;
62import java.io.FileNotFoundException;
63
64...
65
66Database myDatabase = null;
67Environment myEnv = null;
68try {
69
70    // Database and environment opens omitted
71
72    String replacementData = "new data";
73
74    Transaction txn = myEnv.beginTransaction(null, null);
75    Cursor cursor = null;
76    try {
77        // Use the transaction handle here
78        cursor = db.openCursor(txn, null);
79        DatabaseEntry key, data;
80        
81        DatabaseEntry key, data;
82        while(cursor.getNext(key, data, LockMode.DEFAULT) ==
83           OperationStatus.SUCCESS) {
84            
85            data.setData(replacementData.getBytes("UTF-8"));
86            // No transaction handle is used on the cursor read or write
87            // methods.
88            cursor.putCurrent(data);
89        }
90        
91        cursor.close();
92        cursor = null;
93        txn.commit();
94        txn = null;
95    } catch (Exception e) {
96        if (cursor != null) {
97            cursor.close();
98        }
99        if (txn != null) {
100            txn.abort();
101            txn = null;
102        }
103    }
104
105} catch (DatabaseException de) {
106    // Exception handling goes here
107} </pre>
108      <div class="sect2" lang="en" xml:lang="en">
109        <div class="titlepage">
110          <div>
111            <div>
112              <h3 class="title"><a id="dplcursors"></a>Using Transactional DPL Cursors</h3>
113            </div>
114          </div>
115          <div></div>
116        </div>
117        <p>
118            When using the DPL, you create the cursor using the entity
119            class's primary or secondary index (see the
120            
121            <i class="citetitle">Getting Started with Berkeley DB for Java</i>
122            guide for details). At the time that you create the cursor, you
123            pass a transaction handle to the <tt class="methodname">entities()</tt>
124            method, and this causes all subsequent operations performed
125            using that cursor to be performed within the scope of the
126            transaction.
127        </p>
128        <p>
129                Note that if you are using a transaction-enabled store,
130                then you must provide a transaction handle when you open
131                your cursor.
132        </p>
133        <p>
134                For example:
135        </p>
136        <pre class="programlisting">package persist.txn;
137
138import com.sleepycat.db.DatabaseException;
139import com.sleepycat.db.Environment;
140import com.sleepycat.db.EnvironmentConfig;
141import com.sleepycat.db.Transaction;
142
143import com.sleepycat.persist.EntityCursor;
144import com.sleepycat.persist.EntityStore;
145import com.sleepycat.persist.PrimaryIndex;
146
147import java.io.File;
148import java.io.FileNotFoundException;
149
150...
151
152Environment myEnv = null;
153EntityStore store = null;
154
155...
156
157
158    // Store and environment open omitted, as is the DataAccessor
159    // instantiation.
160
161...
162
163    Transaction txn = myEnv.beginTransaction(null, null);
164    PrimaryIndex&lt;String,Inventory&gt; pi =
165        store.getPrimaryIndex(String.class, Inventory.class);
166    EntityCursor&lt;Inventory&gt; pi_cursor = pi.entities(txn, null);
167
168    try {
169        for (Inventory ii : pi_cursor) {
170            // do something with each object "ii"
171            // A transactional handle is not required for any write operations.
172            // All operations performed using this cursor will be done within
173            // the scope of the transaction, txn.
174        }
175        pi_cursor.close();
176        pi_cursor = null;
177        txn.commit();
178        txn = null;
179    // Always make sure the cursor is closed when we are done with it.
180    } catch (Exception e) {
181        if (pi_cursor != null) {
182            pi_cursor.close();
183        }
184        if (txn != null) {
185            txn.abort();
186            txn = null;
187        }
188    } </pre>
189      </div>
190    </div>
191    <div class="navfooter">
192      <hr />
193      <table width="100%" summary="Navigation footer">
194        <tr>
195          <td width="40%" align="left"><a accesskey="p" href="nestedtxn.html">Prev</a> </td>
196          <td width="20%" align="center">
197            <a accesskey="u" href="usingtxns.html">Up</a>
198          </td>
199          <td width="40%" align="right"> <a accesskey="n" href="txnindices.html">Next</a></td>
200        </tr>
201        <tr>
202          <td width="40%" align="left" valign="top">Nested Transactions </td>
203          <td width="20%" align="center">
204            <a accesskey="h" href="index.html">Home</a>
205          </td>
206          <td width="40%" align="right" valign="top"> Secondary Indices with Transaction Applications</td>
207        </tr>
208      </table>
209    </div>
210  </body>
211</html>
212