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>Configuring the Transaction Subsystem</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="txnindices.html" title="Secondary Indices with Transaction Applications" />
12    <link rel="next" href="txnconcurrency.html" title="Chapter 4. Concurrency" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Configuring the Transaction Subsystem</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="txnindices.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="txnconcurrency.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="maxtxns"></a>Configuring the Transaction Subsystem</h2>
33          </div>
34        </div>
35      </div>
36      <p>
37            Most of the configuration activities that you need to perform
38            for your transactional DB application will involve the
39            locking and logging subsystems. See 
40            <a class="xref" href="txnconcurrency.html" title="Chapter 4. Concurrency">Concurrency</a>
41            and
42            <a class="xref" href="filemanagement.html" title="Chapter 5. Managing DB Files">Managing DB Files</a>
43            for details.
44        </p>
45      <p>
46            However, there are a couple of things that you can do to
47            configure your transaction subsystem directly. These things
48            are:
49        </p>
50      <div class="itemizedlist">
51        <ul type="disc">
52          <li>
53            <span>
54                <p>
55                    
56                    <span>
57                        Configure 
58                    </span>
59                        
60                    the maximum number of simultaneous
61                    transactions needed by your application. 
62                    In general, you should not need to do this unless you
63                    use deeply nested transactions or you have many threads all
64                    of which have active transactions. In addition, you may
65                    need to configure a higher maximum number of transactions if you
66                    are using snapshot isolation. See
67                    <a class="xref" href="isolation.html#sisolation_maxtxn" title="Snapshot Isolation Transactional Requirements">Snapshot Isolation Transactional Requirements</a>
68                    for details.
69                </p>
70                <p>
71                    By default, your application can support 20 active
72                    transactions. 
73                </p>
74                <p>
75                    You can set the maximum number of simultaneous
76                    transactions supported by your application using
77                    
78                    <span>
79                        <code class="methodname">EnvironmentConfig.setTxnMaxActive()</code>.
80                    </span>
81                </p>
82                <p>
83                    If your application has exceeded this maximum value,
84                    then any attempt to begin a new transaction will fail.
85                </p>
86                <p>
87                    This value can also be set using the
88                    <code class="literal">DB_CONFIG</code> file's
89                    <code class="literal">set_tx_max</code> parameter. Remember that
90                    the <code class="literal">DB_CONFIG</code> must reside in your
91                    environment home directory.
92                </p>
93</span>
94          </li>
95          <li>
96            <span>
97                  <p>
98                    <span>
99                    Configure the timeout value for your transactions. 
100                    </span>
101                    
102                    
103                    This value represents the longest period of time a
104                    transaction can be active. Note, however, that
105                    transaction timeouts are checked only when DB
106                    examines its lock tables for blocked locks
107                    (see <a class="xref" href="blocking_deadlocks.html" title="Locks, Blocks, and Deadlocks">Locks, Blocks, and Deadlocks</a>
108                    for more information). Therefore, a transaction's timeout can
109                    have expired, but the application will not be notified until DB 
110                    has a reason to examine its lock tables.
111                </p>
112                <p>
113                    Be aware that some transactions may be
114                    inappropriately timed out before the transaction has a
115                    chance to complete. You should therefore use this
116                    mechanism only if you know your application
117                    might have unacceptably long transactions and
118                    you want to make sure your application will
119                    not stall during their execution.
120                    (This might happen if, for example, your
121                    transaction blocks or requests too much
122                    data.)
123                </p>
124                <p>
125                    Note that by default transaction timeouts are set to 0 seconds, which means that they never time
126                    out.
127                </p>
128                <p>
129                    To set the maximum timeout value for your transactions,
130                    use  the
131                            
132                            
133                            <span><code class="methodname">EnvironmentConfig.setTxnTimeout()</code></span>
134                        method. This method configures the entire
135                        environment; not just the handle used to set the
136                        configuration. Further, this value may
137                        be set at any time during the application's
138                        lifetime. <span>(Use
139                        <code class="methodname">Environment.setConfig()</code> to
140                        set this value after the environment has been
141                        opened.)</span>
142                </p>
143                <p>
144                    This value can also be set using the
145                    <code class="literal">DB_CONFIG</code> file's
146                    <code class="literal">set_txn_timeout</code> parameter.
147                </p> 
148                
149</span>
150          </li>
151        </ul>
152      </div>
153      <p>
154            For example:
155        </p>
156      <pre class="programlisting">package db.txn;
157
158import com.sleepycat.db.Environment;
159import com.sleepycat.db.EnvironmentConfig;
160import com.sleepycat.db.LockDetectMode;
161
162import java.io.File;
163import java.io.FileNotFoundException;
164
165...
166
167Environment myEnv = null;
168try {
169    EnvironmentConfig myEnvConfig = new EnvironmentConfig();
170    myEnvConfig.setTransactional(true);
171    myEnvConfig.setInitializeCache(true);
172    myEnvConfig.setInitializeLocking(true);
173    myEnvConfig.setInitializeLogging(true);
174
175    // Configure a maximum transaction timeout of 1 second.
176    myEnvConfig.setTxnTimeout(1000000);
177    // Configure 40 maximum transactions.
178    myEnv.setTxnMaxActive(40);
179
180    myEnv = new Environment(new File("/my/env/home"),
181                              myEnvConfig);
182
183    // From here, you open your databases (or store), proceed with your 
184    // database or store operations, and respond to deadlocks as is 
185    // normal (omitted for brevity).
186
187    ...</pre>
188    </div>
189    <div class="navfooter">
190      <hr />
191      <table width="100%" summary="Navigation footer">
192        <tr>
193          <td width="40%" align="left"><a accesskey="p" href="txnindices.html">Prev</a> </td>
194          <td width="20%" align="center">
195            <a accesskey="u" href="usingtxns.html">Up</a>
196          </td>
197          <td width="40%" align="right"> <a accesskey="n" href="txnconcurrency.html">Next</a></td>
198        </tr>
199        <tr>
200          <td width="40%" align="left" valign="top">Secondary Indices with Transaction Applications </td>
201          <td width="20%" align="center">
202            <a accesskey="h" href="index.html">Home</a>
203          </td>
204          <td width="40%" align="right" valign="top"> Chapter 4. Concurrency</td>
205        </tr>
206      </table>
207    </div>
208  </body>
209</html>
210