mirror of
https://github.com/berkeleydb/je.git
synced 2024-07-06 18:07:18 +00:00
793 lines
30 KiB
HTML
793 lines
30 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>Using the BIND APIs</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="Getting Started with Berkeley DB Java Edition" />
|
||
<link rel="up" href="DBEntry.html" title="Chapter 8. Database Records" />
|
||
<link rel="prev" href="timetolive.html" title="Using Time to Live" />
|
||
<link rel="next" href="comparator.html" title="Using Comparators" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 12.2.7.5</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Using the BIND APIs</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="timetolive.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 8. Database Records</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="comparator.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="bindAPI"></a>Using the BIND APIs</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="bindAPI.html#bindPrimitive">Numerical and String Objects</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="bindAPI.html#object2dbt">Serializable Complex Objects</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="bindAPI.html#customTuple">Custom Tuple Bindings</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>Except for Java String and boolean types, efficiently moving data in
|
||
and out of Java byte arrays for storage in a database can be a nontrivial
|
||
operation. To help you with this problem, JE provides the Bind APIs.
|
||
While these APIs are described in detail in the
|
||
<span>
|
||
<em class="citetitle">Berkeley DB, Java Edition Collections Tutorial</em>,
|
||
</span>
|
||
|
||
|
||
|
||
this section provides a brief introduction to using the Bind APIs with:</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>Single field numerical and string objects</p>
|
||
<p>Use this if you want to store a single numerical or string object,
|
||
such as <code class="classname">Long</code>, <code class="classname">Double</code>, or
|
||
<code class="classname">String</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Complex objects that implement Java serialization.</p>
|
||
<p>Use this if you are storing objects that implement
|
||
<code class="classname">Serializable</code> and if you do not need to sort them.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>Non-serialized complex objects.</p>
|
||
<p>If you are storing objects that do not implement serialization,
|
||
you can create your own custom tuple bindings. Note that you should
|
||
use custom tuple bindings even if your objects are serializable if
|
||
you want to sort on that data.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="bindPrimitive"></a>Numerical and String Objects</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>You can use the Bind APIs to store primitive data in a <code class="classname">DatabaseEntry</code>
|
||
object. That is, you can store a single field containing one of the following types:</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
<code class="classname">String</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Character</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Boolean</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Byte</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Short</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Integer</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Long</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Float</code>
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
<code class="classname">Double</code>
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
To store primitive data using the Bind APIs:
|
||
</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>Create an <code class="classname">EntryBinding</code> object.</p>
|
||
<p>When you do this, you use <code class="classname">TupleBinding.getPrimitiveBinding()</code>
|
||
to return an appropriate binding for the conversion.</p>
|
||
</li>
|
||
<li>
|
||
<p>Use the <code class="classname">EntryBinding</code> object to place
|
||
the numerical object on the <code class="classname">DatabaseEntry</code>.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>Once the data is stored in the DatabaseEntry, you can put it to
|
||
the database in whatever manner you wish. For example:</p>
|
||
<a id="je_dbt6"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.bind.EntryBinding;
|
||
import com.sleepycat.bind.tuple.TupleBinding;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
|
||
...
|
||
|
||
// Need a key for the put.
|
||
try {
|
||
String aKey = "myLong";
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
|
||
// Now build the DatabaseEntry using a TupleBinding
|
||
Long myLong = new Long(123456789l);
|
||
DatabaseEntry theData = new DatabaseEntry();
|
||
EntryBinding myBinding = TupleBinding.getPrimitiveBinding(Long.class);
|
||
myBinding.objectToEntry(myLong, theData);
|
||
|
||
// Now store it
|
||
myDatabase.put(null, theKey, theData);
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
}</pre>
|
||
<p>Retrieval from the <code class="classname">DatabaseEntry</code> object is
|
||
performed in much the same way:</p>
|
||
<a id="je_dbt7"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.bind.EntryBinding;
|
||
import com.sleepycat.bind.tuple.TupleBinding;
|
||
|
||
import com.sleepycat.je.Database;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
import com.sleepycat.je.LockMode;
|
||
import com.sleepycat.je.OperationStatus;
|
||
|
||
...
|
||
|
||
Database myDatabase = null;
|
||
// Database open omitted for clarity
|
||
|
||
try {
|
||
// Need a key for the get
|
||
String aKey = "myLong";
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
|
||
// Need a DatabaseEntry to hold the associated data.
|
||
DatabaseEntry theData = new DatabaseEntry();
|
||
|
||
// Bindings need only be created once for a given scope
|
||
EntryBinding myBinding = TupleBinding.getPrimitiveBinding(Long.class);
|
||
|
||
// Get it
|
||
OperationStatus retVal = myDatabase.get(null, theKey, theData,
|
||
LockMode.DEFAULT);
|
||
String retKey = null;
|
||
if (retVal == OperationStatus.SUCCESS) {
|
||
// Recreate the data.
|
||
// Use the binding to convert the byte array contained in theData
|
||
// to a Long type.
|
||
Long theLong = (Long) myBinding.entryToObject(theData);
|
||
retKey = new String(theKey.getData(), "UTF-8");
|
||
System.out.println("For key: '" + retKey + "' found Long: '" +
|
||
theLong + "'.");
|
||
} else {
|
||
System.out.println("No record found for key '" + retKey + "'.");
|
||
}
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
} </pre>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="object2dbt"></a>Serializable Complex Objects</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>Frequently your application requires you to store and manage
|
||
objects for your record data and/or keys. You may need to do this if you
|
||
are caching objects created by another process. You may also want to do
|
||
this if you want to store multiple data values on a record. When used
|
||
with just primitive data, or with objects containing a single data member,
|
||
JE database records effectively represent a single row in a two-column table.
|
||
By storing a complex object in the record, you can turn each record into
|
||
a single row in an <span class="emphasis"><em>n</em></span>-column table, where
|
||
<span class="emphasis"><em>n</em></span> is the number of data members contained by the
|
||
stored object(s).</p>
|
||
<p>In order to store objects in a
|
||
JE database, you must convert them to and from a <code class="literal">byte</code> array.
|
||
The first instinct for many Java programmers is to do this using Java
|
||
serialization. While this is functionally a correct solution, the result
|
||
is poor space-performance because this causes the class information
|
||
to be stored on every such database record. This information can be quite large
|
||
and it is redundant — the class information does not vary for serialized objects of the same type.
|
||
</p>
|
||
<p>
|
||
In other words, directly using serialization to place your objects into byte
|
||
arrays means that you will be storing a great deal of unnecessary information in
|
||
your database, which ultimately leads to larger databases and more expensive disk
|
||
I/O.
|
||
</p>
|
||
<p>The easiest way for you to solve this problem is to use the Bind
|
||
APIs to perform the serialization for you. Doing so causes the extra
|
||
object information to be saved off to a unique <code class="classname">Database</code>
|
||
dedicated for that purpose. This means that you do not have to duplicate
|
||
that information on each record in the <code class="classname">Database</code>
|
||
that your application is using to store its information.</p>
|
||
<p>
|
||
Note that when you use the Bind APIs to perform serialization, you still
|
||
receive all the benefits of serialization. You can still use arbitrarily
|
||
complex object graphs, and you still receive built-in class evolution
|
||
through the serialVersionUID (SUID) scheme. All of the Java
|
||
serialization rules apply without modification. For example, you can
|
||
implement Externalizable instead of Serializable.
|
||
</p>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="bindCaveats"></a>Usage Caveats</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>Before using the Bind APIs to perform serialization, you may
|
||
want to consider writing your own custom tuple bindings. Specifically,
|
||
avoid serialization if:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
If you need to sort based on the objects your are storing.
|
||
The sort order is meaningless for the byte arrays that you
|
||
obtain through serialization. Consequently, you should not use serialization for keys if you
|
||
care about their sort order. You should
|
||
also not use serialization for record data if your
|
||
<code class="classname">Database</code> supports duplicate records and you care about sort order.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
You want to minimize the size of your byte arrays. Even when using the Bind APIs to perform the
|
||
serialization the resulting <code class="literal">byte</code> array may be larger than necessary. You can achieve
|
||
more compact results by building your own custom tuple binding.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
You want to optimize for speed. In general, custom tuple bindings are faster than serialization at
|
||
moving data in and out of <code class="literal">byte</code> arrays.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
You are using custom comparators. In JE, comparators are instantiated and called internally whenever
|
||
databases are not accessible. Because serial bindings depend on the class catalog, a serial binding
|
||
binding cannot be used during these times. As a result, attempting to use a serial binding with a
|
||
custom comparator will result in a <code class="literal">NullPointerException</code> during environment open or
|
||
close.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>
|
||
For information on building your own custom tuple binding, see <a class="xref" href="bindAPI.html#customTuple" title="Custom Tuple Bindings">Custom Tuple Bindings</a>.
|
||
</p>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="objectSerial"></a>Serializing Objects</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>To store a serializable complex object using the
|
||
Bind APIs:</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
Implement java.io.Serializable in the class whose instances that
|
||
you want to store.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>Open (create) your databases. You need two. The first is the
|
||
database that you use to store your data. The second is used to
|
||
store the class information.</p>
|
||
</li>
|
||
<li>
|
||
<p>Instantiate a class catalog. You do this with
|
||
<code class="classname">com.sleepycat.bind.serial.StoredClassCatalog</code>,
|
||
and at that time you must provide a handle to an open database
|
||
that is used to store the class information.</p>
|
||
</li>
|
||
<li>
|
||
<p>Create an entry binding that uses <code class="methodname">com.sleepycat.bind.serial.SerialBinding</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>Instantiate an instance of the object that you want to
|
||
store, and place it in a <code class="classname">DatabaseEntry</code>
|
||
using the entry binding that you created in the previous step.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>
|
||
For example, suppose you want to store a long, double, and a
|
||
String as a record's data. Then you might create a class that
|
||
looks something like this:
|
||
</p>
|
||
<a id="je_dbt8"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import java.io.Serializable;
|
||
|
||
public class MyData implements Serializable {
|
||
private long longData;
|
||
private double doubleData;
|
||
private String description;
|
||
|
||
MyData() {
|
||
longData = 0;
|
||
doubleData = 0.0;
|
||
description = null;
|
||
}
|
||
|
||
public void setLong(long data) {
|
||
longData = data;
|
||
}
|
||
|
||
public void setDouble(double data) {
|
||
doubleData = data;
|
||
}
|
||
|
||
public void setDescription(String data) {
|
||
description = data;
|
||
}
|
||
|
||
public long getLong() {
|
||
return longData;
|
||
}
|
||
|
||
public double getDouble() {
|
||
return doubleData;
|
||
}
|
||
|
||
public String getDescription() {
|
||
return description;
|
||
}
|
||
}</pre>
|
||
<p>You can then store instances of this class as follows:</p>
|
||
<a id="je_dbt9"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.bind.EntryBinding;
|
||
import com.sleepycat.bind.serial.StoredClassCatalog;
|
||
import com.sleepycat.bind.serial.SerialBinding;
|
||
|
||
import com.sleepycat.je.Database;
|
||
import com.sleepycat.je.DatabaseConfig;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
|
||
...
|
||
|
||
// The key data.
|
||
String aKey = "myData";
|
||
|
||
// The data data
|
||
MyData data2Store = new MyData();
|
||
data2Store.setLong(123456789l);
|
||
data2Store.setDouble(1234.9876543);
|
||
data2Store.setDescription("A test instance of this class");
|
||
|
||
try {
|
||
// Environment open omitted for brevity
|
||
|
||
// Open the database that you will use to store your data
|
||
DatabaseConfig myDbConfig = new DatabaseConfig();
|
||
myDbConfig.setAllowCreate(true);
|
||
myDbConfig.setSortedDuplicates(true);
|
||
Database myDatabase = myDbEnv.openDatabase(null, "myDb", myDbConfig);
|
||
|
||
// Open the database that you use to store your class information.
|
||
// The db used to store class information does not require duplicates
|
||
// support.
|
||
myDbConfig.setSortedDuplicates(false);
|
||
Database myClassDb = myDbEnv.openDatabase(null, "classDb",
|
||
myDbConfig);
|
||
|
||
// Instantiate the class catalog
|
||
StoredClassCatalog classCatalog = new StoredClassCatalog(myClassDb);
|
||
|
||
// Create the binding
|
||
EntryBinding dataBinding = new SerialBinding(classCatalog,
|
||
MyData.class);
|
||
|
||
// Create the DatabaseEntry for the key
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
|
||
// Create the DatabaseEntry for the data. Use the EntryBinding object
|
||
// that was just created to populate the DatabaseEntry
|
||
DatabaseEntry theData = new DatabaseEntry();
|
||
dataBinding.objectToEntry(data2Store, theData);
|
||
|
||
// Put it as normal
|
||
myDatabase.put(null, theKey, theData);
|
||
|
||
// Database and environment close omitted for brevity
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
}</pre>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="objectDeserial"></a>Deserializing Objects</h4>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>Once an object is stored in the database, you can retrieve the
|
||
<code class="classname">MyData</code> objects from the retrieved
|
||
<code class="classname">DatabaseEntry</code> using the Bind APIs in much the
|
||
same way as is described above. For example:</p>
|
||
<a id="je_dbt10"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.bind.EntryBinding;
|
||
import com.sleepycat.bind.serial.StoredClassCatalog;
|
||
import com.sleepycat.bind.serial.SerialBinding;
|
||
|
||
import com.sleepycat.je.Database;
|
||
import com.sleepycat.je.DatabaseConfig;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
import com.sleepycat.je.LockMode;
|
||
|
||
...
|
||
|
||
// The key data.
|
||
String aKey = "myData";
|
||
|
||
try {
|
||
// Environment open omitted for brevity.
|
||
|
||
// Open the database that stores your data
|
||
DatabaseConfig myDbConfig = new DatabaseConfig();
|
||
myDbConfig.setAllowCreate(false);
|
||
Database myDatabase = myDbEnv.openDatabase(null, "myDb", myDbConfig);
|
||
|
||
// Open the database that stores your class information.
|
||
Database myClassDb = myDbEnv.openDatabase(null, "classDb",
|
||
myDbConfig);
|
||
|
||
// Instantiate the class catalog
|
||
StoredClassCatalog classCatalog = new StoredClassCatalog(myClassDb);
|
||
|
||
// Create the binding
|
||
EntryBinding dataBinding = new SerialBinding(classCatalog,
|
||
MyData.class);
|
||
|
||
// Create DatabaseEntry objects for the key and data
|
||
DatabaseEntry theKey = new DatabaseEntry(aKey.getBytes("UTF-8"));
|
||
DatabaseEntry theData = new DatabaseEntry();
|
||
|
||
// Do the get as normal
|
||
myDatabase.get(null, theKey, theData, LockMode.DEFAULT);
|
||
|
||
// Recreate the MyData object from the retrieved DatabaseEntry using
|
||
// the EntryBinding created above
|
||
MyData retrievedData = (MyData) dataBinding.entryToObject(theData);
|
||
|
||
// Database and environment close omitted for brevity
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
}</pre>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="customTuple"></a>Custom Tuple Bindings</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
If you want to store complex objects in your database, then you can use
|
||
tuple bindings to do this. While they are more work to write and
|
||
maintain than if you were to use serialization, the
|
||
<code class="literal">byte</code> array conversion is faster. In addition, custom
|
||
tuple bindings should allow you to create <code class="literal">byte</code> arrays
|
||
that are smaller than those created by serialization. Custom tuple
|
||
bindings also allow you to optimize your BTree comparisons, whereas
|
||
serialization does not.
|
||
</p>
|
||
<p>
|
||
For information on using serialization to store complex objects, see
|
||
<a class="xref" href="bindAPI.html#object2dbt" title="Serializable Complex Objects">Serializable Complex Objects</a>.
|
||
</p>
|
||
<p>To store complex objects using a custom tuple binding:</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>Implement the class whose instances that you want to store.
|
||
Note that you do not have to implement the Serializable interface.</p>
|
||
</li>
|
||
<li>
|
||
<p>Write a tuple binding using the <code class="classname">com.sleepycat.bind.tuple.TupleBinding</code>
|
||
class.</p>
|
||
</li>
|
||
<li>
|
||
<p>Open (create) your database. Unlike serialization, you only
|
||
need one.</p>
|
||
</li>
|
||
<li>
|
||
<p>Create an entry binding that uses the tuple binding that you
|
||
implemented in step 2.</p>
|
||
</li>
|
||
<li>
|
||
<p>Instantiate an instance of the object that you want to store,
|
||
and place it in a <code class="classname">DatabaseEntry</code> using the
|
||
entry binding that you created in the previous step.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<p>
|
||
For example, suppose you want to your keys to be instances of the
|
||
following class:
|
||
</p>
|
||
<a id="je_dbt11"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
public class MyData2 {
|
||
private long longData;
|
||
private Double doubleData;
|
||
private String description;
|
||
|
||
public MyData2() {
|
||
longData = 0;
|
||
doubleData = new Double(0.0);
|
||
description = "";
|
||
}
|
||
|
||
public void setLong(long data) {
|
||
longData = data;
|
||
}
|
||
|
||
public void setDouble(Double data) {
|
||
doubleData = data;
|
||
}
|
||
|
||
public void setString(String data) {
|
||
description = data;
|
||
}
|
||
|
||
public long getLong() {
|
||
return longData;
|
||
}
|
||
|
||
public Double getDouble() {
|
||
return doubleData;
|
||
}
|
||
|
||
public String getString() {
|
||
return description;
|
||
}
|
||
} </pre>
|
||
<p>In this case, you need to write a tuple binding for the
|
||
<code class="classname">MyData2</code> class. When you do this, you must
|
||
implement the <code class="methodname">TupleBinding.objectToEntry()</code>
|
||
and <code class="methodname">TupleBinding.entryToObject()</code> abstract methods.
|
||
Remember the following as you implement these methods:</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>You use <code class="methodname">TupleBinding.objectToEntry()</code> to convert
|
||
objects to <code class="literal">byte</code> arrays. You use
|
||
<code class="classname">com.sleepycat.bind.tuple.TupleOutput</code> to write
|
||
primitive data types to the <code class="literal">byte</code> array. Note that
|
||
<code class="classname">TupleOutput</code> provides methods that allows
|
||
you to work with numerical types (<code class="literal">long</code>,
|
||
<code class="literal">double</code>, <code class="literal">int</code>, and so forth) and
|
||
not the corresponding <code class="literal">java.lang</code> numerical
|
||
classes.</p>
|
||
</li>
|
||
<li>
|
||
<p>The order that you write data to the <code class="literal">byte</code>
|
||
array in <code class="methodname">TupleBinding.objectToEntry()</code> is the order that
|
||
it appears in the array. So given the <code class="classname">MyData2</code>
|
||
class as an example, if you write <code class="literal">description</code>,
|
||
<code class="literal">doubleData</code>, and then <code class="literal">longData</code>,
|
||
then the resulting byte array will contain these data elements in
|
||
that order. This means that your records will sort based on the
|
||
value of the <code class="literal">description</code> data member and then
|
||
the <code class="literal">doubleData</code> member, and so forth. If you
|
||
prefer to sort based on, say, the <code class="literal">longData</code> data
|
||
member, write it to the byte array first.</p>
|
||
</li>
|
||
<li>
|
||
<p>You use <code class="methodname">TupleBinding.entryToObject()</code> to convert
|
||
the <code class="literal">byte</code> array back into an instance of your
|
||
original class. You use <code class="classname">com.sleepycat.bind.tuple.TupleInput</code>
|
||
to get data from the <code class="literal">byte</code> array.</p>
|
||
</li>
|
||
<li>
|
||
<p>The order that you read data from the <code class="literal">byte</code>
|
||
array must be exactly the same as the order in which it was written.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>For example:</p>
|
||
<a id="je_dbt12"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.bind.tuple.TupleBinding;
|
||
import com.sleepycat.bind.tuple.TupleInput;
|
||
import com.sleepycat.bind.tuple.TupleOutput;
|
||
|
||
public class MyTupleBinding extends TupleBinding {
|
||
|
||
// Write a MyData2 object to a TupleOutput
|
||
public void objectToEntry(Object object, TupleOutput to) {
|
||
|
||
MyData2 myData = (MyData2)object;
|
||
|
||
// Write the data to the TupleOutput (a DatabaseEntry).
|
||
// Order is important. The first data written will be
|
||
// the first bytes used by the default comparison routines.
|
||
to.writeDouble(myData.getDouble().doubleValue());
|
||
to.writeLong(myData.getLong());
|
||
to.writeString(myData.getString());
|
||
}
|
||
|
||
// Convert a TupleInput to a MyData2 object
|
||
public Object entryToObject(TupleInput ti) {
|
||
|
||
// Data must be read in the same order that it was
|
||
// originally written.
|
||
Double theDouble = new Double(ti.readDouble());
|
||
long theLong = ti.readLong();
|
||
String theString = ti.readString();
|
||
|
||
MyData2 myData = new MyData2();
|
||
myData.setDouble(theDouble);
|
||
myData.setLong(theLong);
|
||
myData.setString(theString);
|
||
|
||
return myData;
|
||
}
|
||
} </pre>
|
||
<p>In order to use the tuple binding, instantiate the binding and
|
||
then use:</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p><code class="methodname">MyTupleBinding.objectToEntry()</code> to
|
||
convert a MyData2 object to a <code class="classname">DatabaseEntry</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code class="methodname">MyTupleBinding.entryToObject()</code> to convert
|
||
a <code class="classname">DatabaseEntry</code> to a <code class="classname">MyData2</code>
|
||
object.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<p>For example:</p>
|
||
<a id="je_dbt13"></a>
|
||
<pre class="programlisting">package je.gettingStarted;
|
||
|
||
import com.sleepycat.bind.tuple.TupleBinding;
|
||
import com.sleepycat.je.DatabaseEntry;
|
||
|
||
...
|
||
|
||
TupleBinding keyBinding = new MyTupleBinding();
|
||
|
||
MyData2 theKeyData = new MyData2();
|
||
theKeyData.setLong(123456789l);
|
||
theKeyData.setDouble(new Double(12345.6789));
|
||
theKeyData.setString("My key data");
|
||
|
||
DatabaseEntry myKey = new DatabaseEntry();
|
||
|
||
try {
|
||
// Store theKeyData in the DatabaseEntry
|
||
keyBinding.objectToEntry(theKeyData, myKey);
|
||
|
||
...
|
||
// Database put and get activity omitted for clarity
|
||
...
|
||
|
||
// Retrieve the key data
|
||
theKeyData = (MyData2) keyBinding.entryToObject(myKey);
|
||
} catch (Exception e) {
|
||
// Exception handling goes here
|
||
}</pre>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="timetolive.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="DBEntry.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="comparator.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Using Time to Live </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Using Comparators</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|