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>Secondary Indices with Transaction Applications</title>
7    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
8    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
9    <link rel="start" 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="prev" href="txncursor.html" title="Transactional Cursors" />
12    <link rel="next" href="maxtxns.html" title="Configuring the Transaction Subsystem" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Secondary Indices with Transaction Applications</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="txncursor.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="maxtxns.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="txnindices"></a>Secondary Indices with Transaction Applications</h2>
33          </div>
34        </div>
35      </div>
36      <p>
37            You can use transactions with your secondary indices so long as you
38
39            
40
41            <span>
42                open the secondary index so that it is transactional. 
43            </span>
44                
45            
46        </p>
47      <p>
48            All other aspects of using secondary indices with transactions are
49            identical to using secondary indices without transactions. In
50            addition, transaction-protecting 
51                
52                <span>
53                    secondary cursors is performed just as you protect normal
54                    cursors — you simply have to make sure the cursor is
55                    opened using a transaction handle, and that the cursor is
56                    closed before the handle is either either committed or
57                    aborted.
58                </span>
59                    See <a class="xref" href="txncursor.html" title="Transactional Cursors">Transactional Cursors</a> for details.
60        </p>
61      <p>
62            Note that when you use transactions to protect your database writes, your secondary indices are protected from
63            corruption because updates to the primary and the secondaries are performed in a single atomic transaction.
64        </p>
65      <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
66        <h3 class="title">Note</h3>
67        <p>
68                            If you are using the DPL, then be aware that
69                            you never have to provide a transactional
70                            handle when opening an index, be it a primary
71                            or a secondary. However, transactions are
72                            enabled for your store, then all of the indexes
73                            that you open will be enabled for transactional
74                            usage. More, any write operation performed
75                            using that index will be done using a
76                            transaction, regardless of whether you
77                            explictly provide a transactional handle to the
78                            write operation.
79                    </p>
80        <p>
81                            If you do not explictly provide a transaction
82                            handle to DPL write operations performed on a
83                            transactional store, then auto commit is
84                            silently used for that operation.
85                    </p>
86      </div>
87      <p>
88            For example:
89        </p>
90      <pre class="programlisting">package db.GettingStarted;
91
92import com.sleepycat.bind.tuple.TupleBinding;
93import com.sleepycat.db.Database;
94import com.sleepycat.db.DatabaseType;
95import com.sleepycat.db.DatabaseConfig;
96import com.sleepycat.db.DatabaseException;
97import com.sleepycat.db.Environment;
98import com.sleepycat.db.EnvironmentConfig;
99import com.sleepycat.db.SecondaryDatabase;
100import com.sleepycat.db.SecondaryConfig;
101
102import java.io.FileNotFoundException;
103
104...
105
106// Environment and primary database opens omitted.
107
108SecondaryConfig mySecConfig = new SecondaryConfig();
109mySecConfig.setAllowCreate(true);
110mySecConfig.setType(DatabaseType.BTREE);
111mySecConfig.setTransactional(true);
112
113SecondaryDatabase mySecDb = null;
114try {
115    // A fake tuple binding that is not actually implemented anywhere.
116    // The tuple binding is dependent on the data in use.
117    // See the Getting Started Guide for details
118    TupleBinding myTupleBinding = new MyTupleBinding();
119
120    // Open the secondary. FullNameKeyCreator is not actually implemented
121    // anywhere. See the Getting Started Guide for details.
122    FullNameKeyCreator keyCreator = new FullNameKeyCreator(myTupleBinding);
123
124    // Set the key creator on the secondary config object.
125    mySecConfig.setKeyCreator(keyCreator);
126
127    // Perform the actual open. Because this database is configured to be
128    // transactional, the open is automatically wrapped in a transaction.
129    //      - myEnv is the environment handle.
130    //      - myDb is the primary database handle.
131    String secDbName = "mySecondaryDatabase";
132    mySecDb = myEnv.openSecondary(null, secDbName, null, myDb, mySecConfig);
133} catch (DatabaseException de) {
134    // Exception handling goes here ...
135} catch (FileNotFoundException fnfe) {
136    // Exception handling goes here ...
137}</pre>
138    </div>
139    <div class="navfooter">
140      <hr />
141      <table width="100%" summary="Navigation footer">
142        <tr>
143          <td width="40%" align="left"><a accesskey="p" href="txncursor.html">Prev</a> </td>
144          <td width="20%" align="center">
145            <a accesskey="u" href="usingtxns.html">Up</a>
146          </td>
147          <td width="40%" align="right"> <a accesskey="n" href="maxtxns.html">Next</a></td>
148        </tr>
149        <tr>
150          <td width="40%" align="left" valign="top">Transactional Cursors </td>
151          <td width="20%" align="center">
152            <a accesskey="h" href="index.html">Home</a>
153          </td>
154          <td width="40%" align="right" valign="top"> Configuring the Transaction Subsystem</td>
155        </tr>
156      </table>
157    </div>
158  </body>
159</html>
160