docs/programmer_reference/java_program.html

   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 xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Java programming notes</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="java_compat.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 5.
  26                 Java API
  27         </th>
  28           <td width="20%" align="right"> <a accesskey="n" href="java_faq.html">Next</a></td>
  29         </tr>
  30       </table>
  31       <hr />
  32     </div>
  33     <div class="sect1" lang="en" xml:lang="en">
  34       <div class="titlepage">
  35         <div>
  36           <div>
  37             <h2 class="title" style="clear: both"><a id="java_program"></a>Java programming notes</h2>
  38           </div>
  39         </div>
  40       </div>
  41       <p>Although the Java API parallels the Berkeley DB C++/C interface in many ways,
  42 it differs where the Java language requires.  For example, the handle
  43 method names are camel-cased and conform to Java naming patterns.  (The
  44 C++/C method names are currently provided, but are deprecated.)</p>
  45       <div class="orderedlist">
  46         <ol type="1">
  47           <li>The Java runtime does not automatically close Berkeley DB objects on
  48 finalization.  There are several reasons for this.  One is that
  49 finalization is generally run only when garbage collection occurs, and
  50 there is no guarantee that this occurs at all, even on exit.  Allowing
  51 specific Berkeley DB actions to occur in ways that cannot be replicated seems
  52 wrong.  Second, finalization of objects may happen in an arbitrary
  53 order, so we would have to do extra bookkeeping to make sure that
  54 everything was closed in the proper order.  The best word of advice is
  55 to always do a close() for any matching open() call.  Specifically, the
  56 Berkeley DB package requires that you explicitly call close on each individual
  57 <a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and
  58 <a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> object that you opened.  Your database
  59 activity may not be synchronized to disk unless you do so.</li>
  60           <li>Some methods in the Java API have no return type, and throw a
  61 <a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a> when an severe error
  62 arises.  There are some notable methods that do have a return value, and
  63 can also throw an exception.  The "get" methods in
  64 <a class="ulink" href="../java/com/sleepycat/db/Database.html" target="_top">Database</a> and
  65 <a class="ulink" href="../java/com/sleepycat/db/Cursor.html" target="_top">Cursor</a> both return 0 when a get
  66 succeeds, <a class="link" href="program_errorret.html#program_errorret.DB_NOTFOUND">DB_NOTFOUND</a> when the key is not found, and throw an
  67 error when there is a severe error.  This approach allows the programmer
  68 to check for typical data-driven errors by watching return values
  69 without special casing exceptions.
  70 <p>An object of type <a class="ulink" href="../java/com/sleepycat/db/MemoryException.html" target="_top">MemoryException</a> is
  71 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
  72 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
  73 subclass of <a class="ulink" href="../java/com/sleepycat/db/DatabaseException.html" target="_top">DatabaseException</a>, is thrown when
  74 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>
  75 a standard Java Language exception, is thrown when there is an error in
  76 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
  77 when the system cannot provide enough memory to complete the operation
  78 (the ENOMEM system error on UNIX).</p></li>
  79           <li>If there are embedded nulls in the <span class="bold"><strong>curslist</strong></span> argument for
  80 <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>,
  81 they will be treated as the end of the list of cursors, even if you
  82 may have allocated a longer array.  Fill in all the cursors in your
  83 array unless you intend to cut it short.</li>
  84           <li>If you are using custom class loaders in your application, make sure
  85 that the Berkeley DB classes are loaded by the system class loader, not a
  86 custom class loader. This is due to a JVM bug that can cause an access
  87 violation during finalization (see the bug 4238486 in Sun Microsystem's
  88 Java Bug Database).</li>
  89         </ol>
  90       </div>
  91     </div>
  92     <div class="navfooter">
  93       <hr />
  94       <table width="100%" summary="Navigation footer">
  95         <tr>
  96           <td width="40%" align="left"><a accesskey="p" href="java_compat.html">Prev</a> </td>
  97           <td width="20%" align="center">
  98             <a accesskey="u" href="java.html">Up</a>
  99           </td>
 100           <td width="40%" align="right"> <a accesskey="n" href="java_faq.html">Next</a></td>
 101         </tr>
 102         <tr>
 103           <td width="40%" align="left" valign="top">Compatibility </td>
 104           <td width="20%" align="center">
 105             <a accesskey="h" href="index.html">Home</a>
 106           </td>
 107           <td width="40%" align="right" valign="top"> Java FAQ</td>
 108         </tr>
 109       </table>
 110     </div>
 111   </body>
 112 </html>