Debian Codegraph @

docs/collections/tutorial/createbindingscollections.html

raw
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>