1<!--$Id: conf.so,v 10.30 2005/12/01 03:18:51 bostic Exp $-->
2<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
3<!--See the file LICENSE for redistribution information.-->
4<html>
5<head>
6<title>Berkeley DB Reference Guide: Java configuration</title>
7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
9</head>
10<body bgcolor=white>
11<a name="2"><!--meow--></a>
12<table width="100%"><tr valign=top>
13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></b></td>
14<td align=right><a href="/am_misc/faq.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/java/compat.html"><img src="/images/next.gif" alt="Next"></a>
15</td></tr></table>
16<p align=center><b>Java configuration</b></p>
17<p>Building the Berkeley DB java classes, the examples and the native support
18library is integrated into the normal build process.  See
19<a href="/ref/build_unix/conf.html#--enable-java">Configuring
20Berkeley DB</a> and <a href="/ref/build_win/intro.html">Building for Windows</a>
21for more information.</p>
22<p>We expect that you already installed the Java JDK or equivalent on your
23system.  For the sake of discussion, we assume that it is in a directory
24called db-VERSION; for example, you downloaded a Berkeley DB archive, and you
25did not change the top-level directory name.  The files related to Java
26are in three subdirectories of db-VERSION: java (the java source files),
27libdb_java (the C++ files that provide the "glue" between java and
28Berkeley DB) and examples_java (containing all examples code).  The directory
29tree looks like this:</p>
30<blockquote><pre>db-VERSION
31|-- java
32|   `-- src
33|       `-- com
34|           `-- sleepycat
35|               |-- bdb
36|               |   |-- ...
37|               |   |-- bind
38|               |   |   `-- ...
39|               |   `-- util
40|               |       `-- ...
41|               `-- db
42|-- examples_java
43|   `-- src
44|       `-- com
45|           `-- sleepycat
46|               `-- examples
47|                   |-- bdb
48|                   |   `-- ...
49|                   `-- db
50|                       `-- ...
51`-- libdb_java
52    `-- ...
53</pre></blockquote>
54<p>This naming conforms to the de facto standard for naming java packages.
55When the java code is built, it is placed into two jar files:
56<b>db.jar</b>, containing the db package,
57and <b>dbexamples.jar</b>, containing the examples.</p>
58<p>For your application to use Berkeley DB successfully, you must set your
59<b>CLASSPATH</b> environment variable to include the full pathname of
60the db jar files as well as the classes in your java distribution.
61On UNIX, <b>CLASSPATH</b> is a colon-separated
62list of directories and jar files;
63on Windows, it is separated by semicolons.
64On UNIX, the jar files are put in your build directory, and when
65you do the make install step, they are copied to the lib directory
66of your installation tree.  On Windows, the jar files are placed
67in the Release or Debug subdirectory with your other objects.</p>
68<p>The Berkeley DB Java classes are mostly implemented in native
69methods. Before you can use them, you need to make sure that the
70DLL or shared library containing the native methods can be found
71by your Java runtime.  On Windows, you should set your PATH variable
72to include:</p>
73<blockquote><pre><b>db-VERSION\build_windows\Release</b></pre></blockquote>
74<p>On UNIX, you should set the
75<b>LD_LIBRARY_PATH</b> environment variable or local equivalent
76to include the Berkeley DB library installation directory. Of course, the
77standard install directory may have been changed for your site; see your
78system administrator for details.</p>
79<p>On other platforms, the path can be set on the command line as follows
80(assuming the shared library is in <b>/usr/local/BerkeleyDB/lib</b>:)</p>
81<blockquote><pre>% java -Djava.library.path=/usr/local/BerkeleyDB/lib ...</pre></blockquote>
82<p>Regardless, if you get the following exception when you run, you
83probably do not have the library search path configured correctly:</p>
84<blockquote><pre>java.lang.UnsatisfiedLinkError</pre></blockquote>
85<p>Different Java interpreters provide different error messages if the
86<b>CLASSPATH</b> value is incorrect, a typical error is the following:</p>
87<blockquote><pre>java.lang.NoClassDefFoundError</pre></blockquote>
88<p>To ensure that everything is running correctly, you may want to try a
89simple test from the example programs in</p>
90<blockquote><pre><b>db-VERSION/examples_java/src/db</b></pre></blockquote>
91<p>For example, the following sample program will prompt for text input
92lines, which are then stored in a Btree database named <b>access.db</b> in
93your current directory:</p>
94<blockquote><pre>% java db.AccessExample</pre></blockquote>
95<p>Try giving it a few lines of input text and then end-of-file.  Before
96it exits, you should see a list of the lines you entered display with
97data items.  This is a simple check to make sure the fundamental
98configuration is working correctly.</p>
99<table width="100%"><tr><td><br></td><td align=right><a href="/am_misc/faq.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/java/compat.html"><img src="/images/next.gif" alt="Next"></a>
100</td></tr></table>
101<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
102</body>
103</html>
104