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>Programmatic APIs</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="arch.html" title="Chapter��8.�� Berkeley DB Architecture" /> 11 <link rel="prev" href="arch_progmodel.html" title="Programming model" /> 12 <link rel="next" href="arch_script.html" title="Scripting languages" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Programmatic APIs</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="arch_progmodel.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��8.�� 23 Berkeley DB Architecture 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="arch_script.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="arch_apis"></a>Programmatic APIs</h2> 35 </div> 36 </div> 37 </div> 38 <div class="toc"> 39 <dl> 40 <dt> 41 <span class="sect2"> 42 <a href="arch_apis.html#id1603628">C</a> 43 </span> 44 </dt> 45 <dt> 46 <span class="sect2"> 47 <a href="arch_apis.html#id1603668">C++</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect2"> 52 <a href="arch_apis.html#id1603511">STL</a> 53 </span> 54 </dt> 55 <dt> 56 <span class="sect2"> 57 <a href="arch_apis.html#id1603399">Java</a> 58 </span> 59 </dt> 60 <dt> 61 <span class="sect2"> 62 <a href="arch_apis.html#id1603369">Dbm/Ndbm, Hsearch</a> 63 </span> 64 </dt> 65 </dl> 66 </div> 67 <p>The Berkeley DB subsystems can be accessed through interfaces from multiple 68languages. Applications can use Berkeley DB via C, C++ or Java, as well as a 69variety of scripting languages such as Perl, Python, Ruby or Tcl. 70Environments can be shared among applications written by using any of 71these interfaces. For example, you might have a local server written 72in C or C++, a script for an administrator written in Perl or Tcl, and 73a Web-based user interface written in Java -- all sharing a single 74database environment.</p> 75 <div class="sect2" lang="en" xml:lang="en"> 76 <div class="titlepage"> 77 <div> 78 <div> 79 <h3 class="title"><a id="id1603628"></a>C</h3> 80 </div> 81 </div> 82 </div> 83 <p>The Berkeley DB library is written entirely in ANSI C. C applications use a 84single include file:</p> 85 <pre class="programlisting">#include <db.h></pre> 86 </div> 87 <div class="sect2" lang="en" xml:lang="en"> 88 <div class="titlepage"> 89 <div> 90 <div> 91 <h3 class="title"><a id="id1603668"></a>C++</h3> 92 </div> 93 </div> 94 </div> 95 <p>The C++ classes provide a thin wrapper around the C API, with the major 96advantages being improved encapsulation and an optional exception 97mechanism for errors. C++ applications use a single include file:</p> 98 <pre class="programlisting">#include <db_cxx.h></pre> 99 <p>The classes and methods are named in a fashion that directly corresponds 100to structures and functions in the C interface. Likewise, arguments to 101methods appear in the same order as the C interface, except to remove the 102explicit <span class="bold"><strong>this</strong></span> pointer. The #defines used for flags are identical 103between the C and C++ interfaces.</p> 104 <p>As a rule, each C++ object has exactly one structure from the underlying 105C API associated with it. The C structure is allocated with each 106constructor call and deallocated with each destructor call. Thus, the 107rules the user needs to follow in allocating and deallocating structures 108are the same between the C and C++ interfaces.</p> 109 <p>To ensure portability to many platforms, both new and old, Berkeley DB makes 110as few assumptions as possible about the C++ compiler and library. For 111example, it does not expect STL, templates, or namespaces to be 112available. The newest C++ feature used is exceptions, which are used 113liberally to transmit error information. Even the use of exceptions 114can be disabled at runtime.</p> 115 </div> 116 <div class="sect2" lang="en" xml:lang="en"> 117 <div class="titlepage"> 118 <div> 119 <div> 120 <h3 class="title"><a id="id1603511"></a>STL</h3> 121 </div> 122 </div> 123 </div> 124 <p> 125dbstl is an C++ STL style API for Berkeley DB, based on the C++ API above. With it, you can store data/objects of any type into 126or retrieve them from Berkeley DB databases as if you are using C++ STL containers. The full functionality 127of Berkeley DB can still be utilized via dbstl with little performance overhead, e.g. you can use all transaction and/or replication functionality of Berkeley DB. 128 129</p> 130 <p> 131dbstl container/iterator class templates reside in header files dbstl_vector.h, dbstl_map.h and dbstl_set.h. 132 133Among them, dbstl_vector.h contains dbstl::db_vector and its iterators; 134dbstl_map.h contains dbstl::db_map, dbstl::db_multimap and their iterators; dbstl_set.h contains dbstl::db_set and dbstl::db_multiset and their iterators. You should 135include needed header file(s) to use the container/iterator. Note that we don't use the file name with no extention --- To use dbstl::db_vector, you should do this: 136</p> 137 <pre class="programlisting">#include "dbstl_vector.h"</pre> 138 <p> 139rather than this: 140</p> 141 <pre class="programlisting">#include "dbstl_vector"</pre> 142 <p> 143And these header files reside in "stl" directory inside Berkeley DB source root directory. If you have installed 144Berkeley DB, they are also available in the "include" directory in the directory where Berkeley DB is installed. 145</p> 146 <p> 147Apart from the above three header files, you may also need to include db_exception.h and db_utility.h files. The db_exception.h file contains all exception classes of dbstl, which 148integrate seamlessly with Berkeley DB C++ API exceptions and C++ standard exception classes in std namespace. And the db_utility.h file contains the DbstlElemTraits which helps you 149to store complex objects. These five header files are all that you need to include in order to make use of dbstl. 150</p> 151 <p> 152All symbols of dbstl, including classes, class templates, global functions, etc, reside in the namespace "dbstl", so in order to use them, you may also want to do this: 153</p> 154 <pre class="programlisting">using namespace dbstl;</pre> 155 <p> 156The dbstl library is always at the same place where Berkeley DB library is located, you will need to build it and link with it to use dbstl. 157</p> 158 <p> 159While making use of dbstl, you will probably want to create environment or databases directly, or set/get configurations to Berkeley DB environment or databases, etc. You are allowed to do so via Berkeley DB C/C++ API. 160</p> 161 </div> 162 <div class="sect2" lang="en" xml:lang="en"> 163 <div class="titlepage"> 164 <div> 165 <div> 166 <h3 class="title"><a id="id1603399"></a>Java</h3> 167 </div> 168 </div> 169 </div> 170 <p>The Java classes provide a layer around the C API that is almost identical 171to the C++ layer. The classes and methods are, for the most part 172identical to the C++ layer. Berkeley DB constants and #defines are represented as 173"static final int" values. Error conditions are communicated as Java 174exceptions.</p> 175 <p>As in C++, each Java object has exactly one structure from the underlying 176C API associated with it. The Java structure is allocated with each 177constructor or open call, but is deallocated only by the Java garbage 178collector. Because the timing of garbage collection is not predictable, 179applications should take care to do a close when finished with any object 180that has a close method.</p> 181 </div> 182 <div class="sect2" lang="en" xml:lang="en"> 183 <div class="titlepage"> 184 <div> 185 <div> 186 <h3 class="title"><a id="id1603369"></a>Dbm/Ndbm, Hsearch</h3> 187 </div> 188 </div> 189 </div> 190 <p>Berkeley DB supports the standard UNIX <a href="../api_reference/C/dbm.html" class="olink">dbm</a> and <a href="../api_reference/C/hsearch.html" class="olink">hsearch</a> interfaces. After including a new header file and recompiling, programs will run orders of magnitude faster, and underlying databases can grow as large as necessary. Also, historic <a href="../api_reference/C/dbm.html" class="olink">dbm</a> applications can fail once some number of entries are inserted into the database, in which the number depends on the effectiveness of the internal hashing function on the particular data set. This is not a problem with Berkeley DB.</p> 191 </div> 192 </div> 193 <div class="navfooter"> 194 <hr /> 195 <table width="100%" summary="Navigation footer"> 196 <tr> 197 <td width="40%" align="left"><a accesskey="p" href="arch_progmodel.html">Prev</a>��</td> 198 <td width="20%" align="center"> 199 <a accesskey="u" href="arch.html">Up</a> 200 </td> 201 <td width="40%" align="right">��<a accesskey="n" href="arch_script.html">Next</a></td> 202 </tr> 203 <tr> 204 <td width="40%" align="left" valign="top">Programming model��</td> 205 <td width="20%" align="center"> 206 <a accesskey="h" href="index.html">Home</a> 207 </td> 208 <td width="40%" align="right" valign="top">��Scripting languages</td> 209 </tr> 210 </table> 211 </div> 212 </body> 213</html> 214