diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/java_program.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/java_program.html')
| -rw-r--r-- | docs/programmer_reference/java_program.html | 133 |
1 files changed, 83 insertions, 50 deletions
diff --git a/docs/programmer_reference/java_program.html b/docs/programmer_reference/java_program.html index 3a191702..8a4a4308 100644 --- a/docs/programmer_reference/java_program.html +++ b/docs/programmer_reference/java_program.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="java_compat.html">Prev</a> </td> - <th width="60%" align="center">Chapter 5. - Java API - </th> + <th width="60%" align="center">Chapter 5. Java API </th> <td width="20%" align="right"> <a accesskey="n" href="java_faq.html">Next</a></td> </tr> </table> @@ -38,54 +36,89 @@ </div> </div> </div> - <p>Although the Java API parallels the Berkeley DB C++/C interface in many ways, -it differs where the Java language requires. For example, the handle -method names are camel-cased and conform to Java naming patterns. (The -C++/C method names are currently provided, but are deprecated.)</p> + <p> + Although the Java API parallels the Berkeley DB C++/C + interface in many ways, it differs where the Java language + requires. For example, the handle method names are camel-cased + and conform to Java naming patterns. (The C++/C method names + are currently provided, but are deprecated.) + </p> <div class="orderedlist"> <ol type="1"> - <li>The Java runtime does not automatically close Berkeley DB objects on -finalization. There are several reasons for this. One is that -finalization is generally run only when garbage collection occurs, and -there is no guarantee that this occurs at all, even on exit. Allowing -specific Berkeley DB actions to occur in ways that cannot be replicated seems -wrong. Second, finalization of objects may happen in an arbitrary -order, so we would have to do extra bookkeeping to make sure that -everything was closed in the proper order. The best word of advice is -to always do a close() for any matching open() call. Specifically, the -Berkeley DB package requires that you explicitly call close on each individual -<a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and -<a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> object that you opened. Your database -activity may not be synchronized to disk unless you do so.</li> - <li>Some methods in the Java API have no return type, and throw a -<a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a> when an severe error -arises. There are some notable methods that do have a return value, and -can also throw an exception. The "get" methods in -<a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and -<a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> both return 0 when a get -succeeds, <a class="link" href="program_errorret.html#program_errorret.DB_NOTFOUND">DB_NOTFOUND</a> when the key is not found, and throw an -error when there is a severe error. This approach allows the programmer -to check for typical data-driven errors by watching return values -without special casing exceptions. -<p>An object of type <a class="ulink" href="../java/com/sleepycat/db/MemoryException.html" target="_top">MemoryException</a> is -thrown 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 -thrown 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 -subclass of <a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a>, is thrown when -there is an error that requires a recovery of the database using <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility.</p><p>An object of type <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a> -a standard Java Language exception, is thrown when there is an error in -method arguments.</p><p>An object of type <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/OutOfMemoryError.html" target="_top">OutOfMemoryError</a> is thrown -when the system cannot provide enough memory to complete the operation -(the ENOMEM system error on UNIX).</p></li> - <li>If there are embedded nulls in the <span class="bold"><strong>curslist</strong></span> argument for -<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>, -they will be treated as the end of the list of cursors, even if you -may have allocated a longer array. Fill in all the cursors in your -array unless you intend to cut it short.</li> - <li>If you are using custom class loaders in your application, make sure -that the Berkeley DB classes are loaded by the system class loader, not a -custom class loader. This is due to a JVM bug that can cause an access -violation during finalization (see the bug 4238486 in Sun Microsystem's -Java Bug Database).</li> + <li> + The Java runtime does not automatically close + Berkeley DB objects on finalization. There are several + reasons for this. One is that finalization is generally + run only when garbage collection occurs, and there is no + guarantee that this occurs at all, even on exit. Allowing + specific Berkeley DB actions to occur in ways that cannot + be replicated seems wrong. Second, finalization of objects + may happen in an arbitrary order, so we would have to do + extra bookkeeping to make sure that everything was closed + in the proper order. The best word of advice is to always + do a close() for any matching open() call. Specifically, + the Berkeley DB package requires that you explicitly call + close on each individual <a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and <a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> object + that you opened. Your database + activity may not be synchronized to disk unless you do + so. + </li> + <li> + Some methods in the Java API have no return type, + and throw a <a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a> + when an severe error + arises. There are some notable methods that do have a + return value, and can also throw an exception. The "get" + methods in <a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and <a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> both + return 0 when a get succeeds, + <a class="link" href="program_errorret.html#program_errorret.DB_NOTFOUND">DB_NOTFOUND</a> + when the key is not found, and throw an error when there is a severe + error. This approach allows the programmer to check for typical data-driven + errors by watching return values without special casing + exceptions. + <p> + An object of type <a class="ulink" href="../java/com/sleepycat/db/MemoryException.html" target="_top"> + MemoryException</a> is thrown 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 thrown 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 subclass of + <a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top"> + DatabaseException</a>, is thrown when there + is an error that requires a recovery of the database + using <a href="../api_reference/C/db_recover.html" class="olink">db_recover</a> utility. + </p><p> + An object of type <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top"> + IllegalArgumentException</a> a standard Java + Language exception, is thrown when there is an error + in method arguments.</p><p> + An object of type <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/OutOfMemoryError.html" target="_top"> + OutOfMemoryError</a> is thrown when the + system cannot provide enough memory to complete the + operation (the ENOMEM system error on + UNIX). + </p></li> + <li> + If there are embedded nulls in the <span class="bold"><strong>curslist</strong></span> argument for <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>, they will be + treated as the end of the list of cursors, even if you may + have allocated a longer array. Fill in all the cursors in + your array unless you intend to cut it short. + </li> + <li> + If you are using custom class loaders in your + application, make sure that the Berkeley DB classes are + loaded by the system class loader, not a custom class + loader. This is due to a JVM bug that can cause an access + violation during finalization (see the bug 4238486 in Sun + Microsystem's Java Bug Database). + </li> </ol> </div> </div> |