← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/ref/java/program.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/ref/java/program.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB Reference Guide: Java programming notes</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<table width="100%"><tr valign=top>
13
 
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Java API</dl></h3></td>
14
 
<td align=right><a href="../../ref/java/compat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/faq.html"><img src="../../images/next.gif" alt="Next"></a>
15
 
</td></tr></table>
16
 
<p>
17
 
<h1 align=center>Java programming notes</h1>
18
 
<p>The Java API closely parallels the Berkeley DB C++ and C interfaces.  If you
19
 
are currently using either of those APIs, there will be very little to
20
 
surprise you in the Java API.  We have even taken care to make the names
21
 
of classes, constants, methods and arguments identical, where possible,
22
 
across all three APIs.
23
 
<p><ol>
24
 
<p><li>The Java runtime does not automatically close Berkeley DB objects on
25
 
finalization.  There are several reasons for this.  One is that
26
 
finalization is generally run only when garbage collection occurs, and
27
 
there is no guarantee that this occurs at all, even on exit.  Allowing
28
 
specific Berkeley DB actions to occur in ways that cannot be replicated seems
29
 
wrong.  Second, finalization of objects may happen in an arbitrary
30
 
order, so we would have to do extra bookkeeping to make sure that
31
 
everything was closed in the proper order.  The best word of advice is
32
 
to always do a close() for any matching open() call.  Specifically, the
33
 
Berkeley DB package requires that you explicitly call close on each individual
34
 
<a href="../../api_java/db_class.html">Db</a> and <a href="../../api_java/dbc_class.html">Dbc</a> object that you opened.  Your database
35
 
activity may not be synchronized to disk unless you do so.
36
 
<p><li>Some methods in the Java API have no return type, and throw a
37
 
<a href="../../api_java/except_class.html">DbException</a> when an severe error arises.  There are some notable
38
 
methods that do have a return value, and can also throw an exception.
39
 
<a href="../../api_java/db_get.html">Db.get</a> and <a href="../../api_java/dbc_get.html">Dbc.get</a> both return 0 when a get succeeds,
40
 
return <a href="../../ref/program/errorret.html#DB_NOTFOUND">Db.DB_NOTFOUND</a> when the key is not found, and throw an error
41
 
when there is a severe error.  This approach allows the programmer to
42
 
check for typical data-driven errors by watching return values without
43
 
special casing exceptions.
44
 
<p>An object of type <a href="../../api_java/deadlock_class.html">DbDeadlockException</a> is thrown when a deadlock
45
 
would occur.
46
 
<p>An object of type <a href="../../api_java/memp_class.html">DbMemoryException</a> is thrown when the system
47
 
cannot provide enough memory to complete the operation (the ENOMEM
48
 
system error on UNIX).
49
 
<p>An object of type <a href="../../api_java/runrec_class.html">DbRunRecoveryException</a>, a subclass of
50
 
<a href="../../api_java/except_class.html">DbException</a>, is thrown when there is an error that requires a
51
 
recovery of the database using <a href="../../utility/db_recover.html">db_recover</a>.
52
 
<p><li>There is no class corresponding to the C++ DbMpoolFile class in the Berkeley DB
53
 
Java API.  There is a subset of the memp_XXX methods in the <a href="../../api_java/env_class.html">DbEnv</a>
54
 
class.  This has been provided to allow you to perform certain
55
 
administrative actions on underlying memory pools opened as a consequence
56
 
of <a href="../../api_java/env_open.html">DbEnv.open</a>.  Direct access to other memory pool functionality
57
 
is not appropriate for the Java environment.
58
 
<p><li>Berkeley DB always turns on the <a href="../../api_java/env_open.html#DB_THREAD">Db.DB_THREAD</a> flag because
59
 
threads are expected in Java.
60
 
<p><li>If there are embedded null strings in the <b>curslist</b> argument for
61
 
<a href="../../api_java/db_join.html">Db.join</a>, they will be treated as the end of the list of
62
 
cursors, even if you may have allocated a longer array.  Fill in all
63
 
the strings in your array unless you intend to cut it short.
64
 
<p><li>The callback installed for <a href="../../api_java/env_set_errcall.html">DbEnv.set_errcall</a> will run in the same
65
 
thread as the caller to <a href="../../api_java/env_set_errcall.html">DbEnv.set_errcall</a>.  Make sure that thread
66
 
remains running until your application exits or until <a href="../../api_java/env_close.html">DbEnv.close</a>
67
 
is called.
68
 
<p><li>If you are using custom class loaders in your application, make sure
69
 
that the Berkeley DB classes are loaded by the system class loader, not a
70
 
custom class loader. This is due to a JVM bug that can cause an access
71
 
violation during finalization (see the bug 4238486 in Sun Microsystem's
72
 
Java Bug Database).
73
 
</ol>
74
 
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/java/compat.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/java/faq.html"><img src="../../images/next.gif" alt="Next"></a>
75
 
</td></tr></table>
76
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
77
 
</body>
78
 
</html>