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
|
<?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>Creating Indexes</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" />
<link rel="up" href="persist_index.html" title="Chapter 4. Working with Indices" />
<link rel="prev" href="persist_index.html" title="Chapter 4. Working with Indices" />
<link rel="next" href="persist_access.html" title="Chapter 5. Saving and Retrieving Objects" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.1.6.1</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Creating Indexes</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="persist_index.html">Prev</a> </td>
<th width="60%" align="center">Chapter 4. Working with Indices</th>
<td width="20%" align="right"> <a accesskey="n" href="persist_access.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="dplindexcreate"></a>Creating Indexes</h2>
</div>
</div>
</div>
<div class="toc">
<dl>
<dt>
<span class="sect2">
<a href="dplindexcreate.html#dplprimaryidxdecl">Declaring a Primary Indexes</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="dplindexcreate.html#dplsecondaryidxdecl">Declaring Secondary Indexes</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="dplindexcreate.html#foreignkey">Foreign Key Constraints</a>
</span>
</dt>
</dl>
</div>
<p>
To create an index using the DPL, you use Java
annotations to declare which feature on the class is used
for the primary index, and which features (if any) are to
be used as secondary indexes.
</p>
<p>
All entity classes stored in the DPL must have a
primary index declared for it.
</p>
<p>
Entity classes can have zero or more secondary
indexes declared for them. There is no limit on the
number of secondary indexes that you can declare.
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="dplprimaryidxdecl"></a>Declaring a Primary Indexes</h3>
</div>
</div>
</div>
<p>
You declare a primary key for an entity class by
using the <code class="literal">@PrimaryKey</code>
annotation. This annotation must appear
immediately before the data member which
represents the class's primary key. For example:
</p>
<pre class="programlisting">package persist.gettingStarted;
import com.sleepycat.persist.model.Entity;
import com.sleepycat.persist.model.PrimaryKey;
@Entity
public class Vendor {
private String address;
private String bizPhoneNumber;
private String city;
private String repName;
private String repPhoneNumber;
private String state;
// Primary key is the vendor's name
// This assumes that the vendor's name is
// unique in the database.
@PrimaryKey
private String vendor;
... </pre>
<p>
For this class, the <code class="literal">vendor</code> value is set for an individual
<code class="classname">Vendor</code> class object by
the <code class="methodname">setVendorName()</code>
method. If our example code fails to set this
value before storing the object, the data
member used to store the primary key is set to a
null value. This would result in a runtime
error.
</p>
<p>
You can avoid the need to explicitly set a
value for a class's primary index by specifying
a sequence to be used for the primary key. This
results in an unique integer value being used
as the primary key for each stored object.
</p>
<p>
You declare a sequence is to be used by specifying
the <code class="literal">sequence</code> keyword to the
<code class="literal">@PrimaryKey</code> annotation. You must
also provide a name for the sequence. For example:
For example:
</p>
<pre class="programlisting">@PrimaryKey(sequence="Sequence_Namespace")
long myPrimaryKey; </pre>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="dplsecondaryidxdecl"></a>Declaring Secondary Indexes</h3>
</div>
</div>
</div>
<p>
To declare a secondary index, we use the
<code class="literal">@SecondaryKey</code> annotation. Note
that when we do this, we must declare what sort of
an index it is; that is, what is its relationship to
other data in the data store.
</p>
<p>
The <span class="emphasis"><em>kind</em></span> of indices that we
can declare are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<code class="literal">ONE_TO_ONE</code>
</p>
<p>
This relationship indicates that
the secondary key is unique to the
object. If an object is stored with a
secondary key that already
exists in the data store, a run
time error is raised.
</p>
<p>
For example, a person object might
be stored with a primary key of a
social security number (in the US),
with a secondary key of the
person's employee number. Both
values are expected to be unique in
the data store.
</p>
</li>
<li>
<p>
<code class="literal">MANY_TO_ONE</code>
</p>
<p>
Indicates that the secondary key
may be used for multiple
objects in the data store. That is,
the key appears more than
once, but for each stored object it
can be used only once.
</p>
<p>
Consider a data store that relates
managers to employees. A given
manager will have multiple
employees, but each employee is
assumed to have just one manager.
In this case, the manager's
employee number might be a
secondary key, so that you can
quickly locate all the objects
related to that manager's
employees.
</p>
</li>
<li>
<p>
<code class="literal">ONE_TO_MANY</code>
</p>
<p>
Indicates that the secondary key
might be used more than once for a
given object. Index keys
themselves are assumed to be
unique, but multiple instances of
the index can be used per object.
</p>
<p>
For example, employees might have
multiple unique email addresses. In
this case, any given object can be
access by one or more email
addresses. Each such address is
unique in the data store, but each
such address will relate to a
single employee object.
</p>
</li>
<li>
<p>
<code class="literal">MANY_TO_MANY</code>
</p>
<p>
There can be multiple keys for
any given object, and for any given
key there can be many related
objects.
</p>
<p>
For example, suppose your
organization has a shared
resource, such as printers. You
might want to track which
printers a given employee can
use (there might be more than
one). You might also want to
track which employees can use a
specific printer. This
represents a many-to-many
relationship.
</p>
</li>
</ul>
</div>
<p>
Note that for <code class="literal">ONE_TO_ONE</code> and
<code class="literal">MANY_TO_ONE</code> relationships, you
need a simple data member (not an array or
collection) to hold the key. For
<code class="literal">ONE_TO_MANY</code> and
<code class="literal">MANY_TO_MANY</code> relationships, you
need an array or collection to hold the keys:
</p>
<pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE)
private String primaryEmailAddress = new String();
@SecondaryKey(relate=ONE_TO_MANY)
private Set<String> emailAddresses = new HashSet<String>(); </pre>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="foreignkey"></a>Foreign Key Constraints</h3>
</div>
</div>
</div>
<p>
Sometimes a secondary index is related in some
way to another entity class that is also
contained in the data store. That is, the
secondary key might be the primary key for
another entity class. If this is the case, you
can declare the foreign key constraint to make
data integrity easier to accomplish.
</p>
<p>
For example, you might have one class that is
used to represent employees.
You might have another that is used to
represent corporate divisions. When you add or
modify an employee record, you might want to
ensure that the division to which the employee
belongs is known to the data store. You do this
by specifying a foreign key constraint.
</p>
<p>
When a foreign key constraint is declared:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
When a new secondary key
for the object is stored,
it is checked to make sure
it exists as a primary
key for the related
entity object. If it does
not, a runtime error
occurs.
</p>
</li>
<li>
<p>
When a related entity is
deleted (that is, a
corporate division is
removed from the data
store), some action is
automatically taken for
the entities that refer to
this object (that is, the
employee objects). Exactly
what that action is, is
definable by you. See
below.
</p>
</li>
</ul>
</div>
<p>
When a related entity is deleted from the data
store, one of the following actions are taken:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<code class="literal">ABORT</code>
</p>
<p>
The delete operation is not
allowed. A runtime error is
raised as a result of the
operation. This is the
default behavior.
</p>
</li>
<li>
<p>
<code class="literal">CASCADE</code>
</p>
<p>
All entities related to this
one are deleted as well. For
example, if you deleted a
<code class="classname">Division</code>
object, then all
<code class="classname">Employee</code>
objects that belonged to the
division are also deleted.
</p>
</li>
<li>
<p>
<code class="literal">NULLIFY</code>
</p>
<p>
All entities related to the
deleted entity are updated so
that the pertinent data member
is nullified. That is, if you
deleted a division, then all
employee objects related to
that division would have their
division key
automatically set to null.
</p>
</li>
</ul>
</div>
<p>
You declare a foreign key constraint by using
the <code class="literal">relatedEntity</code> keyword. You
declare the foreign key constraint deletion policy using the
<code class="literal">onRelatedEntityDelete</code> keyword. For
example, the following declares a foreign key
constraint to <code class="classname">Division</code>
class objects, and it causes related objects to
be deleted if the <code class="classname">Division</code>
class is deleted:
</p>
<pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE, relatedEntity=Division.class,
onRelatedEntityDelete=CASCADE)
private String division = new String(); </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="persist_index.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="persist_index.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="persist_access.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Chapter 4. Working with Indices </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Chapter 5. Saving and Retrieving Objects</td>
</tr>
</table>
</div>
</body>
</html>
|
