mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 18:07:18 +00:00
317 lines
12 KiB
HTML
317 lines
12 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Chapter 3. Direct Persistence Layer First Steps</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Getting Started with Berkeley DB Java Edition" />
|
||
<link rel="up" href="dpl.html" title="Part I. Programming with the Direct Persistence Layer" />
|
||
<link rel="prev" href="dpl.html" title="Part I. Programming with the Direct Persistence Layer" />
|
||
<link rel="next" href="persistobject.html" title="Persistent Objects" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 12.2.7.5</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Chapter 3. Direct Persistence Layer First Steps</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="dpl.html">Prev</a> </td>
|
||
<th width="60%" align="center">Part I. Programming with the Direct Persistence Layer</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="persistobject.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="chapter" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title"><a id="persist_first"></a>Chapter 3. Direct Persistence Layer First Steps</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<p>
|
||
<b>Table of Contents</b>
|
||
</p>
|
||
<dl>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="persist_first.html#entitystore">Entity Stores</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="persist_first.html#persist-open">Opening and Closing Environments and Stores</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</dd>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="persistobject.html">Persistent Objects</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="saveret.html">Saving and Retrieving Data</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
This chapter guides you through the first few steps required to
|
||
use the DPL with your application. These steps include:
|
||
</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
Opening your environment as was described in
|
||
<span>
|
||
<a class="xref" href="env.html#envopen" title="Opening Database Environments">Opening Database Environments</a>.
|
||
</span>
|
||
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Opening your entity store.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Identifying the classes that you want to store in
|
||
JE as either a <code class="literal">persistent</code>
|
||
class or an <code class="literal">entity</code>.
|
||
</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>
|
||
Once you have done these things, you can write your classes to
|
||
the JE databases, read them back from the databases, delete
|
||
them from the databases, and so forth. These activities are
|
||
described in the chapters that follow in this part of this manual.
|
||
</p>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="entitystore"></a>Entity Stores</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="persist_first.html#persist-open">Opening and Closing Environments and Stores</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
Entity stores are the basic unit of storage that you use with the DPL. That is, it
|
||
is a unit of encapsulation for the classes that you want to store in JE. Under
|
||
the hood it actually interacts with JE databases, but the DPL provides a layer
|
||
of abstraction from the underlying JE APIs. The store, therefore, provides a
|
||
simplified mechanism by which you read and write your stored classes. By using a
|
||
store, you have access to your classes that is more simplified than if you were
|
||
interacting with databases directly, but this simplified access comes at the cost of
|
||
reduced flexibility.
|
||
</p>
|
||
<p>
|
||
Entity stores have configurations in the same way that environments have
|
||
configurations. You can use a <code class="classname">StoreConfig</code> object
|
||
to identify store properties. Among these are methods that allow you to declare
|
||
whether:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
the store can be created if it does not exist at the time
|
||
it is opened. Use the
|
||
<code class="methodname">StoreConfig.setAllowCreate()</code>
|
||
method to set this.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
deferred writes are allowed for the store. Use the
|
||
<code class="methodname">StoreConfig.setDeferredWrite()</code>
|
||
method to set this. See
|
||
<a class="xref" href="databases.html#dwdatabase" title="Deferred Write Databases">Deferred Write Databases</a>
|
||
for general information on deferred write
|
||
databases.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
the store is read-only. Use the
|
||
<code class="methodname">StoreConfig.setReadOnly()</code>
|
||
method to set this.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
the store supports transactions. Use the
|
||
<code class="methodname">StoreConfig.setTransactional()</code>
|
||
method to set this.
|
||
</p>
|
||
<p>
|
||
Writing JE transactional applications is described in the
|
||
<em class="citetitle">Berkeley DB, Java Edition Getting Started with Transaction Processing</em> guide.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
<code class="classname">EntityStore</code> objects also provide methods for retrieving
|
||
information about the store, such as:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
the store's name. Use the
|
||
<code class="methodname">EntityStore.getStoreName()</code>
|
||
method to retrieve this.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
a handle to the environment in which the store is opened. Use the
|
||
<code class="methodname">EntityStore.getEnvironment</code>
|
||
method to retrieve this handle.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
You can also use the <code class="classname">EntityStore</code> to
|
||
retrieve all the primary and secondary indexes related to a given type of entity
|
||
object contained in the store. See <a class="xref" href="persist_index.html" title="Chapter 4. Working with Indices">Working with Indices</a> for
|
||
more information.
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="persist-open"></a>Opening and Closing Environments and Stores</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
As described in
|
||
<span>
|
||
<a class="xref" href="env.html" title="Chapter 2. Database Environments">Database Environments</a>,
|
||
</span>
|
||
|
||
|
||
an
|
||
<span class="emphasis"><em>environment</em></span> is a unit of
|
||
encapsulation for JE databases. It also provides a
|
||
handle by which activities common across the databases
|
||
can be managed.
|
||
</p>
|
||
<p>
|
||
To use an entity store, you must first open an environment and then provide that
|
||
environment handle to the <code class="classname">EntityStore</code> constructor.
|
||
</p>
|
||
<p>
|
||
For example, the following code fragment configures both
|
||
the environment and the entity store such that they can
|
||
be created if they do not exist. Both the environment and
|
||
the entity store are then opened.
|
||
</p>
|
||
<pre class="programlisting">package persist.gettingStarted;
|
||
|
||
import java.io.File;
|
||
|
||
import com.sleepycat.je.DatabaseException;
|
||
import com.sleepycat.je.Environment;
|
||
import com.sleepycat.je.EnvironmentConfig;
|
||
|
||
import com.sleepycat.persist.EntityStore;
|
||
import com.sleepycat.persist.StoreConfig;
|
||
|
||
...
|
||
|
||
private Environment myEnv;
|
||
private EntityStore store;
|
||
|
||
try {
|
||
EnvironmentConfig myEnvConfig = new EnvironmentConfig();
|
||
StoreConfig storeConfig = new StoreConfig();
|
||
|
||
myEnvConfig.setAllowCreate(!readOnly);
|
||
storeConfig.setAllowCreate(!readOnly);
|
||
|
||
// Open the environment and entity store
|
||
myEnv = new Environment(envHome, myEnvConfig);
|
||
store = new EntityStore(myEnv, "EntityStore", storeConfig);
|
||
} catch(DatabaseException dbe) {
|
||
System.err.println("Error opening environment and store: " +
|
||
dbe.toString());
|
||
System.exit(-1);
|
||
} </pre>
|
||
<p>
|
||
As always, before you exit your program you should close both
|
||
your store and your environment. It is recommended that you close your store before you close your
|
||
environment.
|
||
</p>
|
||
<pre class="programlisting">if (store != null) {
|
||
try {
|
||
store.close();
|
||
} catch(DatabaseException dbe) {
|
||
System.err.println("Error closing store: " +
|
||
dbe.toString());
|
||
System.exit(-1);
|
||
}
|
||
}
|
||
|
||
if (myEnv != null) {
|
||
try {
|
||
// Finally, close environment.
|
||
myEnv.close();
|
||
} catch(DatabaseException dbe) {
|
||
System.err.println("Error closing MyDbEnv: " +
|
||
dbe.toString());
|
||
System.exit(-1);
|
||
}
|
||
} </pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="dpl.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="dpl.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="persistobject.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Part I. Programming with the Direct Persistence Layer </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Persistent Objects</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|