je/docs/GettingStartedGuide/keyCreator.html
2021-06-06 13:46:45 -04:00

241 lines
8.7 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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>Implementing Key Creators</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="indexes.html" title="Chapter 10. Secondary Databases" />
<link rel="prev" href="indexes.html" title="Chapter 10. Secondary Databases" />
<link rel="next" href="secondaryProps.html" title="Secondary Database Properties" />
</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">Implementing Key
<span xmlns="http://www.w3.org/1999/xhtml">Creators</span>
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="indexes.html">Prev</a> </td>
<th width="60%" align="center">Chapter 10. Secondary Databases</th>
<td width="20%" align="right"> <a accesskey="n" href="secondaryProps.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="keyCreator"></a>Implementing Key
<span>Creators</span>
</h2>
</div>
</div>
</div>
<p>
You must provide every secondary database with a
<span>class</span>
that creates keys from primary records. You identify this
<span>class</span>
<span>
using the <code class="methodname">SecondaryConfig.setKeyCreator()</code>
method.
</span>
</p>
<p>
You can create keys using whatever data you want. Typically you will
base your key on some information found in a record's data, but you
can also use information found in the primary record's key. How you build
your keys is entirely dependent upon the nature of the index that you
want to maintain.
</p>
<p>
You implement a key creator by writing a class that implements the
<code class="classname">SecondaryKeyCreator</code> interface. This interface
requires you to implement the <code class="methodname">SecondaryKeyCreator.createSecondaryKey()</code>
method.
</p>
<p>
One thing to remember when implementing this method is that you will
need a way to extract the necessary information from the data's
<code class="classname">DatabaseEntry</code> and/or the key's
<code class="classname">DatabaseEntry</code> that are provided on calls to this
method. If you are using complex objects, then you are probably using the
Bind APIs to perform this conversion. The easiest thing to do is to
instantiate the <code class="classname">EntryBinding</code> or
<code class="classname">TupleBinding</code> that you need to perform the
conversion, and then provide this to your key creator's constructor.
The Bind APIs are introduced in <a class="xref" href="bindAPI.html" title="Using the BIND APIs">Using the BIND APIs</a>.
</p>
<p>
<code class="methodname">SecondaryKeyCreator.createSecondaryKey()</code> returns a
boolean. A return value of <code class="literal">false</code> indicates that
no secondary key exists, and therefore no record should be added to the secondary database for that primary record.
If a record already exists in the secondary database, it is deleted.
</p>
<p>
For example, suppose your primary database uses the following class
for its record data:
</p>
<a id="je_index3"></a>
<pre class="programlisting">package je.gettingStarted;
public class PersonData {
private String userID;
private String surname;
private String familiarName;
public PersonData(String userID, String surname,
String familiarName) {
this.userID = userID;
this.surname = surname;
this.familiarName = familiarName;
}
public String getUserID() {
return userID;
}
public String getSurname() {
return surname;
}
public String getFamiliarName() {
return familiarName;
}
} </pre>
<p>
Also, suppose that you have created a custom tuple binding,
<code class="classname">PersonDataBinding</code>, that you use to convert
<code class="classname">PersonData</code> objects to and from
<code class="classname">DatabaseEntry</code> objects. (Custom tuple bindings are
described in <a class="xref" href="bindAPI.html#customTuple" title="Custom Tuple Bindings">Custom Tuple Bindings</a>.)
</p>
<p>
Finally, suppose you want a secondary database that is keyed based
on the person's full name.
</p>
<p>
Then in this case you might create a key creator as follows:
</p>
<a id="je_index4"></a>
<pre class="programlisting">package je.gettingStarted;
import com.sleepycat.bind.tuple.TupleBinding;
import com.sleepycat.je.SecondaryKeyCreator;
import com.sleepycat.je.DatabaseEntry;
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.SecondaryDatabase;
import java.io.IOException;
public class FullNameKeyCreator implements SecondaryKeyCreator {
private TupleBinding theBinding;
public FullNameKeyCreator(TupleBinding theBinding1) {
theBinding = theBinding1;
}
public boolean createSecondaryKey(SecondaryDatabase secDb,
DatabaseEntry keyEntry,
DatabaseEntry dataEntry,
DatabaseEntry resultEntry) {
try {
PersonData pd =
(PersonData) theBinding.entryToObject(dataEntry);
String fullName = pd.getFamiliarName() + " " +
pd.getSurname();
resultEntry.setData(fullName.getBytes("UTF-8"));
} catch (IOException willNeverOccur) {}
return true;
}
} </pre>
<p>Finally, you use this key creator as follows:</p>
<a id="je_index5"></a>
<pre class="programlisting">package je.gettingStarted;
import com.sleepycat.bind.tuple.TupleBinding;
import com.sleepycat.je.Database;
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.Environment;
import com.sleepycat.je.SecondaryDatabase;
import com.sleepycat.je.SecondaryConfig;
...
Environment myEnv = null;
Database myDb = null;
SecondaryDatabase mySecDb = null;
try {
// Environment and primary database open omitted for brevity
...
TupleBinding myDataBinding = new MyTupleBinding();
FullNameKeyCreator fnkc = new FullNameKeyCreator(myDataBinding);
SecondaryConfig mySecConfig = new SecondaryConfig();
mySecConfig.setKeyCreator(fnkc);
//Perform the actual open
String secDbName = "mySecondaryDatabase";
mySecDb = myEnv.openSecondaryDatabase(null, secDbName, myDb,
mySecConfig);
} catch (DatabaseException de) {
// Exception handling goes here
} finally {
try {
if (mySecDb != null) {
mySecDb.close();
}
if (myDb != null) {
myDb.close();
}
if (myEnv != null) {
myEnv.close();
}
} catch (DatabaseException dbe) {
// Exception handling goes here
}
}</pre>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="indexes.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="indexes.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="secondaryProps.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 10. Secondary Databases </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Secondary Database Properties</td>
</tr>
</table>
</div>
</body>
</html>