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>Chapter��2.��Database Environments</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" />
10    <link rel="up" href="index.html" title="Getting Started with Berkeley DB" />
11    <link rel="previous" href="gettingit.html" title="Getting and Using DB " />
12    <link rel="next" href="EnvClose.html" title="Closing Database Environments" />
13  </head>
14  <body>
15    <div class="navheader">
16      <table width="100%" summary="Navigation header">
17        <tr>
18          <th colspan="3" align="center">Chapter��2.��Database Environments</th>
19        </tr>
20        <tr>
21          <td width="20%" align="left"><a accesskey="p" href="gettingit.html">Prev</a>��</td>
22          <th width="60%" align="center">��</th>
23          <td width="20%" align="right">��<a accesskey="n" href="EnvClose.html">Next</a></td>
24        </tr>
25      </table>
26      <hr />
27    </div>
28    <div class="chapter" lang="en" xml:lang="en">
29      <div class="titlepage">
30        <div>
31          <div>
32            <h2 class="title"><a id="Env"></a>Chapter��2.��Database Environments</h2>
33          </div>
34        </div>
35        <div></div>
36      </div>
37      <div class="toc">
38        <p>
39          <b>Table of Contents</b>
40        </p>
41        <dl>
42          <dt>
43            <span class="sect1">
44              <a href="Env.html#EnvOpen">Opening Database Environments</a>
45            </span>
46          </dt>
47          <dt>
48            <span class="sect1">
49              <a href="EnvClose.html">Closing Database Environments</a>
50            </span>
51          </dt>
52          <dt>
53            <span class="sect1">
54              <a href="EnvProps.html">Environment Properties</a>
55            </span>
56          </dt>
57          <dd>
58            <dl>
59              <dt>
60                <span class="sect2">
61                  <a href="EnvProps.html#envconfig">The EnvironmentConfig Class</a>
62                </span>
63              </dt>
64              <dt>
65                <span class="sect2">
66                  <a href="EnvProps.html#envhandleconfig">EnvironmentMutableConfig</a>
67                </span>
68              </dt>
69            </dl>
70          </dd>
71        </dl>
72      </div>
73      <p>
74    Environments are optional, but very commonly used, for Berkeley DB
75    applications built using the base API. If you are using the DPL, then
76    environments are required.
77  </p>
78      <p>
79  	Database environments encapsulate one or more databases. This encapsulation 
80  	provides your threads with efficient access to your databases by allowing a single
81  	in-memory cache to be used for each of the databases contained in the
82  	environment. This encapsulation also allows you to group operations performed against 
83    multiple databases inside a single
84  	transactions (see the <i class="citetitle">Berkeley DB Java Edition Getting Started with Transaction Processing</i> guide for more information).
85  </p>
86      <p>
87  	Most commonly you use database environments to create and open
88  	databases (you close individual databases using the individual
89  	database handles). You can also use environments to delete and rename
90  	databases. For transactional applications, you use the environment to start
91  	transactions. For non-transactional
92  	applications, you use the environment to sync your in-memory cache to disk.
93 </p>
94      <div class="sect1" lang="en" xml:lang="en">
95        <div class="titlepage">
96          <div>
97            <div>
98              <h2 class="title" style="clear: both"><a id="EnvOpen"></a>Opening Database Environments</h2>
99            </div>
100          </div>
101          <div></div>
102        </div>
103        <p>You open a database environment by instantiating an
104    <tt class="classname">Environment</tt> object. You must provide to the
105    constructor the name of the on-disk directory where the environment is to reside.
106    This directory location must exist or the open will fail.</p>
107        <p>By default, the environment is not created for you if it does not exist. Set the 
108    <a href="EnvProps.html" title="Environment Properties">creation property</a> to <tt class="literal">true</tt> if
109    you want the environment to be created. For example:</p>
110        <a id="je_env1"></a>
111        <pre class="programlisting">
112    
113import com.sleepycat.je.DatabaseException;
114import com.sleepycat.je.Environment;
115import com.sleepycat.je.EnvironmentConfig;
116
117import java.io.File;
118
119...
120
121// Open the environment. Allow it to be created if it does not already exist.
122Environment myDbEnvironment = null;
123
124try {
125    EnvironmentConfig envConfig = new EnvironmentConfig();
126    envConfig.setAllowCreate(true);
127    myDbEnvironment = new Environment(new File("/export/dbEnv"), envConfig);
128} catch (DatabaseException dbe) {
129    // Exception handling goes here
130} </pre>
131        <pre class="programlisting">package db.gettingStarted;
132    
133import com.sleepycat.db.DatabaseException;
134import com.sleepycat.db.Environment;
135import com.sleepycat.db.EnvironmentConfig;
136
137import java.io.File;
138import java.io.FileNotFoundException;
139
140...
141
142// Open the environment. Allow it to be created if it does not already exist.
143Environment myDbEnvironment = null;
144
145try {
146    EnvironmentConfig envConfig = new EnvironmentConfig();
147    envConfig.setAllowCreate(true);
148    myDbEnvironment = new Environment(new File("/export/dbEnv"), envConfig);
149} catch (DatabaseException dbe) {
150    // Exception handling goes here
151} catch (FileNotFoundException fnfe) {
152// Exception handling goes here
153} </pre>
154        <p>Your application can open and use as many environments as you have
155    disk and memory to manage, although most applications will use just one
156    environment. Also, you can instantiate multiple <tt class="classname">Environment</tt>
157    objects for the same physical environment.</p>
158      </div>
159    </div>
160    <div class="navfooter">
161      <hr />
162      <table width="100%" summary="Navigation footer">
163        <tr>
164          <td width="40%" align="left"><a accesskey="p" href="gettingit.html">Prev</a>��</td>
165          <td width="20%" align="center">
166            <a accesskey="u" href="index.html">Up</a>
167          </td>
168          <td width="40%" align="right">��<a accesskey="n" href="EnvClose.html">Next</a></td>
169        </tr>
170        <tr>
171          <td width="40%" align="left" valign="top">Getting and Using DB ��</td>
172          <td width="20%" align="center">
173            <a accesskey="h" href="index.html">Home</a>
174          </td>
175          <td width="40%" align="right" valign="top">��Closing Database Environments</td>
176        </tr>
177      </table>
178    </div>
179  </body>
180</html>
181