This appendix contains information useful to the collections programmer that is too detailed to easily fit into the format of a tutorial. Specifically, this appendix contains the following information:
Data bindings determine how keys and values are represented as stored data (byte arrays) in the database, and how stored data is converted to and from Java objects.
The selection of data bindings is, in general, independent of the selection of access methods and collection views. In other words, any binding can be used with any access method or collection. One exception to this rule is described under Record Number Bindings below.
In this document, bindings are described in the context of their use for stored data in a database. However, bindings may also be used independently of a database to operate on an arbitrary byte array. This allows using bindings when data is to be written to a file or sent over a network, for example.
For the key and value of each stored collection, you may select one of the following types of bindings.
| Binding Format | Ordered | Description |
|---|---|---|
| SerialBinding | No | The data is stored using a compact form of Java serialization, where the class descriptions are stored separately in a catalog database. Arbitrary Java objects are supported. |
| TupleBinding | Yes | The data is stored using a series of fixed length primitive values or zero terminated character arrays (strings). Class/type evolution is not supported. |
| RecordNumberBinding | Yes | The data is a 32-bit integer stored in a platform-dependent format. |
| Custom binding format | User-defined | The data storage format and ordering is determined by the custom binding implementation. |
As shown in the table above, the tuple format supports built-in ordering (without specifying a custom comparator), while the serial format does not. This means that when a specific key order is needed, tuples should be used instead of serial data. Alternatively, a custom Btree comparator should be specified using DatabaseConfig.setBtreeComparator(). Note that a custom Btree comparator will usually execute more slowly than the default byte-by-byte comparison. This makes using tuples an attractive option, since they provide ordering along with optimal performance.
The tuple binding uses less space and executes faster than the serial binding. But once a tuple is written to a database, the order of fields in the tuple may not be changed and fields may not be deleted. The only type evolution allowed is the addition of fields at the end of the tuple, and this must be explicitly supported by the custom binding implementation.
The serial binding supports the full generality of Java serialization including type evolution. But serialized data can only be accessed by Java applications, its size is larger, and its bindings are slower to execute.
Any use of an access method with record number keys, and therefore any use of a stored list view, requires using RecordNumberBinding as the key binding. Since Berkeley DB stores record number keys using a platform-dependent byte order, RecordNumberBinding is needed to store record numbers properly. See logical record numbers in the Berkeley DB Programmer's Reference Guide for more information on storing DB record numbers.
You may not use RecordNumberBinding except with record number keys, as determined by the access method. Using RecordNumberBinding in other cases will create a database that is not portable between platforms. When constructing the stored collection, the DB Java Collections API will throw an IllegalArgumentException in such cases.
There are two types of binding interfaces. Simple entry bindings implement the EntryBinding interface and can be used for key or value objects. Entity bindings implement the EntityBinding interface and are used for combined key and value objects called entities.
Simple entry bindings map between the key or value data stored by Berkeley DB and a key or value object. This is a simple one-to-one mapping.
Simple entry bindings are easy to implement and in some cases require no coding. For example, a SerialBinding can be used for keys or values without writing any additional code. A tuple binding for a single-item tuple can also be used without writing any code; see the TupleBinding.getPrimitiveBinding method.
Entity bindings must divide an entity object into its key and value data, and then combine the key and value data to re-create the entity object. This is a two-to-one mapping.
Entity bindings are useful when a stored application object naturally has its primary key as a property, which is very common. For example, an Employee object would naturally have an EmployeeNumber property (its primary key) and an entity binding would then be needed. Of course, entity bindings are more complex to implement, especially if their key and data formats are different.
Note that even when an entity binding is used a key binding is also usually needed. For example, a key binding is used to create key objects that are passed to the Map.get() method. A key object is passed to this method even though it may return an entity that also contains the key.
There are two ways to implement bindings. The first way is to create a binding class that implements one of the two binding interfaces, EntryBinding or EntityBinding. For tuple bindings and serial bindings there are a number of abstract classes that make this easier. For example, you can extend TupleBinding to implement a simple binding for a tuple key or value. Abstract classes are also provided for entity bindings and are named after the format names of the key and value. For example, you can extend TupleSerialBinding to implement an entity binding with a tuple key and serial value.
Another way to implement bindings is with marshalling interfaces. These are interfaces which perform the binding operations and are implemented by the key, value or entity classes themselves. With marshalling you use a binding which calls the marshalling interface and you implement the marshalling interface for each key, value or entity class. For example, you can use TupleMarshalledBinding along with key or value classes that implement the MarshalledTupleEntry interface.
Bindings are specified whenever a stored collection is created. A key binding must be specified for map, key set and entry set views. A value binding or entity binding must be specified for map, value set and entry set views.
Any number of bindings may be created for the same stored data. This allows multiple views over the same data. For example, a tuple might be bound to an array of values or to a class with properties for each object.
It is important to be careful of bindings that only use a subset of the stored data. This can be useful to simplify a view or to hide information that should not be accessible. However, if you write records using these bindings you may create stored data that is invalid from the application's point of view. It is up to the application to guard against this by creating a read-only collection when such bindings are used.
Secondary Key Creators are needed whenever database indices are used. For each secondary index (SecondaryDatabase) a key creator is used to derive index key data from key/value data. Key creators are objects whose classes implement the SecondaryKeyCreator interface.
Like bindings, key creators may be implemented using a separate key creator class or using a marshalling interface. Abstract key creator classes and marshalling interfaces are provided in the com.sleepycat.bind.tuple and com.sleepycat.bind.serial packages.
Unlike bindings, key creators fundamentally operate on key and value data, not necessarily on the objects derived from the data by bindings. In this sense key creators are a part of a database definition, and may be independent of the various bindings that may be used to view data in a database. However, key creators are not prohibited from using higher level objects produced by bindings, and doing so may be convenient for some applications. For example, marshalling interfaces, which are defined for objects produced by bindings, are a convenient way to define key creators.