1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Java programming notes</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="java.html" title="Chapter��5.�� Java API" /> 11 <link rel="prev" href="java_compat.html" title="Compatibility" /> 12 <link rel="next" href="java_faq.html" title="Java FAQ" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Java programming notes</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="java_compat.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��5.�� 23 Java API 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="java_faq.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="java_program"></a>Java programming notes</h2> 35 </div> 36 </div> 37 </div> 38 <p>Although the Java API parallels the Berkeley DB C++/C interface in many ways, 39it differs where the Java language requires. For example, the handle 40method names are camel-cased and conform to Java naming patterns. (The 41C++/C method names are currently provided, but are deprecated.)</p> 42 <div class="orderedlist"> 43 <ol type="1"> 44 <li>The Java runtime does not automatically close Berkeley DB objects on 45finalization. There are several reasons for this. One is that 46finalization is generally run only when garbage collection occurs, and 47there is no guarantee that this occurs at all, even on exit. Allowing 48specific Berkeley DB actions to occur in ways that cannot be replicated seems 49wrong. Second, finalization of objects may happen in an arbitrary 50order, so we would have to do extra bookkeeping to make sure that 51everything was closed in the proper order. The best word of advice is 52to always do a close() for any matching open() call. Specifically, the 53Berkeley DB package requires that you explicitly call close on each individual 54<a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and 55<a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> object that you opened. Your database 56activity may not be synchronized to disk unless you do so.</li> 57 <li>Some methods in the Java API have no return type, and throw a 58<a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a> when an severe error 59arises. There are some notable methods that do have a return value, and 60can also throw an exception. The "get" methods in 61<a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and 62<a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> both return 0 when a get 63succeeds, <a class="link" href="program_errorret.html#program_errorret.DB_NOTFOUND">DB_NOTFOUND</a> when the key is not found, and throw an 64error when there is a severe error. This approach allows the programmer 65to check for typical data-driven errors by watching return values 66without special casing exceptions. 67<p>An object of type <a class="ulink" href="../java/com/sleepycat/db/MemoryException.html" target="_top">MemoryException</a> is 68thrown when a Dbt is too small to hold the corresponding key or data item.</p><p>An object of type <a class="ulink" href="../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a> is 69thrown when a deadlock would occur.</p><p>An object of type <a class="ulink" href="../java/com/sleepycat/db/RunRecoveryException.html" target="_top">RunRecoveryException</a>, a 70subclass of <a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a>, is thrown when 71there is an error that requires a recovery of the database using <a href="../api_reference/C/db_recover.html" class="olink">db_recover utility</a>.</p><p>An object of type <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a> 72a standard Java Language exception, is thrown when there is an error in 73method arguments.</p><p>An object of type <a class="ulink" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/OutOfMemoryError.html" target="_top">OutOfMemoryError</a> is thrown 74when the system cannot provide enough memory to complete the operation 75(the ENOMEM system error on UNIX).</p></li> 76 <li>If there are embedded nulls in the <span class="bold"><strong>curslist</strong></span> argument for 77<a class="ulink" href="../java/com/sleepycat/db/Database.html#join(com.sleepycat.db.Cursor[], com.sleepycat.db.JoinConfig)" target="_top">Database.join(com.sleepycat.db.Cursor[], com.sleepycat.db.JoinConfig)</a>, 78they will be treated as the end of the list of cursors, even if you 79may have allocated a longer array. Fill in all the cursors in your 80array unless you intend to cut it short.</li> 81 <li>If you are using custom class loaders in your application, make sure 82that the Berkeley DB classes are loaded by the system class loader, not a 83custom class loader. This is due to a JVM bug that can cause an access 84violation during finalization (see the bug 4238486 in Sun Microsystem's 85Java Bug Database).</li> 86 </ol> 87 </div> 88 </div> 89 <div class="navfooter"> 90 <hr /> 91 <table width="100%" summary="Navigation footer"> 92 <tr> 93 <td width="40%" align="left"><a accesskey="p" href="java_compat.html">Prev</a>��</td> 94 <td width="20%" align="center"> 95 <a accesskey="u" href="java.html">Up</a> 96 </td> 97 <td width="40%" align="right">��<a accesskey="n" href="java_faq.html">Next</a></td> 98 </tr> 99 <tr> 100 <td width="40%" align="left" valign="top">Compatibility��</td> 101 <td width="20%" align="center"> 102 <a accesskey="h" href="index.html">Home</a> 103 </td> 104 <td width="40%" align="right" valign="top">��Java FAQ</td> 105 </tr> 106 </table> 107 </div> 108 </body> 109</html> 110