| 1 |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| 6 |
<title>Creating Bindings and Collections</title> |
| 7 |
<link rel="stylesheet" href="gettingStarted.css" type="text/css" /> |
| 8 |
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> |
| 9 |
<link rel="start" href="index.html" title="Berkeley DB Collections Tutorial" /> |
| 10 |
<link rel="up" href="BasicProgram.html" title="Chapter 2. The Basic Program" /> |
| 11 |
<link rel="prev" href="opendatabases.html" title="Opening and Closing Databases" /> |
| 12 |
<link rel="next" href="implementingmain.html" title="Implementing the Main Program" /> |
| 13 |
</head> |
| 14 |
<body> |
| 15 |
<div xmlns="" class="navheader"> |
| 16 |
<div class="libver"> |
| 17 |
<p>Library Version 11.2.5.3</p> |
| 18 |
</div> |
| 19 |
<table width="100%" summary="Navigation header"> |
| 20 |
<tr> |
| 21 |
<th colspan="3" align="center"> |
| 22 |
Creating Bindings and Collections |
| 23 |
</th> |
| 24 |
</tr> |
| 25 |
<tr> |
| 26 |
<td width="20%" align="left"><a accesskey="p" href="opendatabases.html">Prev</a> </td> |
| 27 |
<th width="60%" align="center">Chapter 2. |
| 28 |
The Basic Program |
| 29 |
</th> |
| 30 |
<td width="20%" align="right"> <a accesskey="n" href="implementingmain.html">Next</a></td> |
| 31 |
</tr> |
| 32 |
</table> |
| 33 |
<hr /> |
| 34 |
</div> |
| 35 |
<div class="sect1" lang="en" xml:lang="en"> |
| 36 |
<div class="titlepage"> |
| 37 |
<div> |
| 38 |
<div> |
| 39 |
<h2 class="title" style="clear: both"><a id="createbindingscollections"></a> |
| 40 |
Creating Bindings and Collections |
| 41 |
</h2> |
| 42 |
</div> |
| 43 |
</div> |
| 44 |
</div> |
| 45 |
<p> |
| 46 |
<span class="emphasis"><em>Bindings</em></span> translate between stored records and Java objects. |
| 47 |
In this example, Java serialization bindings are used. Serial |
| 48 |
bindings are the simplest type of bindings because no mapping of |
| 49 |
fields or type conversion is needed. Tuple bindings — which are |
| 50 |
more difficult to create than serial bindings but have some |
| 51 |
advantages — will be introduced later in the Tuple example |
| 52 |
program. |
| 53 |
</p> |
| 54 |
<p> |
| 55 |
Standard Java <span class="emphasis"><em>collections</em></span> are used to access records in a |
| 56 |
database. Stored collections use bindings transparently to convert |
| 57 |
the records to objects when they are retrieved from the collection, |
| 58 |
and to convert the objects to records when they are stored in the |
| 59 |
collection. |
| 60 |
</p> |
| 61 |
<p> |
| 62 |
An important characteristic of stored collections is that they |
| 63 |
do <span class="emphasis"><em>not</em></span> perform object caching. Every time an object is |
| 64 |
accessed via a collection it will be added to or retrieved from the |
| 65 |
database, and the bindings will be invoked to convert the data. |
| 66 |
Objects are therefore always passed and returned by value, not by |
| 67 |
reference. Because Berkeley DB is an embedded database, efficient |
| 68 |
caching of stored raw record data is performed by the database library. |
| 69 |
</p> |
| 70 |
<p> |
| 71 |
The <code class="classname">SampleViews</code> class is used to create the bindings and |
| 72 |
collections. This class is separate from the <code class="classname">SampleDatabase</code> |
| 73 |
class to illustrate the idea that a single set of stored data can |
| 74 |
be accessed via multiple bindings and collections, or <span class="emphasis"><em>views</em></span>. |
| 75 |
The skeleton for the <code class="classname">SampleViews</code> class follows. |
| 76 |
</p> |
| 77 |
<a id="cb_sampleviews"></a> |
| 78 |
<pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.bind.EntryBinding; |
| 79 |
import com.sleepycat.bind.serial.ClassCatalog; |
| 80 |
import com.sleepycat.bind.serial.SerialBinding; |
| 81 |
import com.sleepycat.collections.StoredEntrySet; |
| 82 |
import com.sleepycat.collections.StoredMap; |
| 83 |
... |
| 84 |
|
| 85 |
public class SampleViews |
| 86 |
{ |
| 87 |
private StoredMap partMap; |
| 88 |
private StoredMap supplierMap; |
| 89 |
private StoredMap shipmentMap; |
| 90 |
|
| 91 |
... |
| 92 |
public SampleViews(SampleDatabase db) |
| 93 |
{ |
| 94 |
} |
| 95 |
}</code></strong> </pre> |
| 96 |
<p> |
| 97 |
A |
| 98 |
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a> |
| 99 |
|
| 100 |
field is used for each database. The StoredMap class implements the |
| 101 |
standard Java |
| 102 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a> |
| 103 |
|
| 104 |
interface, which has methods for obtaining a |
| 105 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a> |
| 106 |
|
| 107 |
of keys, a |
| 108 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a> |
| 109 |
|
| 110 |
of values, or a |
| 111 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a> |
| 112 |
|
| 113 |
of |
| 114 |
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a> |
| 115 |
|
| 116 |
key/value pairs. Because databases contain key/value pairs, any |
| 117 |
Berkeley DB database may be represented as a Java map. |
| 118 |
</p> |
| 119 |
<p> |
| 120 |
The following statements create the key and data bindings using |
| 121 |
the |
| 122 |
<a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a> |
| 123 |
|
| 124 |
class. |
| 125 |
</p> |
| 126 |
<a id="cb_sampleviews1"></a> |
| 127 |
<pre class="programlisting"> public SampleViews(SampleDatabase db) |
| 128 |
{ |
| 129 |
<strong class="userinput"><code> ClassCatalog catalog = db.getClassCatalog(); |
| 130 |
EntryBinding partKeyBinding = |
| 131 |
new SerialBinding(catalog, PartKey.class); |
| 132 |
EntryBinding partValueBinding = |
| 133 |
new SerialBinding(catalog, PartData.class); |
| 134 |
EntryBinding supplierKeyBinding = |
| 135 |
new SerialBinding(catalog, SupplierKey.class); |
| 136 |
EntryBinding supplierValueBinding = |
| 137 |
new SerialBinding(catalog, SupplierData.class); |
| 138 |
EntryBinding shipmentKeyBinding = |
| 139 |
new SerialBinding(catalog, ShipmentKey.class); |
| 140 |
EntryBinding shipmentValueBinding = |
| 141 |
new SerialBinding(catalog, ShipmentData.class);</code></strong> |
| 142 |
... |
| 143 |
} </pre> |
| 144 |
<p> |
| 145 |
The first parameter of the |
| 146 |
<a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a> |
| 147 |
|
| 148 |
constructor is the class catalog, and is used to store the class |
| 149 |
descriptions of the serialized objects. |
| 150 |
</p> |
| 151 |
<p> |
| 152 |
The second parameter is the base class for the serialized |
| 153 |
objects and is used for type checking of the stored objects. If |
| 154 |
<code class="literal">null</code> or <code class="literal">Object.class</code> is specified, then any Java |
| 155 |
class is allowed. Otherwise, all objects stored in that format must |
| 156 |
be instances of the specified class or derived from the specified |
| 157 |
class. In the example, specific classes are used to enable strong |
| 158 |
type checking. |
| 159 |
</p> |
| 160 |
<p> |
| 161 |
The following statements create standard Java maps using the |
| 162 |
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a> |
| 163 |
|
| 164 |
class. |
| 165 |
</p> |
| 166 |
<a id="cb_sampleviews2"></a> |
| 167 |
<pre class="programlisting"> public SampleViews(SampleDatabase db) |
| 168 |
{ |
| 169 |
... |
| 170 |
<strong class="userinput"><code> partMap = |
| 171 |
new StoredMap(db.getPartDatabase(), |
| 172 |
partKeyBinding, partValueBinding, true); |
| 173 |
supplierMap = |
| 174 |
new StoredMap(db.getSupplierDatabase(), |
| 175 |
supplierKeyBinding, supplierValueBinding, true); |
| 176 |
shipmentMap = |
| 177 |
new StoredMap(db.getShipmentDatabase(), |
| 178 |
shipmentKeyBinding, shipmentValueBinding, true);</code></strong> |
| 179 |
... |
| 180 |
} </pre> |
| 181 |
<p> |
| 182 |
The first parameter of the |
| 183 |
<a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html" target="_top">StoredMap</a> |
| 184 |
|
| 185 |
constructor is the database. In a StoredMap, the database keys (the primary |
| 186 |
keys) are used as the map keys. The Index |
| 187 |
example shows how to use secondary index keys as map keys. |
| 188 |
</p> |
| 189 |
<p> |
| 190 |
The second and third parameters are the key and value bindings |
| 191 |
to use when storing and retrieving objects via the map. |
| 192 |
</p> |
| 193 |
<p> |
| 194 |
The fourth and last parameter specifies whether changes will be |
| 195 |
allowed via the collection. If false is passed, the collection will |
| 196 |
be read-only. |
| 197 |
</p> |
| 198 |
<p> |
| 199 |
The following getter methods return the stored maps for use by |
| 200 |
other classes in the example program. Convenience methods for |
| 201 |
returning entry sets are also included. |
| 202 |
</p> |
| 203 |
<a id="cb_sampleviewsgetters"></a> |
| 204 |
<pre class="programlisting">public class SampleViews |
| 205 |
{ |
| 206 |
... |
| 207 |
<strong class="userinput"><code> public final StoredMap getPartMap() |
| 208 |
{ |
| 209 |
return partMap; |
| 210 |
} |
| 211 |
|
| 212 |
public final StoredMap getSupplierMap() |
| 213 |
{ |
| 214 |
return supplierMap; |
| 215 |
} |
| 216 |
|
| 217 |
public final StoredMap getShipmentMap() |
| 218 |
{ |
| 219 |
return shipmentMap; |
| 220 |
} |
| 221 |
|
| 222 |
public final StoredEntrySet getPartEntrySet() |
| 223 |
{ |
| 224 |
return (StoredEntrySet) partMap.entrySet(); |
| 225 |
} |
| 226 |
|
| 227 |
public final StoredEntrySet getSupplierEntrySet() |
| 228 |
{ |
| 229 |
return (StoredEntrySet) supplierMap.entrySet(); |
| 230 |
} |
| 231 |
|
| 232 |
public final StoredEntrySet getShipmentEntrySet() |
| 233 |
{ |
| 234 |
return (StoredEntrySet) shipmentMap.entrySet(); |
| 235 |
}</code></strong> |
| 236 |
... |
| 237 |
} </pre> |
| 238 |
<p> |
| 239 |
Note that StoredMap and StoredEntrySet are returned rather than |
| 240 |
just returning Map and Set. Since StoredMap implements the Map |
| 241 |
interface and StoredEntrySet implements the Set interface, you may |
| 242 |
ask why Map and Set were not returned directly. |
| 243 |
</p> |
| 244 |
<p> |
| 245 |
<code class="classname">StoredMap</code>, <code class="classname">StoredEntrySet</code>, |
| 246 |
and other stored collection classes |
| 247 |
have a small number of extra methods beyond those in the Java |
| 248 |
collection interfaces. The stored collection types are therefore |
| 249 |
returned to avoid casting when using the extended methods. |
| 250 |
Normally, however, only a Map or Set is needed, and may be used as |
| 251 |
follows. |
| 252 |
</p> |
| 253 |
<a id="cb_sampleviews_usage"></a> |
| 254 |
<pre class="programlisting"><strong class="userinput"><code> SampleDatabase sd = new SampleDatabase(new String("/home")); |
| 255 |
SampleViews views = new SampleViews(sd); |
| 256 |
Map partMap = views.getPartMap(); |
| 257 |
Set supplierEntries = views.getSupplierEntrySet();</code></strong> </pre> |
| 258 |
</div> |
| 259 |
<div class="navfooter"> |
| 260 |
<hr /> |
| 261 |
<table width="100%" summary="Navigation footer"> |
| 262 |
<tr> |
| 263 |
<td width="40%" align="left"><a accesskey="p" href="opendatabases.html">Prev</a> </td> |
| 264 |
<td width="20%" align="center"> |
| 265 |
<a accesskey="u" href="BasicProgram.html">Up</a> |
| 266 |
</td> |
| 267 |
<td width="40%" align="right"> <a accesskey="n" href="implementingmain.html">Next</a></td> |
| 268 |
</tr> |
| 269 |
<tr> |
| 270 |
<td width="40%" align="left" valign="top"> |
| 271 |
Opening and Closing Databases |
| 272 |
</td> |
| 273 |
<td width="20%" align="center"> |
| 274 |
<a accesskey="h" href="index.html">Home</a> |
| 275 |
</td> |
| 276 |
<td width="40%" align="right" valign="top"> |
| 277 |
Implementing the Main Program |
| 278 |
</td> |
| 279 |
</tr> |
| 280 |
</table> |
| 281 |
</div> |
| 282 |
</body> |
| 283 |
</html> |