1<!--$Id: apis.so,v 10.29 2003/10/18 19:15:57 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: Programmatic APIs</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<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Architecture</dl></b></td> 14<td align=right><a href="../arch/progmodel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../arch/script.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Programmatic APIs</b></p> 17<p>The Berkeley DB subsystems can be accessed through interfaces from multiple 18languages. Applications can use Berkeley DB via C, C++ or Java, as well as a 19variety of scripting languages such as Perl, Python, Ruby or Tcl. 20Environments can be shared among applications written by using any of 21these interfaces. For example, you might have a local server written 22in C or C++, a script for an administrator written in Perl or Tcl, and 23a Web-based user interface written in Java -- all sharing a single 24database environment.</p> 25<b>C</b> 26<p>The Berkeley DB library is written entirely in ANSI C. C applications use a 27single include file:</p> 28<blockquote><pre>#include <db.h></pre></blockquote> 29<b>C++</b> 30<p>The C++ classes provide a thin wrapper around the C API, with the major 31advantages being improved encapsulation and an optional exception 32mechanism for errors. C++ applications use a single include file:</p> 33<blockquote><pre>#include <db_cxx.h></pre></blockquote> 34<p>The classes and methods are named in a fashion that directly corresponds 35to structures and functions in the C interface. Likewise, arguments to 36methods appear in the same order as the C interface, except to remove the 37explicit <b>this</b> pointer. The #defines used for flags are identical 38between the C and C++ interfaces.</p> 39<p>As a rule, each C++ object has exactly one structure from the underlying 40C API associated with it. The C structure is allocated with each 41constructor call and deallocated with each destructor call. Thus, the 42rules the user needs to follow in allocating and deallocating structures 43are the same between the C and C++ interfaces.</p> 44<p>To ensure portability to many platforms, both new and old, Berkeley DB makes 45as few assumptions as possible about the C++ compiler and library. For 46example, it does not expect STL, templates, or namespaces to be 47available. The newest C++ feature used is exceptions, which are used 48liberally to transmit error information. Even the use of exceptions 49can be disabled at runtime.</p> 50<b>Java</b> 51<p>The Java classes provide a layer around the C API that is almost identical 52to the C++ layer. The classes and methods are, for the most part 53identical to the C++ layer. Berkeley DB constants and #defines are represented as 54"static final int" values. Error conditions are communicated as Java 55exceptions.</p> 56<p>As in C++, each Java object has exactly one structure from the underlying 57C API associated with it. The Java structure is allocated with each 58constructor or open call, but is deallocated only by the Java garbage 59collector. Because the timing of garbage collection is not predictable, 60applications should take care to do a close when finished with any object 61that has a close method.</p> 62<b>Dbm/Ndbm, Hsearch</b> 63<p>Berkeley DB supports the standard UNIX <a href="../../api_c/dbm.html">dbm</a>, <a href="../../api_c/dbm.html">ndbm</a>, and 64<a href="../../api_c/hsearch.html">hsearch</a> interfaces. After including a new header file and 65recompiling, programs will run orders of magnitude faster, and 66underlying databases can grow as large as necessary. Also, historic 67<a href="../../api_c/dbm.html">dbm</a> and <a href="../../api_c/dbm.html">ndbm</a> applications can fail once some number of 68entries are inserted into the database, in which the number depends on 69the effectiveness of the internal hashing function on the particular 70data set. This is not a problem with Berkeley DB.</p> 71<table width="100%"><tr><td><br></td><td align=right><a href="../arch/progmodel.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../arch/script.html"><img src="../../images/next.gif" alt="Next"></a> 72</td></tr></table> 73<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 74</body> 75</html> 76