1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
|
<?xml version="1.0" encoding="ISO-8859-1" 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=ISO-8859-1" />
<title>AppendixA.
API Notes and Details
</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
<link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" />
<link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" />
<link rel="previous" href="Summary.html" title="Chapter7. 		Summary 	" />
<link rel="next" href="UsingCollectionsAPI.html" title=" Using the Sleepycat Java Collections API " />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">AppendixA.
API Notes and Details
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="Summary.html">Prev</a></td>
<th width="60%" align="center"></th>
<td width="20%" align="right"><a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="appendix" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="collectionOverview"></a>AppendixA.
API Notes and Details
</h2>
</div>
</div>
<div></div>
</div>
<p>
This appendix contains information useful to the collections programmer
that is too detailed to easily fit into the format of a tutorial.
Specifically, this appendix contains the following information:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<a href="collectionOverview.html#UsingDataBindings">
Using Data Bindings
</a>
</p>
</li>
<li>
<p>
<a href="UsingCollectionsAPI.html">
Using the Sleepycat Java Collections API
</a>
</p>
</li>
<li>
<p>
<a href="UsingStoredCollections.html">
Using Stored Collections
</a>
</p>
</li>
<li>
<p>
<a href="SerializedObjectStorage.html">
Serialized Object Storage
</a>
</p>
</li>
</ul>
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="UsingDataBindings"></a>
Using Data Bindings
</h2>
</div>
</div>
<div></div>
</div>
<p>
Data bindings determine how keys and values are represented as
stored data (byte arrays) in the database, and how stored data is
converted to and from Java objects.
</p>
<p>
The selection of data bindings is, in general, independent of
the selection of
<span> access methods and </span>
collection views. In other
words, any binding can be used with any
<span> access method or </span>
collection.
<span>
One exception to this rule is described under
<a href="collectionOverview.html#RecordNumberBindings">Record Number Bindings</a>
below.
</span>
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
In this document, bindings are described in the
context of their use for stored data in a database. However,
bindings may also be used independently of a database to operate on
an arbitrary byte array. This allows using bindings when data is to
be written to a file or sent over a network, for example.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="SelectingBindingFormats"></a>
Selecting Binding Formats
</h3>
</div>
</div>
<div></div>
</div>
<p>
For the key and value of each stored collection, you may select
one of the following types of bindings.
</p>
<div class="informaltable">
<table border="1" width="80%">
<colgroup>
<col />
<col />
<col />
</colgroup>
<thead>
<tr>
<th>Binding Format</th>
<th>Ordered</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
</td>
<td>No</td>
<td>
The data is stored using a compact form of Java serialization,
where the class descriptions are stored separately in a catalog
database. Arbitrary Java objects are supported.
</td>
</tr>
<tr>
<td>
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
</td>
<td>Yes</td>
<td>
The data is stored using a series of fixed length primitive
values or zero terminated character arrays (strings). Class/type
evolution is not supported.
</td>
</tr>
<tr>
<td>
<a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
</td>
<td>Yes</td>
<td>
The data is a 32-bit integer stored in a platform-dependent format.
</td>
</tr>
<tr>
<td>Custom binding format</td>
<td>User-defined</td>
<td>
The data storage format and ordering is determined by the
custom binding implementation.
</td>
</tr>
</tbody>
</table>
</div>
<p>
As shown in the table above, the tuple format supports built-in ordering
(without specifying a custom comparator), while the serial format does
not. This means that when a specific key order is needed, tuples should
be used instead of serial data. Alternatively, a custom BTree comparator should be
specified using
<tt class="methodname">DatabaseConfig.setBtreeComparator()</tt>. Note that
a custom BTree comparator will usually execute more slowly than the
default byte-by-byte comparison. This makes using tuples an attractive
option, since they provide ordering along with optimal performance.
</p>
<p>
The tuple binding uses less space and executes faster than the
serial binding. But once a tuple is written to a database, the
order of fields in the tuple may not be changed and fields may not
be deleted. The only type evolution allowed is the addition of
fields at the end of the tuple, and this must be explicitly
supported by the custom binding implementation.
</p>
<p>
The serial binding supports the full generality of Java
serialization including type evolution. But serialized data can
only be accessed by Java applications, its size is larger, and its
bindings are slower to execute.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="RecordNumberBindings"></a>Record Number Bindings</h3>
</div>
</div>
<div></div>
</div>
<p>
Any use of an access method with record number keys, and therefore any
use of a stored list view, requires using
<a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
as the key binding. Since Berkeley DB stores record number keys using
a platform-dependent byte order,
<a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
is needed to store record numbers properly. See
<span class="html"><a href="../../ref/am_conf/logrec.html" target="_top">logical record numbers</a> in</span>
the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i>
for more information on storing DB record numbers.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p>
You may not use
<a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
except with record number keys, as determined by the access
method. Using
<a href="../../java/com/sleepycat/bind/RecordNumberBinding.html" target="_top">RecordNumberBinding</a>
in other cases will create a database that is not portable
between platforms. When constructing the stored collection,
the Sleepycat Java Collections API will throw an
<a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a>
in such cases.
</p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="SelectingDataBindings"></a>
Selecting Data Bindings
</h3>
</div>
</div>
<div></div>
</div>
<p>
There are two types of binding interfaces. Simple entry bindings
implement the
<a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
interface and can be used for key or value objects. Entity bindings
implement the
<a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
interface and are used for combined key and value objects called
entities.
</p>
<p>
Simple entry bindings map between the key or value data stored
by Berkeley DB and a key or value object. This is a simple
one-to-one mapping.
</p>
<p>
Simple entry bindings are easy to implement and in some cases
require no coding. For example, a
<a href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
can be used for keys or values without writing any additional
code. A tuple binding for a single-item tuple can also be used without
writing any code; see the
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html#getPrimitiveBinding(java.lang.Class)" target="_top">TupleBinding.getPrimitiveBinding</a>
method.
</p>
<p>
Entity bindings must divide an entity object into its key and
value data, and then combine the key and value data to re-create
the entity object. This is a two-to-one mapping.
</p>
<p>
Entity bindings are useful when a stored application object
naturally has its primary key as a property, which is very common.
For example, an Employee object would naturally have an
EmployeeNumber property (its primary key) and an entity binding
would then be needed. Of course, entity bindings are more complex
to implement, especially if their key and data formats are
different.
</p>
<p>
Note that even when an entity binding is used a key binding is
also usually needed. For example, a key binding is used to create
key objects that are passed to the
<a href="http://java.sun.com/j2se/1.3/docs/api/java/util/Map.get().html" target="_top">Map.get()</a>
method. A key object is passed to this method even though it may
return an entity that also contains the key.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="ImplementingBindings"></a>
Implementing Bindings
</h3>
</div>
</div>
<div></div>
</div>
<p>
There are two ways to implement bindings. The first way is to
create a binding class that implements one of the two binding
interfaces,
<a href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
or
<a href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>.
For tuple bindings and serial bindings there are a number of
abstract classes that make this easier. For example, you can extend
<a href="../../java/com/sleepycat/bind/tuple/TupleBinding.html" target="_top">TupleBinding</a>
to implement a simple binding for a tuple key or value. Abstract
classes are also provided for entity bindings and are named after
the format names of the key and value. For example, you can extend
<a href="../../java/com/sleepycat/bind/serial/TupleSerialBinding.html" target="_top">TupleSerialBinding</a>
to implement an entity binding with a tuple key and serial
value.
</p>
<p>
Another way to implement bindings is with marshalling
interfaces. These are interfaces which perform the binding
operations and are implemented by the key, value or entity classes
themselves. With marshalling you use a binding which calls the
marshalling interface and you implement the marshalling interface
for each key, value or entity class. For example, you can use
<a href="../../java/com/sleepycat/bind/tuple/TupleMarshalledBinding.html" target="_top">TupleMarshalledBinding</a>
along with key or value classes that implement the
<a href="../../java/com/sleepycat/bind/tuple/MarshalledTupleEntry.html" target="_top">MarshalledTupleEntry</a>
interface.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="UsingBindings"></a>
Using Bindings
</h3>
</div>
</div>
<div></div>
</div>
<p>
Bindings are specified whenever a stored collection is created.
A key binding must be specified for map, key set and entry set
views. A value binding or entity binding must be specified for map,
value set and entry set views.
</p>
<p>
Any number of bindings may be created for the same stored data.
This allows multiple views over the same data. For example, a tuple
might be bound to an array of values or to a class with properties
for each object.
</p>
<p>
It is important to be careful of bindings that only use a subset
of the stored data. This can be useful to simplify a view or to
hide information that should not be accessible. However, if you
write records using these bindings you may create stored data that
is invalid from the application's point of view. It is up to the
application to guard against this by creating a read-only
collection when such bindings are used.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="SecondaryKeyCreators"></a>
Secondary Key Creators
</h3>
</div>
</div>
<div></div>
</div>
<p>
Secondary Key Creators are needed whenever database indices are
used. For each secondary index
<span>
(<a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>)
</span>
a key creator is used to derive index key data from key/value data.
Key creators are objects whose classes implement the
<a href="../../java/com/sleepycat/db/SecondaryKeyCreator.html" target="_top">SecondaryKeyCreator</a>
interface.
</p>
<p>
Like bindings, key creators may be implemented using a separate
key creator class or using a marshalling interface. Abstract key
creator classes and marshalling interfaces are provided in the
com.sleepycat.bind.tuple and com.sleepycat.bind.serial
packages.
</p>
<p>
Unlike bindings, key creators fundamentally operate on key and
value data, not necessarily on the objects derived from the data by
bindings. In this sense key creators are a part of a database
definition, and may be independent of the various bindings that may
be used to view data in a database. However, key creators are not
prohibited from using higher level objects produced by bindings,
and doing so may be convenient for some applications. For example,
marshalling interfaces, which are defined for objects produced by
bindings, are a convenient way to define key creators.
</p>
</div>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="Summary.html">Prev</a></td>
<td width="20%" align="center">
<a accesskey="u" href="index.html">Up</a>
</td>
<td width="40%" align="right"><a accesskey="n" href="UsingCollectionsAPI.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter7.
Summary
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top">
Using the Sleepycat Java Collections API
</td>
</tr>
</table>
</div>
</body>
</html>
|
