Sophie: lib64db4.2-devel-4.2.52-11mdv2007.0 x86

lib64db4.2-devel-4.2.52-11mdv2007.0.x86_64.rpm

<!--$Id: env.so,v 1.5 2003/11/19 15:47:51 gburd Exp $-->
<!--Copyright 1997-2003 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB Reference Guide: Opening and closing the database environment</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table width="100%"><tr valign=top>
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Java API Tutorial - Basic</dl></h3></td>
<td align=right><a href="../bdb_basic/keyvalue.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../bdb_basic/catalog.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p>
<h3 align=center>Opening and closing the database environment</h3>
<p>This section of the tutorial describes how to open and close the
database environment.  The database environment manages resources (for
example, memory) and transactions for any number of database stores.  A
single environment instance is normally used for all stores, although
some advanced applications may use multiple environments.</p>
<hr size=1 noshade>
<p>The <b>SampleDatabase</b> class is used to open and close the database
environment.  It will also be used in following sections to open and close the
class catalog and database stores.  Its constructor is used to open the
database and its <b>close()</b> method is used to close the database.  The
skeleton for the <b>SampleDatabase</b> class follows.</p>
<blockquote><pre><b>import com.sleepycat.db.Db;
import com.sleepycat.db.DbException;
import com.sleepycat.db.DbEnv;
import java.io.FileNotFoundException;
import java.io.IOException;
<p>
public class SampleDatabase
{
    private DbEnv env;
<p>
    public SampleDatabase(String homeDirectory, boolean runRecovery)
        throws DbException, FileNotFoundException
    {
    }
<p>
    public void close()
        throws DbException, IOException
    {
    }
}
</b></pre></blockquote>
<p>The first thing to notice is that the DbEnv class is in the
com.sleepycat.db package, not the com.sleepycat.bdb package.  The
db package contains all
core Berkeley DB functionality and is the same across all supported
programming languages.  The bdb package contains extended functionality
that is Java-specific and based on the Java Collections API.  The bdb
package is layered on top of the db package.  Both packages are needed
to create a complete application based on the Java API.</p>
<hr size=1 noshade>
<p>The following statements create a 
<a href="../../java/com/sleepycat/db/DbEnv.html">DbEnv</a>
object and call its 
<a href="../../java/com/sleepycat/db/DbEnv.html#open">DbEnv.open</a>
 method.</p>
<blockquote><pre>
    public SampleDatabase(String homeDirectory, boolean runRecovery)
        throws DbException, FileNotFoundException
    {
<b>        int envFlags = Db.DB_INIT_TXN | Db.DB_INIT_LOCK | Db.DB_INIT_MPOOL |
                       Db.DB_CREATE;
        if (runRecovery) envFlags |= Db.DB_RECOVER;
        env = new DbEnv(0);
        System.out.println("Opening environment in: " + homeDirectory);
        env.open(homeDirectory, envFlags, 0);
</b>    }
</pre></blockquote>
<p>Notice that flags are used to specify options for the environment when it
is opened.  Flags are used in many places in the Berkeley DB API.  To specify more
than one flag, OR them together with the '|' operator as shown.</p>
<p>The first three environment flags used --
<a href="../../java/com/sleepycat/db/Db.html#DB_INIT_TXN">Db.DB_INIT_TXN</a>
,
<a href="../../java/com/sleepycat/db/Db.html#DB_INIT_LOCK">Db.DB_INIT_LOCK</a>
, and
<a href="../../java/com/sleepycat/db/Db.html#DB_INIT_MPOOL">Db.DB_INIT_MPOOL</a>
 --
must always be specified when opening a transactional environment.  While
non-transactional environments can also be created, the examples in this
tutorial use a transactional environment.</p>
<p>The 
<a href="../../java/com/sleepycat/db/Db.html#DB_CREATE">Db.DB_CREATE</a>
 flag specifies that
the environment's files (database, log and shared memory pool files) will be
created if they don't already exist.  If this flag is not specified, an
exception will be thrown if the environment does not already exist.  The same
flag will be used later to cause database stores to be created if they don't
exist.</p>
<p>The 
<a href="../../java/com/sleepycat/db/Db.html#DB_RECOVER">Db.DB_RECOVER</a>
 flag causes database
recovery to be performed, if recovery is necessary because of an error that
occurred previously.  In general, it is safe to run recovery unconditionally if
the current process is known to be the only one attempting to access the
database.  The <b>runRecovery</b> parameter in the example is used to
control this behavior so that recovery can be coordinated among multiple
processes.  This will be explained further when the example's main() method is
described.</p>
<p>When the 
<a href="../../java/com/sleepycat/db/DbEnv.html#open">DbEnv.open</a>
 method is called,
a home directory, a flags parameter, and a file open mode are specified.  The
home directory is the location of the environment files and is the default
parent directory for database store files.  The flags are those described
above.  The open mode is used for creating files on UNIX systems, where zero
means to use a reasonable default.</p>
<hr size=1 noshade>
<p>The following statement closes the environment.  The environment should
always be closed when database work is completed to free allocated resources
and to prevent having to run recovery later.  Closing the environment does not
automatically close database stores, so stores must be closed explicitly before
closing the environment.</p>
<blockquote><pre>
    public void close()
        throws DbException, IOException
    {
<b>        env.close(0);
</b>    }
</pre></blockquote>
<hr size=1 noshade>
<p>The following getter method returns the environment for use by other
classes in the example program.  The environment is used for running
transactions, among other things.</p>
<blockquote><pre>
public class SampleDatabase
{
    ...
<b>    public final DbEnv getEnvironment()
    {
        return env;
    }
</b>    ...
}
</pre></blockquote>
<table width="100%"><tr><td><br></td><td align=right><a href="../bdb_basic/keyvalue.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../bdb_basic/catalog.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p><font size=1><a href="../../sleepycat/legal.html">Copyright (c) 1996-2003</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font>
</body>
</html>