greg/je
1
0
Fork 0
mirror of https://github.com/berkeleydb/je.git synced 2024-11-15 01:46:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
je/docs/GettingStartedGuide/applicationoverview.html

629 lines
32 KiB
HTML
Raw Permalink Normal View History

Initial import.
2021-06-06 17:46:45 +00:00
<?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>The JE Application</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="introduction.html" title="Chapter 1. Introduction to Berkeley DB Java Edition" />
<link rel="prev" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB Java Edition" />
<link rel="next" href="restore.html" title="JE Backup and Restore" />
</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">The JE Application</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td>
<th width="60%" align="center">Chapter 1. Introduction to Berkeley DB Java Edition </th>
<td width="20%" align="right"> <a accesskey="n" href="restore.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="applicationoverview"></a>The JE Application</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="applicationoverview.html#dbIntro">Database Environments</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#key-data">Key-Data Pairs</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#storing-intro">Storing Data</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#duplicatesintro">Duplicate Data</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#replacedeleteIntro">Replacing and Deleting Entries</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#secondary">Secondary Keys</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#transactionIntro">Transactions</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#resourcesIntro">JE Resources</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="applicationoverview.html#applicationConsiderations">
Application Considerations
</a>
</span>
</dt>
</dl>
</div>
<p>This section provides a brief overview to the major concepts and
operations that comprise a JE application. This section is concluded with a summary of the decisions that
you need to make when working with JE.</p>
<p>
Note that the core JE classes are all contained in the <code class="literal">com.sleepycat.je</code> package.
In addition, this book describes some classes that are found in <code class="literal">com.sleepycat.je.bind</code>.
The bind APIs are used for converting Java objects in and out of <code class="literal">byte</code> arrays.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="dbIntro"></a>Database Environments</h3>
</div>
</div>
</div>
<p>
Regardless of the JE API that you use, your data is
stored in databases. If you use the DPL, you do not manage
these databases directly; rather, they are managed for you by
the API. On the other hand, if you use the lower-level JE
APIs, then you must manage databases directly. This is not
difficult to do as it mostly involves opening and closing the
databases, giving them names, and so forth. See
<a class="xref" href="databases.html" title="Chapter 7. Databases">Databases</a>
for more
information.
</p>
<p>
That said, JE always requires you to use a
<span class="emphasis"><em>database environment</em></span>. Database
environments provide an unit of encapsulation for one or more
databases. Environments correspond to a directory location on
disk, and in them you will find all the files in use by JE.
Environments are also used to manage JE resources such as
transactions.
</p>
<p>
To use a database environment, it must first be created and then
opened. In order to create a database environment, the
directory location in which it resides must already exist.
</p>
<p>
You open a database environment by instantiating an
<code class="classname">Environment</code> object. Your
<code class="classname">Environment</code> instance is called
an <span class="emphasis"><em>environment handle</em></span>.
</p>
<p>
Once you have opened an environment, what you do with it
depends on the nature of your application; that is, the
JE API you are using and whether you are using advanced
features such as transactions. (See
<em class="citetitle">Berkeley DB, Java Edition Getting Started with Transaction Processing</em>
for details on using
transactions). However, at a minimum you will always have to
open your environment before you can access your data stored
in JE. Also, before you end your application you should
always close your environment.
</p>
<p>
Environments are described in greater detail in <a class="xref" href="env.html" title="Chapter 2. Database Environments">Database Environments</a>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="key-data"></a>Key-Data Pairs</h3>
</div>
</div>
</div>
<p>
JE stores and retrieves data using
<span class="emphasis"><em>key-data pairs</em></span>. The
<span class="emphasis"><em>data</em></span> portion of this is the data
that you have decided to store in JE for future
retrieval. The <span class="emphasis"><em>key</em></span> is the
information that you want to use to look up your
stored data once it has been placed inside a JE
database.
</p>
<p>
For example, if you were building a database that
contained employee information, then the
<span class="emphasis"><em>data</em></span> portion is all of the
information that you want to store about the employees:
name, address, phone numbers, physical location, their
manager, and so forth.
</p>
<p>
The <span class="emphasis"><em>key</em></span>, however, is the way that
you look up any given employee. You can have more than
one key if you wish, but every record in your database must have a
primary key. If you are using the DPL, then this key must be unique; that is,
it must not be used multiple times in the database. However, if you are using
the base API, then this requirement is relaxed. See
<a class="xref" href="applicationoverview.html#duplicatesintro" title="Duplicate Data">Duplicate Data</a> for more
information.
</p>
<p>
For example, in the case of an employee database, you would probably use
something like the employee identification number as the primary key as this
uniquely identifies a given employee.
</p>
<p>
You can optionally also have secondary keys that represent indexes
into your database. These keys do not have to be unique
to a given record; in fact, they often are not. For
example, you might set up the employee's manager's name
as a secondary key so that it is easy to locate all
the employee's that work for a given manager.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="storing-intro"></a>Storing Data</h3>
</div>
</div>
</div>
<p>
How you manage your stored information differs
significantly, depending on which API you are using.
Both APIs ultimately are doing the same thing, but the
DPL hides a lot of the details from you.
</p>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="dplstore"></a>Storing Data in the DPL</h4>
</div>
</div>
</div>
<p>
The DPL is used to store Java objects in an
underlying series of databases. These databases are
accessed using an <code class="classname">EntityStore</code>
class object.
</p>
<p>
To use the DPL, you must decorate the classes you
want to store with Java annotations that identify them
as either an <span class="emphasis"><em>entity class</em></span> or a
<span class="emphasis"><em>persistent class</em></span>.
</p>
<p>
Entity classes are classes that have a primary key, and
optionally one or more secondary keys. That is, these
are the classes that you will save and retrieve directly
using the DPL. You identify an entity class using the
<code class="literal">@Entity</code> java annotation.
</p>
<p>
Persistent classes are classes used by entity classes.
They do not have primary or secondary indices used for
object retrieval. Rather, they are stored or retrieved
when an entity class makes direct use of them. You
identify an persistent class using the
<code class="literal">@Persistent</code> java annotation.
</p>
<p>
The primary key for an object is obtained from one of the class' data members.
You identify which data member to use as the primary key using the
<code class="literal">@PrimaryKey</code> java annotation.
</p>
<p>
Note that all non-transient instance fields of a
persistent class, as well as its superclasses and
subclasses, are persistent. Static and transient fields
are not persistent. The persistent fields of a class
may be private, package-private (default access),
protected or public.
</p>
<p>
Also, simple Java types, such as
<code class="classname">java.lang.String</code> and
<code class="classname">java.util.Date</code>, are automatically handled as a
persistent class when you use them in an entity class;
you do not have to do anything special to cause these
simple Java objects to be stored in the
<code class="classname">EntityStore</code>.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="lowlevelstore"></a>Storing Data using the Base API</h4>
</div>
</div>
</div>
<p>
When you are not using the DPL, both record keys and record data must be byte
arrays and are passed to and returned from JE using
<code class="classname">DatabaseEntry</code> instances.
<code class="classname">DatabaseEntry</code> only supports storage of Java byte arrays.
Complex objects must be marshaled using either Java serialization, or more
efficiently with the bind APIs provided with JE </p>
<p> Database
records and <code class="literal">byte</code> array conversion are described in <a class="xref" href="DBEntry.html" title="Chapter 8. Database Records">Database Records</a>.
</p>
<p>
You store records in a <code class="classname">Database</code> by calling one of the
put methods on a <code class="classname">Database</code> handle. JE
automatically determines the record's proper placement in the database's
internal B-Tree using whatever key and data comparison functions that are
available to it.
</p>
<p>
You can also retrieve, or get, records using the
<code class="classname">Database</code> handle. Gets are performed by providing the
key (and sometimes also the data) of the record that you want to retrieve.
</p>
<p>
You can also use cursors for database puts and gets. Cursors are essentially
a mechanism by which you can iterate over the records in the database. Like
databases and database environments, cursors must be opened and closed.
Cursors are managed using the <code class="classname">Cursor</code> class.
</p>
<p>
Databases are described in <a class="xref" href="databases.html" title="Chapter 7. Databases">Databases</a>. Cursors
are described in <a class="xref" href="Cursors.html" title="Chapter 9. Using Cursors">Using Cursors</a>.
</p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="duplicatesintro"></a>Duplicate Data</h3>
</div>
</div>
</div>
<p>
If you are using the base API, then at creation time databases can be configured to
allow duplicate data. Remember that JE database records consist of a key/data
pair. <span class="emphasis"><em>Duplicate data</em></span>, then, occurs when two or more records have
identical keys, but different data. By default, a <code class="classname">Database</code> does
not allow duplicate data.
</p>
<p>
If your <code class="classname">Database </code> contains duplicate data, then a simple
database get based only on a key returns just the first record that uses that key. To
access all duplicate records for that key, you must use a cursor.
</p>
<p>
If you are using the DPL, then you can duplicate date using
secondary keys, but not by using the primary key. For more information, see
<a class="xref" href="getmultiple.html" title="Retrieving Multiple Objects">Retrieving Multiple Objects</a>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="replacedeleteIntro"></a>Replacing and Deleting Entries</h3>
</div>
</div>
</div>
<p>
If you are using the DPL, then replacing a stored entity object simply consists of
retrieving it, updating it, then storing it again. To delete the object, use the
<code class="methodname">delete()</code> method that is available on either its primary or
secondary keys. If you use the <code class="methodname">delete()</code> method available on
the secondary key, then all objects referenced by that key are also deleted.
See <a class="xref" href="dpl_delete.html" title="Deleting Entity Objects">Deleting Entity Objects</a>
for more information.
</p>
<p>
If you are using the base API, then how you replace database records depends on whether
duplicate data is allowed in the database.
</p>
<p>
If duplicate data is not allowed in the database, then simply calling
<code class="methodname">Database.put()</code> with the appropriate key will cause any
existing record to be updated with the new data. Similarly, you can delete a record by
providing the appropriate key to the <code class="methodname">Database.delete()</code>
method.
</p>
<p>
If duplicate data is allowed in the database, then you must position a cursor to the
record that you want to update, and then perform the put operation using the cursor.
</p>
<p>
To delete records using the base API, you can use either <code class="methodname">Database.delete()</code> or
<code class="methodname">Cursor.delete()</code>. If duplicate data is not allowed in your
database, then these two method behave identically. However, if duplicates are allowed
in the database, then <code class="methodname">Database.delete()</code> deletes every record
that uses the provided key, while <code class="methodname">Cursor.delete()</code> deletes just
the record at which the cursor is currently positioned.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="secondary"></a>Secondary Keys</h3>
</div>
</div>
</div>
<p>
Secondary keys provide an alternative way to locate information stored in
JE, beyond that which is provided by the primary key. Frequently secondary
keys refer to more than one record in the database. In this way, you can find
all the cars that are green (if you are maintaining an automotive database) or
all the people with brown eyes (if you are maintaining a database about people).
In other words, secondary keys represent a index into your data.
</p>
<p>
How you create and maintain secondary keys differs significantly, depending on
whether you are using the DPL or the base API.
</p>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="secondarydpl"></a>Using Secondaries with the DPL</h4>
</div>
</div>
</div>
<p>
Under the DPL, you declare a particular field to be a secondary key by
using the <code class="literal">@SecondaryKey</code> annotation. When you do this,
you must declare what kind of an index you are creating. For example,
you can declare a secondary key to be part of a
<code class="literal">ONE_TO_ONE</code> index, in which case the key is unique to
the object. Or you could declare the key to be
<code class="literal">MANY_TO_ONE</code>, in which case the key can be used for
multiple objects in the data store.
</p>
<p>
Once you have identified secondary keys for a class, you can access
those keys by using the <code class="methodname">EntityStore.getSecondaryIndex()</code>
method.
</p>
<p>
For more information, see <a class="xref" href="dplindexcreate.html#dplsecondaryidxdecl" title="Declaring Secondary Indexes">Declaring Secondary Indexes</a>.
</p>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="secondarybaseapi"></a>Using Secondaries with the Base API.</h4>
</div>
</div>
</div>
<p>
When you are using the base API, you create and maintain secondary keys using a
special type of a database, called a <span class="emphasis"><em>secondary database</em></span>.
When you are using secondary databases, the database that holds the data you are
indexing is called the <span class="emphasis"><em>primary database</em></span>.
</p>
<p>
You create a secondary database by opening it and associating it with an
existing primary database. You must also provide a class that generates the
secondary's keys (that is, the index) from primary records. Whenever a
record in the primary database is added or changed, JE uses this class
to determine what the secondary key should be.
</p>
<p>
When a primary record is created, modified, or deleted, JE automatically
updates the secondary database(s) for you as is appropriate for the
operation performed on the primary.
</p>
<p>
You manage secondary databases using the
<code class="classname">SecondaryDatabase</code> class. You identify how to create keys
for your secondary databases by supplying an instance of a class that implements
the <code class="classname">SecondaryKeyCreator</code> interface.
</p>
<p>
Secondary databases are described in <a class="xref" href="indexes.html" title="Chapter 10. Secondary Databases">Secondary Databases</a>.
</p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="transactionIntro"></a>Transactions</h3>
</div>
</div>
</div>
<p>
Transactions provide a high level of safety for your JE operations by allowing
you to manage one or more operations as if they were a single unit of work.
Transactions provide your JE operations with recoverability, atomicity, and
isolation.
</p>
<p>
Transactions provide recoverability by allowing JE to undo any
transactional-protected operations that may have been in progress at the time of an
application or system failure.
</p>
<p>
Transactions provide atomicity by allowing you to group many operations into
a single unit of work. Either all operations succeed or none of them do. This means
that if one write operation fails for any reason, then all other writes contained
within that transaction also fail. This ensures that the database is never partially
updated as the result of an only partially successful chain of read/write operations.
</p>
<p>
Transactions provide isolation by ensuring that the transaction will never write to a
record that is currently in use (for either read or write) by another transaction.
Similarly, any record to which the transaction has written can not be read outside of
the transaction until the transaction ends. Note that this is only the default
behavior; you can configure your <code class="classname">Database</code>,
<code class="classname">Cursor</code>, or <code class="classname">Transaction</code> handle to relax
its isolation guarantees.
</p>
<p>
Essentially, transactional isolation provides a transaction with the same unmodified view of the
database that it would have received had the operations been performed in a single-threaded application.
</p>
<p>
Transactions may be long or short lived, they can encompass as many
operations as you want, and (if using the base API) they can span databases
so long as all participating databases reside in the same environment.
</p>
<p>
Transaction usage results in a performance penalty for the application because they
generally require more disk I/O than do non-transactional operations. Therefore, while
most applications will use transactions for JE writes, their usage is optional.
In particular, processes that are performing read-only operations
might not use transactions. Also, applications that use JE for an easily
recreated cache might also choose to avoid transactions.
</p>
<p>
Using transactions with your JE applications is described in detail in the
<em class="citetitle">Berkeley DB, Java Edition Getting Started with Transaction Processing</em> guide.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="resourcesIntro"></a>JE Resources</h3>
</div>
</div>
</div>
<p>
JE has some internal resources that you may want to manage. Most important of these is the in-memory cache.
You should carefully consider how large the JE cache needs to be. If you set this number too low, JE will
perform potentially unnecessary disk I/O which will result in a performance hit. If you set it too high, then
you are potentially wasting RAM that could be put to better purposes.
</p>
<p>
Note that the size that you configure for the in-memory cache is a maximum size. At application startup, the
cache starts out fairly small (only about 7% of the maximum allowed size for the cache). It then grows as is
required by your application's database operations. Also, the cache is not pinned in memory – it can be
paged out by your operating system's virtual memory system.
</p>
<p>
Beyond the cache, JE uses several background threads to clean
the JE log files, to compress the database by removing unneeded
subtrees, and to flush database changes seen in the cache to the backing data files. For the
majority of JE applications, the default behavior for the background threads should be acceptable and you
will not need to manage their behavior. Note that background threads are started no more than once per
process upon environment open.
</p>
<p>
For more information on sizing the cache and on the background threads, see <a class="xref" href="administration.html" title="Chapter 12. Administering Berkeley DB Java Edition Applications">Administering Berkeley DB Java Edition Applications</a>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="applicationConsiderations"></a>
Application Considerations
</h3>
</div>
</div>
</div>
<p>When building your JE application, be sure to think about the following things:</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>What data do you want to store? What is best used for the
primary key? What is the best representation for primary record data?
If you are using the base API, think about the most efficient way to move your keys and data in and
out of byte arrays. See <a class="xref" href="DBEntry.html" title="Chapter 8. Database Records">Database Records</a> for more information.</p>
</li>
<li>
<p>Does the nature of your data require duplicate record support?
Remember that duplicate support can be configured only if you are using the base
API, and then only at database
creation time. See <a class="xref" href="databases.html#DBOpen" title="Opening Databases">Opening Databases</a> for more information.</p>
<p>If you are supporting duplicate records, you may also need to think
about duplicate comparators (not just key comparators). See
<a class="xref" href="comparator.html" title="Using Comparators">Using Comparators</a> for more information.</p>
</li>
<li>
<p>What secondary indexes do you need? How can you compute your secondary indexes based on the data and
keys stored in your primary database?
Indexes are described in <a class="xref" href="indexes.html" title="Chapter 10. Secondary Databases">Secondary Databases</a>.</p>
</li>
<li>
<p>What cache size do you need? See
<a class="xref" href="cachesize.html" title="Sizing the Cache">Sizing the Cache</a> for information on how to size your cache.</p>
</li>
<li>
<p>Does your application require transactions (most will).
Transactions are described in the
<em class="citetitle">Berkeley DB, Java Edition Getting Started with Transaction Processing</em> guide.
</p>
</li>
</ul>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="introduction.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="restore.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 1. Introduction to Berkeley DB Java Edition  </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> JE Backup and Restore</td>
</tr>
</table>
</div>
</body>
</html>
Reference in a new issue Copy permalink