###

Berkeley DB Reference Guide:
  Java API Tutorial - Tuple

### Tuple - Using the tuple format

Tuples are sequences of primitive Java values that can be written to, and read from, the raw data bytes of a stored record. The primitive values are written or read one at a time in sequence, using the Java API TupleInput and TupleOutput classes. These classes are very similar to the standard Java DataInput and DataOutput interfaces. The primary difference is the binary format of the data, which is designed for sorting in the case of tuples.

For example, to read and write a tuple containing two string values, the following code snippets could be used.

>     import com.sleepycat.bdb.bind.tuple.TupleInput;
>     import com.sleepycat.bdb.bind.tuple.TupleOutput;
>     ...
>     TupleInput input;
>     TupleOutput output;
>     ...
>     String partNumber = input.readString();
>     String supplierNumber = input.readString();
>     ...
>     output.writeString(partNumber);
>     output.writeString(supplierNumber);

Since a tuple is defined as an ordered sequence, reading and writing order must match. If the wrong data type is read (an integer instead of string, for example), an exception may be thrown or at minimum invalid data will be read.

When the tuple format is used, bindings and key extractors must read and write tuples using the tuple API as shown above. This will be illustrated in the next two sections.

First, the tuple format objects must be created as shown below in the modified SampleDatabase class.

>     import com.sleepycat.bdb.bind.serial.TupleSerialKeyExtractor;
>     import com.sleepycat.bdb.bind.tuple.TupleFormat;
>     import com.sleepycat.bdb.bind.tuple.TupleInput;
>     import com.sleepycat.bdb.bind.tuple.TupleOutput;
>     ...
>     public class SampleDatabase
>     {
>         ...
>         private TupleFormat partKeyFormat;
>         private SerialFormat partValueFormat;
>         private TupleFormat supplierKeyFormat;
>         private SerialFormat supplierValueFormat;
>         private TupleFormat shipmentKeyFormat;
>         private SerialFormat shipmentValueFormat;
>         private TupleFormat cityKeyFormat;
>         ...
>         public SampleDatabase(String homeDirectory, boolean runRecovery)
>             throws DbException, FileNotFoundException
>         {
>             ...
>             partKeyFormat = new TupleFormat();
>             partValueFormat = new SerialFormat(javaCatalog, PartValue.class);
>             supplierKeyFormat = new TupleFormat();
>             supplierValueFormat = new SerialFormat(javaCatalog, SupplierValue.class);
>             shipmentKeyFormat = new TupleFormat();
>             shipmentValueFormat = new SerialFormat(javaCatalog, ShipmentValue.class);
>             cityKeyFormat = new TupleFormat();
>             ...
>         }
>     }

For each key, a TupleFormat object is used instead of the SerialFormat used in the prior examples. The TupleFormat constructor has no parameters.

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