###

Berkeley DB Reference Guide:
  Java API Tutorial

### Introduction to the Java API tutorial

The Java API is a Java persistence framework based on the standard Java collections API. This tutorial illustrates the use of the Java API with a shipment database, a familiar example from classic database texts.

The examples illustrate the following concepts of the Java API:

- Record bindings and formats
- The database environment
- Database stores that contain key/value records
- Database indices that contain secondary keys and foreign keys
- Java collections for accessing stores and indices
- Transactions used to commit or undo database changes

The examples build on each other, but at the same time the source code for each example stands alone.

- Basic - The shipment program
- Index - Indices and foreign keys
- Entity - Combining the key and value in a single object
- Tuple - Compact ordered keys
- Serializable Entity - One serializable class for entities and values

The shipment database consists of three database stores: the part store, the supplier store, and the shipment store. Each store contains a number of records, and each record consists of a key and a value.

Store | Key | Value
--- | --- | ---
Part | Part Number | Name, Color, Weight, City
Supplier | Supplier Number | Name, Status, City
Shipment | Part Number, Supplier Number | Quantity

In the example programs, Java classes containing the fields above are defined for the key and value of each store: PartKey, PartValue, SupplierKey, SupplierValue, ShipmentKey and ShipmentValue. In addition, because the Part's Weight field is itself composed of two fields -- the weight value and the unit of measure -- it is represented by a separate Weight class. These classes will be defined in the first example program.

In general the Java API uses formats and bindings to describe how Java objects are stored. A format defines the stored data syntax, and a binding defines the mapping between a Java object and the stored data. The example programs show how to create different types of formats and bindings, and explains the characteristics of each type.

The following tables contain the record values that are used in all the example programs in the tutorial.

### Part Records

Number | Name | Color | Weight | City
--- | --- | --- | --- | ---
P1 | Nut | Red | 12.0 grams | London
P2 | Bolt | Green | 17.0 grams | Paris
P3 | Screw | Blue | 17.0 grams | Rome
P4 | Screw | Red | 14.0 grams | London
P5 | Cam | Blue | 12.0 grams | Paris
P6 | Cog | Red | 19.0 grams | London

### Supplier Records

Number | Name | Status | City
--- | --- | --- | ---
S1 | Smith | 20 | London
S2 | Jones | 10 | Paris
S3 | Blake | 30 | Paris
S4 | Clark | 20 | London
S5 | Adams | 30 | Athens

### Shipment Records

Part Number | Supplier Number | Quantity
--- | --- | ---
P1 | S1 | 300
P1 | S2 | 300
P2 | S1 | 200
P2 | S2 | 400
P2 | S3 | 200
P2 | S4 | 200
P3 | S1 | 400
P4 | S1 | 200
P4 | S4 | 300
P5 | S1 | 100
P5 | S4 | 400
P6 | S1 | 100

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.