mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-17 09:36:24 +00:00
454 lines
13 KiB
HTML
454 lines
13 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Chapter 2. The Basic Program</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Collections Tutorial" />
|
||
<link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" />
|
||
<link rel="prev" href="tutorialintroduction.html" title="Tutorial Introduction" />
|
||
<link rel="next" href="opendbenvironment.html" title="Opening and Closing the Database Environment" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.2</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Chapter 2.
|
||
The Basic Program
|
||
</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td>
|
||
<th width="60%" align="center"> </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="opendbenvironment.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="chapter" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title"><a id="BasicProgram"></a>Chapter 2.
|
||
The Basic Program
|
||
</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<p>
|
||
<b>Table of Contents</b>
|
||
</p>
|
||
<dl>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="BasicProgram.html#keyandvalueclasses">
|
||
Defining Serialized Key and Value Classes
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="opendbenvironment.html">
|
||
Opening and Closing the Database Environment
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="openclasscatalog.html">
|
||
Opening and Closing the Class Catalog
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="opendatabases.html">
|
||
Opening and Closing Databases
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="createbindingscollections.html">
|
||
Creating Bindings and Collections
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="implementingmain.html">
|
||
Implementing the Main Program
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="usingtransactions.html">
|
||
Using Transactions
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="addingdatabaseitems.html">
|
||
Adding Database Items
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="retrievingdatabaseitems.html">
|
||
Retrieving Database Items
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect1">
|
||
<a href="handlingexceptions.html">
|
||
Handling Exceptions
|
||
</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
The Basic example is a minimal implementation of the shipment
|
||
program. It writes and reads the part, supplier and shipment
|
||
databases.
|
||
</p>
|
||
<p>
|
||
The complete source of the final version of the example program
|
||
is included in the Berkeley DB distribution.
|
||
</p>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="keyandvalueclasses"></a>
|
||
Defining Serialized Key and Value Classes
|
||
</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The key and value classes for each type of shipment record —
|
||
Parts, Suppliers and Shipments — are defined as ordinary Java
|
||
classes. In this example the serialized form of the key and value
|
||
objects is stored directly in the database. Therefore these classes
|
||
must implement the standard Java java.io.Serializable interface. A
|
||
compact form of Java serialization is used that does not duplicate
|
||
the class description in each record. Instead the class
|
||
descriptions are stored in the class catalog store, which is
|
||
described in the next section. But in all other respects, standard
|
||
Java serialization is used.
|
||
</p>
|
||
<p>
|
||
An important point is that instances of these classes are passed
|
||
and returned by value, not by reference, when they are stored and
|
||
retrieved from the database. This means that changing a key or
|
||
value object does not automatically change the database. The object
|
||
must be explicitly stored in the database after changing it. To
|
||
emphasize this point the key and value classes defined here have no
|
||
field setter methods. Setter methods can be defined, but it is
|
||
important to remember that calling a setter method will not cause
|
||
the change to be stored in the database. How to store and retrieve
|
||
objects in the database will be described later.
|
||
</p>
|
||
<p>
|
||
Each key and value class contains a toString method that is used
|
||
to output the contents of the object in the example program. This
|
||
is meant for illustration only and is not required for database
|
||
objects in general.
|
||
</p>
|
||
<p>
|
||
Notice that the key and value classes defined below do not
|
||
contain any references to <code class="literal">com.sleepycat</code> packages. An
|
||
important characteristic of these classes is that they are
|
||
independent of the database. Therefore, they may be easily used in
|
||
other contexts and may be defined in a way that is compatible with
|
||
other tools and libraries.
|
||
</p>
|
||
<p>
|
||
The <code class="classname">PartKey</code> class contains only the Part's Number field.
|
||
</p>
|
||
<p>
|
||
Note that <code class="classname">PartKey</code> (as well as <code class="classname">SupplierKey</code> below)
|
||
contain only a single String field. Instead of defining a specific
|
||
class for each type of key, the String class by itself could have
|
||
been used. Specific key classes were used to illustrate strong
|
||
typing and for consistency in the example. The use of a plain
|
||
String as an index key is illustrated in the next example program.
|
||
It is up to the developer to use either primitive Java classes such
|
||
as String and Integer, or strongly typed classes. When
|
||
there is the possibility that fields will be added later to a key
|
||
or value, a specific class should be used.
|
||
|
||
</p>
|
||
<a id="cb_partkey"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class PartKey implements Serializable
|
||
{
|
||
private String number;
|
||
|
||
public PartKey(String number) {
|
||
this.number = number;
|
||
}
|
||
|
||
public final String getNumber() {
|
||
return number;
|
||
}
|
||
|
||
public String toString() {
|
||
return "[PartKey: number=" + number + ']';
|
||
}
|
||
}</code></strong> </pre>
|
||
<p>
|
||
The <code class="classname">PartData</code> class contains the Part's Name, Color,
|
||
Weight and City fields.
|
||
</p>
|
||
<a id="cb_partdata"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class PartData implements Serializable
|
||
{
|
||
private String name;
|
||
private String color;
|
||
private Weight weight;
|
||
private String city;
|
||
|
||
public PartData(String name, String color, Weight weight, String city)
|
||
{
|
||
this.name = name;
|
||
this.color = color;
|
||
this.weight = weight;
|
||
this.city = city;
|
||
}
|
||
|
||
public final String getName()
|
||
{
|
||
return name;
|
||
}
|
||
|
||
public final String getColor()
|
||
{
|
||
return color;
|
||
}
|
||
|
||
public final Weight getWeight()
|
||
{
|
||
return weight;
|
||
}
|
||
|
||
public final String getCity()
|
||
{
|
||
return city;
|
||
}
|
||
|
||
public String toString()
|
||
{
|
||
return "[PartData: name=" + name +
|
||
" color=" + color +
|
||
" weight=" + weight +
|
||
" city=" + city + ']';
|
||
}
|
||
}</code></strong> </pre>
|
||
<p>
|
||
The <code class="classname">Weight</code> class is also defined here, and is used as the
|
||
type of the Part's Weight field. Just as in standard Java
|
||
serialization, nothing special is needed to store nested objects as
|
||
long as they are all Serializable.
|
||
</p>
|
||
<a id="cb_weight"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class Weight implements Serializable
|
||
{
|
||
public final static String GRAMS = "grams";
|
||
public final static String OUNCES = "ounces";
|
||
|
||
private double amount;
|
||
private String units;
|
||
|
||
public Weight(double amount, String units)
|
||
{
|
||
this.amount = amount;
|
||
this.units = units;
|
||
}
|
||
|
||
public final double getAmount()
|
||
{
|
||
return amount;
|
||
}
|
||
|
||
public final String getUnits()
|
||
{
|
||
return units;
|
||
}
|
||
|
||
public String toString()
|
||
{
|
||
return "[" + amount + ' ' + units + ']';
|
||
}
|
||
}</code></strong> </pre>
|
||
<p>
|
||
The <code class="classname">SupplierKey</code> class contains the Supplier's Number
|
||
field.
|
||
</p>
|
||
<a id="cb_supplierkey"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class SupplierKey implements Serializable
|
||
{
|
||
private String number;
|
||
|
||
public SupplierKey(String number)
|
||
{
|
||
this.number = number;
|
||
}
|
||
|
||
public final String getNumber()
|
||
{
|
||
return number;
|
||
}
|
||
|
||
public String toString()
|
||
{
|
||
return "[SupplierKey: number=" + number + ']';
|
||
}
|
||
}</code></strong> </pre>
|
||
<p>
|
||
The <code class="classname">SupplierData</code> class contains the Supplier's Name,
|
||
Status and City fields.
|
||
</p>
|
||
<a id="cb_supplierdata"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class SupplierData implements Serializable
|
||
{
|
||
private String name;
|
||
private int status;
|
||
private String city;
|
||
|
||
public SupplierData(String name, int status, String city)
|
||
{
|
||
this.name = name;
|
||
this.status = status;
|
||
this.city = city;
|
||
}
|
||
|
||
public final String getName()
|
||
{
|
||
return name;
|
||
}
|
||
|
||
public final int getStatus()
|
||
{
|
||
return status;
|
||
}
|
||
|
||
public final String getCity()
|
||
{
|
||
return city;
|
||
}
|
||
|
||
public String toString()
|
||
{
|
||
return "[SupplierData: name=" + name +
|
||
" status=" + status +
|
||
" city=" + city + ']';
|
||
}
|
||
}</code></strong>
|
||
</pre>
|
||
<p>
|
||
The <code class="classname">ShipmentKey</code> class contains the keys of both the Part
|
||
and Supplier.
|
||
</p>
|
||
<a id="cb_shipmentkey"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class ShipmentKey implements Serializable
|
||
{
|
||
private String partNumber;
|
||
private String supplierNumber;
|
||
|
||
public ShipmentKey(String partNumber, String supplierNumber)
|
||
{
|
||
this.partNumber = partNumber;
|
||
this.supplierNumber = supplierNumber;
|
||
}
|
||
|
||
public final String getPartNumber()
|
||
{
|
||
return partNumber;
|
||
}
|
||
|
||
public final String getSupplierNumber()
|
||
{
|
||
return supplierNumber;
|
||
}
|
||
|
||
public String toString()
|
||
{
|
||
return "[ShipmentKey: supplier=" + supplierNumber +
|
||
" part=" + partNumber + ']';
|
||
}
|
||
}</code></strong> </pre>
|
||
<p>
|
||
The <code class="classname">ShipmentData</code> class contains only the Shipment's
|
||
Quantity field. Like <code class="classname">PartKey</code> and <code class="classname">SupplierKey</code>,
|
||
<code class="classname">ShipmentData</code> contains only a single primitive field.
|
||
Therefore the Integer class could have been used instead of
|
||
defining a specific value class.
|
||
</p>
|
||
<a id="cb_shipmentdata"></a>
|
||
<pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
|
||
|
||
public class ShipmentData implements Serializable
|
||
{
|
||
private int quantity;
|
||
|
||
public ShipmentData(int quantity)
|
||
{
|
||
this.quantity = quantity;
|
||
}
|
||
|
||
public final int getQuantity()
|
||
{
|
||
return quantity;
|
||
}
|
||
|
||
public String toString()
|
||
{
|
||
return "[ShipmentData: quantity=" + quantity + ']';
|
||
}
|
||
}</code></strong> </pre>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td>
|
||
<td width="20%" align="center"> </td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="opendbenvironment.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Tutorial Introduction </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top">
|
||
Opening and Closing the Database Environment
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|