Debian Codegraph @

docs/collections/tutorial/UsingSecondaries.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>Chapter 3.  Using Secondary Indices</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="index.html" title="Berkeley DB Collections Tutorial" />
11 <link rel="prev" href="handlingexceptions.html" title="Handling Exceptions" />
12 <link rel="next" href="openingforeignkeys.html" title="More Secondary Key Indices" />
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">Chapter 3. 
22 Using Secondary Indices
23 </th>
24 </tr>
25 <tr>
26 <td width="20%" align="left"><a accesskey="p" href="handlingexceptions.html">Prev</a> </td>
27 <th width="60%" align="center"> </th>
28 <td width="20%" align="right"> <a accesskey="n" href="openingforeignkeys.html">Next</a></td>
29 </tr>
30 </table>
31 <hr />
32 </div>
33 <div class="chapter" lang="en" xml:lang="en">
34 <div class="titlepage">
35 <div>
36 <div>
37 <h2 class="title"><a id="UsingSecondaries"></a>Chapter 3. 
38 Using Secondary Indices
39 </h2>
40 </div>
41 </div>
42 </div>
43 <div class="toc">
44 <p>
45 <b>Table of Contents</b>
46 </p>
47 <dl>
48 <dt>
49 <span class="sect1">
50 <a href="UsingSecondaries.html#opensecondaryindices">
51 Opening Secondary Key Indices
52 </a>
53 </span>
54 </dt>
55 <dt>
56 <span class="sect1">
57 <a href="openingforeignkeys.html">
58
59 <span>More Secondary Key Indices</span>
60 </a>
61 </span>
62 </dt>
63 <dt>
64 <span class="sect1">
65 <a href="indexedcollections.html">
66 Creating Indexed Collections
67 </a>
68 </span>
69 </dt>
70 <dt>
71 <span class="sect1">
72 <a href="retrievingbyindexkey.html">
73 Retrieving Items by Index Key
74 </a>
75 </span>
76 </dt>
77 </dl>
78 </div>
79 <p>
80 In the Basic example, each store has a single <span class="emphasis"><em>primary
81 key</em></span>. The Index example extends the Basic example to add the use of
82 <span class="emphasis"><em>secondary keys</em></span>.
83 </p>
84 <p>
85 The complete source of the final version of the example program
86 is included in the Berkeley DB distribution.
87 </p>
88 <div class="sect1" lang="en" xml:lang="en">
89 <div class="titlepage">
90 <div>
91 <div>
92 <h2 class="title" style="clear: both"><a id="opensecondaryindices"></a>
93 Opening Secondary Key Indices
94 </h2>
95 </div>
96 </div>
97 </div>
98 <p>
99 <span class="emphasis"><em>Secondary indices</em></span> or <span class="emphasis"><em>secondary databases</em></span> are used
100 to access a primary database by a key other than the primary key.
101 Recall that the Supplier Number field is the primary key of the
102 Supplier database. In this section, the Supplier City field will be
103 used as a secondary lookup key. Given a city value, we would like
104 to be able to find the Suppliers in that city. Note that more than
105 one Supplier may be in the same city.
106 </p>
107 <p>
108 Both primary and secondary databases contain key-value records.
109 The key of an index record is the secondary key, and its value is
110 the key of the associated record in the primary database. When lookups by
111 secondary key are performed, the associated record in the primary
112 database is transparently retrieved by its primary key and returned
113 to the caller.
114 </p>
115 <p>
116 Secondary indices are maintained automatically when index key
117 fields (the City field in this case) are added, modified or removed
118 in the records of the primary database. However, the application
119 must implement a
120
121 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
122
123 that extracts the index key from the database record.
124 </p>
125 <p>
126 It is useful to contrast opening an secondary index with opening
127 a primary database (as described earlier in
128 <a class="xref" href="opendatabases.html" title="Opening and Closing Databases">
129 Opening and Closing Databases
130 </a>.
131 </p>
132 <div class="itemizedlist">
133 <ul type="disc">
134 <li>
135 <p>
136 A primary database may be associated with one or more secondary
137 indices. A secondary index is always associated with exactly one
138 primary database.
139 </p>
140 </li>
141 <li>
142 <p>
143 For a secondary index, a
144
145 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
146
147 must be implemented by the application to extract the index key
148 from the record of its associated primary database.
149 </p>
150 </li>
151 <li>
152 <p>
153 A primary database is represented by a
154
155 <a class="ulink" href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
156
157 object and a secondary index is represented by a
158
159 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
160
161 object. The
162
163 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
164
165 class extends the
166
167 <a class="ulink" href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
168
169 class.
170 </p>
171 </li>
172 <li>
173 <p>
174 When a
175
176 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
177
178 is created it is associated with a primary
179
180 <a class="ulink" href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
181
182 object and a
183
184 <span>
185 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>.
186 </span>
187 </p>
188 </li>
189 </ul>
190 </div>
191 <p>
192 The <code class="classname">SampleDatabase</code> class is extended to open the
193 Supplier-by-City secondary key index.
194 </p>
195 <a id="index_java_sampledatabase"></a>
196 <pre class="programlisting"><strong class="userinput"><code>import com.sleepycat.bind.serial.SerialSerialKeyCreator;
197 import com.sleepycat.db.SecondaryConfig;
198 import com.sleepycat.db.SecondaryDatabase;</code></strong>
199 ...
200 public class SampleDatabase
201 {
202 ...
203 <strong class="userinput"><code> private static final String SUPPLIER_CITY_INDEX =
204 "supplier_city_index";
205 ...
206 private SecondaryDatabase supplierByCityDb;
207 ...</code></strong>
208 public SampleDatabase(String homeDirectory)
209 throws DatabaseException, FileNotFoundException
210 {
211 ...
212 <strong class="userinput"><code> SecondaryConfig secConfig = new SecondaryConfig();
213 secConfig.setTransactional(true);
214 secConfig.setAllowCreate(true);
215 secConfig.setType(DatabaseType.BTREE);
216 secConfig.setSortedDuplicates(true);
217
218 secConfig.setKeyCreator(
219 new SupplierByCityKeyCreator(javaCatalog,
220 SupplierKey.class,
221 SupplierData.class,
222 String.class));
223
224 supplierByCityDb = env.openSecondaryDatabase(null,
225 SUPPLIER_CITY_INDEX,
226 null,
227 supplierDb,
228 secConfig);</code></strong>
229 ...
230 }
231 } </pre>
232 <p>
233 A
234
235 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryConfig.html" target="_top">SecondaryConfig</a>
236
237 object is used to configure the secondary database. The
238
239 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryConfig.html" target="_top">SecondaryConfig</a>
240
241 class extends the
242
243 <a class="ulink" href="../../java/com/sleepycat/db/DatabaseConfig.html" target="_top">DatabaseConfig</a>
244
245 class, and most steps for configuring a secondary database are the
246 same as for configuring a primary database. The main difference in
247 the example above is that the
248 <code class="methodname">SecondaryConfig.setSortedDuplicates()</code> method is called to
249 allow duplicate index keys. This is how more than one Supplier may
250 be in the same City. If this property is not specified, the default is
251 that the index keys of all records must be unique.
252 </p>
253 <p>
254 For a primary database, duplicate keys are not normally used
255 since a primary database with duplicate keys may not have any
256 associated secondary indices. If primary database keys are not
257 unique, there is no way for a secondary key to reference a specific
258 record in the primary database.
259 </p>
260 <p>
261 Note that <code class="methodname">setSortedDuplicates()</code> and not
262 <code class="methodname">setUnsortedDuplicates()</code> was called. Sorted
263 duplicates are always used for indices rather than unsorted duplicates,
264 since sorting enables optimized equality joins.
265 </p>
266 <p>
267 Opening a secondary key index requires creating a
268
269 <span>
270 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>.
271 </span>
272 The <code class="classname">SupplierByCityKeyCreator</code> class implements the
273
274 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
275
276 interface and will be defined below.
277 </p>
278 <p>
279 The
280
281 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>
282
283 object is opened last. If you compare the
284 <code class="methodname">openSecondaryDatabase()</code> and <code class="methodname">openDatabase()</code> methods you'll
285 notice only two differences:
286 </p>
287 <div class="itemizedlist">
288 <ul type="disc">
289 <li>
290 <p>
291 <code class="methodname">openSecondaryDatabase()</code> has an extra parameter for
292 specifying the associated primary database. The primary database is
293 <code class="literal">supplierDb</code> in this case.
294 </p>
295 </li>
296 <li>
297 <p>
298 The last parameter of <code class="methodname">openSecondaryDatabase()</code> is a
299 <code class="literal">SecondaryConfig</code> instead of a <code class="literal">DatabaseConfig</code>.
300 </p>
301 </li>
302 </ul>
303 </div>
304 <p>
305 How to use the secondary index to access records will be shown
306 in a later section.
307 </p>
308 <p>
309 The application-defined <code class="classname">SupplierByCityKeyCreator</code> class is
310 shown below. It was used above to configure the secondary
311 database.
312 </p>
313 <a id="index_supplierbycitykeycreator"></a>
314 <pre class="programlisting">public class SampleDatabase
315 {
316 ...
317 <strong class="userinput"><code> private static class SupplierByCityKeyCreator
318 extends SerialSerialKeyCreator
319 {
320 private SupplierByCityKeyCreator(ClassCatalog catalog,
321 Class primaryKeyClass,
322 Class valueClass,
323 Class indexKeyClass)
324 {
325 super(catalog, primaryKeyClass, valueClass, indexKeyClass);
326 }
327
328 public Object createSecondaryKey(Object primaryKeyInput,
329 Object valueInput)
330 {
331 SupplierData supplierData = (SupplierData) valueInput;
332 return supplierData.getCity();
333 }
334 }</code></strong>
335 ...
336 } </pre>
337 <p>
338 In general, a key creator class must implement the
339
340 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
341
342 interface. This interface has methods that operate on the record
343 data as raw bytes. In practice, it is easiest to use an abstract
344 base class that performs the conversion of record data to and from
345 the format defined for the database's key and value. The base class
346 implements the
347
348 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
349
350 interface and has abstract methods that must be implemented in turn
351 by the application.
352 </p>
353 <p>
354 In this example the
355 <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialSerialKeyCreator.html" target="_top">SerialSerialKeyCreator</a>
356
357 base class is used because the database record uses the serial
358 format for both its key and its value. The abstract methods of this
359 class have key and value parameters of type
360 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/Object.html" target="_top">Object</a>
361
362 which are automatically converted to and from the raw record data
363 by the base class.
364 </p>
365 <p>
366 To perform the conversions properly, the key creator must be
367 aware of all three formats involved: the key format of the primary
368 database record, the value format of the primary database record,
369 and the key format of the index record. The
370 <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialSerialKeyCreator.html" target="_top">SerialSerialKeyCreator</a>
371
372 constructor is given the base classes for these three formats as
373 parameters.
374 </p>
375 <p>
376 The <code class="methodname">SerialSerialKeyCreator.createSecondaryKey</code> method is
377 given the key and value of the primary database record as
378 parameters, and it returns the key of the index record. In this
379 example, the index key is a field in the primary database record
380 value. Since the record value is known to be a <code class="classname">SupplierData</code>
381 object, it is cast to that class and the city field is
382 returned.
383 </p>
384 <p>
385 Note that the <code class="literal">primaryKeyInput</code> parameter is not used in
386 the example. This parameter is needed only when an index key is
387 derived from the key of the primary database record. Normally an
388 index key is derived only from the primary database record value,
389 but it may be derived from the key, value or both.
390 </p>
391 <p>
392 The following getter methods return the secondary database
393 object for use by other classes in the example program. The
394 secondary database object is used to create Java collections for
395 accessing records via their secondary keys.
396 </p>
397 <a id="index_getsupplierbycitydatabase"></a>
398 <pre class="programlisting">public class SampleDatabase
399 {
400 ...
401 <strong class="userinput"><code> public final SecondaryDatabase getSupplierByCityDatabase()
402 {
403 return supplierByCityDb;
404 }</code></strong>
405 ...
406 } </pre>
407 <p>
408 The following statement closes the secondary database.
409 </p>
410 <a id="index_close"></a>
411 <pre class="programlisting">public class SampleDatabase
412 {
413 ...
414 public void close()
415 throws DatabaseException {
416
417 <strong class="userinput"><code> supplierByCityDb.close();</code></strong>
418 partDb.close();
419 supplierDb.close();
420 shipmentDb.close();
421 javaCatalog.close();
422 env.close();
423 }
424 ...
425 } </pre>
426 <p>
427 Secondary databases must be closed before closing their
428 associated primary database.
429 </p>
430 </div>
431 </div>
432 <div class="navfooter">
433 <hr />
434 <table width="100%" summary="Navigation footer">
435 <tr>
436 <td width="40%" align="left"><a accesskey="p" href="handlingexceptions.html">Prev</a> </td>
437 <td width="20%" align="center"> </td>
438 <td width="40%" align="right"> <a accesskey="n" href="openingforeignkeys.html">Next</a></td>
439 </tr>
440 <tr>
441 <td width="40%" align="left" valign="top">
442 Handling Exceptions
443  </td>
444 <td width="20%" align="center">
445 <a accesskey="h" href="index.html">Home</a>
446 </td>
447 <td width="40%" align="right" valign="top"> 
448
449 <span>More Secondary Key Indices</span>
450 </td>
451 </tr>
452 </table>
453 </div>
454 </body>
455 </html>