1<!--$Id: program.so,v 10.35 2004/09/10 13:04:01 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 programming notes</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<table width="100%"><tr valign=top> 12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></b></td> 13<td align=right><a href="/java/compat.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/java/faq.html"><img src="/images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Java programming notes</b></p> 16<p>Although the Java API parallels the Berkeley DB C++/C interface in many ways, 17it differs where the Java language requires. For example, the handle 18method names are camel-cased and conform to Java naming patterns. (The 19C++/C method names are currently provided, but are deprecated.)</p> 20<ol> 21<p><li>The Java runtime does not automatically close Berkeley DB objects on 22finalization. There are several reasons for this. One is that 23finalization is generally run only when garbage collection occurs, and 24there is no guarantee that this occurs at all, even on exit. Allowing 25specific Berkeley DB actions to occur in ways that cannot be replicated seems 26wrong. Second, finalization of objects may happen in an arbitrary 27order, so we would have to do extra bookkeeping to make sure that 28everything was closed in the proper order. The best word of advice is 29to always do a close() for any matching open() call. Specifically, the 30Berkeley DB package requires that you explicitly call close on each individual 31<a href="/java/com/sleepycat/db/Database.html">Database</a> and 32<a href="/java/com/sleepycat/db/Cursor.html">Cursor</a> object that you opened. Your database 33activity may not be synchronized to disk unless you do so. 34<p><li>Some methods in the Java API have no return type, and throw a 35<a href="/java/com/sleepycat/db/DatabaseException.html">DatabaseException</a> when an severe error 36arises. There are some notable methods that do have a return value, and 37can also throw an exception. The "get" methods in 38<a href="/java/com/sleepycat/db/Database.html">Database</a> and 39<a href="/java/com/sleepycat/db/Cursor.html">Cursor</a> both return 0 when a get 40succeeds, <a href="/ref/program/errorret.html#DB_NOTFOUND">DB_NOTFOUND</a> when the key is not found, and throw an 41error when there is a severe error. This approach allows the programmer 42to check for typical data-driven errors by watching return values 43without special casing exceptions. 44<p>An object of type <a href="/java/com/sleepycat/db/MemoryException.html">MemoryException</a> is 45thrown when a Dbt is too small to hold the corresponding key or data item.</p> 46<p>An object of type <a href="/java/com/sleepycat/db/DeadlockException.html">DeadlockException</a> is 47thrown when a deadlock would occur.</p> 48<p>An object of type <a href="/java/com/sleepycat/db/RunRecoveryException.html">RunRecoveryException</a>, a 49subclass of <a href="/java/com/sleepycat/db/DatabaseException.html">DatabaseException</a>, is thrown when 50there is an error that requires a recovery of the database using 51<a href="/utility/db_recover.html">db_recover</a>.</p> 52<p>An object of type <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/IllegalArgumentException.html">IllegalArgumentException</a> 53a standard Java Language exception, is thrown when there is an error in 54method arguments.</p> 55<p>An object of type <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/OutOfMemoryError.html">OutOfMemoryError</a> is thrown 56when the system cannot provide enough memory to complete the operation 57(the ENOMEM system error on UNIX).</p> 58<p><li>If there are embedded nulls in the <b>curslist</b> argument for 59<a href="/java/com/sleepycat/db/Database.html#pathsubst(join(com.sleepycat.db.Cursor__BRACKETS__, com.sleepycat.db.JoinConfig), ' ', '%20')">Database.join(com.sleepycat.db.Cursor__BRACKETS__, com.sleepycat.db.JoinConfig)</a>, 60they will be treated as the end of the list of cursors, even if you 61may have allocated a longer array. Fill in all the cursors in your 62array unless you intend to cut it short. 63<p><li>If you are using custom class loaders in your application, make sure 64that the Berkeley DB classes are loaded by the system class loader, not a 65custom class loader. This is due to a JVM bug that can cause an access 66violation during finalization (see the bug 4238486 in Sun Microsystem's 67Java Bug Database). 68</ol> 69<table width="100%"><tr><td><br></td><td align=right><a href="/java/compat.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/java/faq.html"><img src="/images/next.gif" alt="Next"></a> 70</td></tr></table> 71<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 72</body> 73</html> 74
