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
|
<?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>Chapter 4. Using Entity Classes</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="Berkeley DB Collections Tutorial" />
<link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" />
<link rel="prev" href="retrievingbyindexkey.html" title="Retrieving Items by Index Key" />
<link rel="next" href="creatingentitybindings.html" title="Creating Entity Bindings" />
</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">Chapter 4.
Using Entity Classes
</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="retrievingbyindexkey.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="creatingentitybindings.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="Entity"></a>Chapter 4.
Using Entity Classes
</h2>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<a href="Entity.html#definingentityclasses">
Defining Entity Classes
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="creatingentitybindings.html">
Creating Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="collectionswithentities.html">
Creating Collections with Entity Bindings
</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="entitieswithcollections.html">
Using Entities with Collections
</a>
</span>
</dt>
</dl>
</div>
<p>
In the prior examples, the keys and values of each store were
represented using separate classes. For example, a <code class="classname">PartKey</code>
and a <code class="classname">PartData</code> class were used. Many times it is desirable
to have a single class representing both the key and the value, for
example, a <code class="classname">Part</code> class.
</p>
<p>
Such a combined key and value class is called an <span class="emphasis"><em>entity
class</em></span> and is used along with an <span class="emphasis"><em>entity binding</em></span>. Entity
bindings combine a key and a value into an entity when reading a
record from a collection, and split an entity into a key and a
value when writing a record to a collection. Entity bindings are
used in place of value bindings, and entity objects are used with
collections in place of value objects.
</p>
<p>
Some reasons for using entities are:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
When the key is a property of an entity object representing the
record as a whole, the object's identity and concept are often
clearer than with key and value objects that are disjoint.
</p>
</li>
<li>
<p>
A single entity object per record is often more convenient to
use than two objects.
</p>
</li>
</ul>
</div>
<p>
Of course, instead of using an entity binding, you could simply
create the entity yourself after reading the key and value from a
collection, and split the entity into a key and value yourself
before writing it to a collection. But this would detract from the
convenience of the using the Java collections API. It is convenient
to obtain a <code class="classname">Part</code> object directly from
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#get(java.lang.Object)" target="_top">Map.get</a>
and to add a <code class="classname">Part</code> object using
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html#add(E)" target="_top">Set.add</a>.
Collections having entity bindings can be used naturally without
combining and splitting objects each time a collection method is
called; however, an entity binding class must be defined by the
application.
</p>
<p>
In addition to showing how to use entity bindings, this example
illustrates a key feature of all bindings: Bindings are independent
of database storage parameters and formats. Compare this example to
the prior Index example and you'll see that the <code class="classname">Sample</code> and
<code class="classname">SampleViews</code> classes have been changed to use entity
bindings, but the <code class="classname">SampleDatabase</code> class was not changed at
all. In fact, the Entity program and the Index program can be used
interchangeably to access the same physical database files. This
demonstrates that bindings are only a "view" onto the physical
stored data.
</p>
<p>
<code class="classname">Warning:</code> When using multiple bindings for the same
database, it is the application's responsibility to ensure that the
same format is used for all bindings. For example, a serial binding
and a tuple binding cannot be used to access the same records.
</p>
<p>
The complete source of the final version of the example program
is included in the Berkeley DB distribution.
</p>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="definingentityclasses"></a>
Defining Entity Classes
</h2>
</div>
</div>
</div>
<p>
As described in the prior section, <span class="emphasis"><em>entity classes</em></span> are
combined key/value classes that are managed by entity bindings. In
this example the <code class="classname">Part</code>, <code class="classname">Supplier</code> and <code class="classname">Shipment</code>
classes are entity classes. These classes contain fields that are a
union of the fields of the key and value classes that were defined
earlier for each store.
</p>
<p>
In general, entity classes may be defined in any way desired by
the application. The entity binding, which is also defined by the
application, is responsible for mapping between key/value objects
and entity objects.
</p>
<p>
The <code class="classname">Part</code>, <code class="classname">Supplier</code> and <code class="classname">Shipment</code>
entity classes are
defined below.
</p>
<p>
An important difference between the entity classes defined here
and the key and value classes defined earlier is that the entity
classes are not serializable (do not implement the
<a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/io/Serializable.html" target="_top">Serializable</a>
interface). This is because the entity classes are not directly
stored. The entity binding decomposes an entity object into key and
value objects, and only the key and value objects are serialized
for storage.
</p>
<p>
One advantage of using entities can already be seen in the
<code class="methodname">toString()</code> method of the classes below. These return debugging
output for the combined key and value, and will be used later to
create a listing of the database that is more readable than in the
prior examples.
</p>
<a id="entity_part"></a>
<pre class="programlisting"><strong class="userinput"><code>public class Part
{
private String number;
private String name;
private String color;
private Weight weight;
private String city;
public Part(String number, String name, String color, Weight weight,
String city)
{
this.number = number;
this.name = name;
this.color = color;
this.weight = weight;
this.city = city;
}
public final String getNumber()
{
return number;
}
public final String getName()
{
return name;
}
public final String getColor()
{
return color;
}
public final Weight getWeight()
{
return weight;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "Part: number=" + number +
" name=" + name +
" color=" + color +
" weight=" + weight +
" city=" + city + '.';
}
}</code></strong> </pre>
<a id="entity_supplier"></a>
<pre class="programlisting"><strong class="userinput"><code>public class Supplier
{
private String number;
private String name;
private int status;
private String city;
public Supplier(String number, String name, int status, String city)
{
this.number = number;
this.name = name;
this.status = status;
this.city = city;
}
public final String getNumber()
{
return number;
}
public final String getName()
{
return name;
}
public final int getStatus()
{
return status;
}
public final String getCity()
{
return city;
}
public String toString()
{
return "Supplier: number=" + number +
" name=" + name +
" status=" + status +
" city=" + city + '.';
}
} </code></strong> </pre>
<a id="entity_shipment"></a>
<pre class="programlisting"><strong class="userinput"><code>public class Shipment
{
private String partNumber;
private String supplierNumber;
private int quantity;
public Shipment(String partNumber, String supplierNumber, int quantity)
{
this.partNumber = partNumber;
this.supplierNumber = supplierNumber;
this.quantity = quantity;
}
public final String getPartNumber()
{
return partNumber;
}
public final String getSupplierNumber()
{
return supplierNumber;
}
public final int getQuantity()
{
return quantity;
}
public String toString()
{
return "Shipment: part=" + partNumber +
" supplier=" + supplierNumber +
" quantity=" + quantity + '.';
}
} </code></strong> </pre>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="retrievingbyindexkey.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="creatingentitybindings.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">
Retrieving Items by Index Key
</td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top">
Creating Entity Bindings
</td>
</tr>
</table>
</div>
</body>
</html>
|
