Debian Codegraph @

docs/collections/tutorial/Entity.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 4.  Using Entity Classes</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="retrievingbyindexkey.html" title="Retrieving Items by Index Key" />
12 <link rel="next" href="creatingentitybindings.html" title="Creating Entity Bindings" />
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 4. 
22 Using Entity Classes
23 </th>
24 </tr>
25 <tr>
26 <td width="20%" align="left"><a accesskey="p" href="retrievingbyindexkey.html">Prev</a> </td>
27 <th width="60%" align="center"> </th>
28 <td width="20%" align="right"> <a accesskey="n" href="creatingentitybindings.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="Entity"></a>Chapter 4. 
38 Using Entity Classes
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="Entity.html#definingentityclasses">
51 Defining Entity Classes
52 </a>
53 </span>
54 </dt>
55 <dt>
56 <span class="sect1">
57 <a href="creatingentitybindings.html">
58 Creating Entity Bindings
59 </a>
60 </span>
61 </dt>
62 <dt>
63 <span class="sect1">
64 <a href="collectionswithentities.html">
65 Creating Collections with Entity Bindings
66 </a>
67 </span>
68 </dt>
69 <dt>
70 <span class="sect1">
71 <a href="entitieswithcollections.html">
72 Using Entities with Collections
73 </a>
74 </span>
75 </dt>
76 </dl>
77 </div>
78 <p>
79 In the prior examples, the keys and values of each store were
80 represented using separate classes. For example, a <code class="classname">PartKey</code>
81 and a <code class="classname">PartData</code> class were used. Many times it is desirable
82 to have a single class representing both the key and the value, for
83 example, a <code class="classname">Part</code> class.
84 </p>
85 <p>
86 Such a combined key and value class is called an <span class="emphasis"><em>entity
87 class</em></span> and is used along with an <span class="emphasis"><em>entity binding</em></span>. Entity
88 bindings combine a key and a value into an entity when reading a
89 record from a collection, and split an entity into a key and a
90 value when writing a record to a collection. Entity bindings are
91 used in place of value bindings, and entity objects are used with
92 collections in place of value objects.
93 </p>
94 <p>
95 Some reasons for using entities are:
96 </p>
97 <div class="itemizedlist">
98 <ul type="disc">
99 <li>
100 <p>
101 When the key is a property of an entity object representing the
102 record as a whole, the object's identity and concept are often
103 clearer than with key and value objects that are disjoint.
104 </p>
105 </li>
106 <li>
107 <p>
108 A single entity object per record is often more convenient to
109 use than two objects.
110 </p>
111 </li>
112 </ul>
113 </div>
114 <p>
115 Of course, instead of using an entity binding, you could simply
116 create the entity yourself after reading the key and value from a
117 collection, and split the entity into a key and value yourself
118 before writing it to a collection. But this would detract from the
119 convenience of the using the Java collections API. It is convenient
120 to obtain a <code class="classname">Part</code> object directly from
121 <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>
122
123 and to add a <code class="classname">Part</code> object using
124 <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>.
125 Collections having entity bindings can be used naturally without
126 combining and splitting objects each time a collection method is
127 called; however, an entity binding class must be defined by the
128 application.
129 </p>
130 <p>
131 In addition to showing how to use entity bindings, this example
132 illustrates a key feature of all bindings: Bindings are independent
133 of database storage parameters and formats. Compare this example to
134 the prior Index example and you'll see that the <code class="classname">Sample</code> and
135 <code class="classname">SampleViews</code> classes have been changed to use entity
136 bindings, but the <code class="classname">SampleDatabase</code> class was not changed at
137 all. In fact, the Entity program and the Index program can be used
138 interchangeably to access the same physical database files. This
139 demonstrates that bindings are only a "view" onto the physical
140 stored data.
141 </p>
142 <p>
143 <code class="classname">Warning:</code> When using multiple bindings for the same
144 database, it is the application's responsibility to ensure that the
145 same format is used for all bindings. For example, a serial binding
146 and a tuple binding cannot be used to access the same records.
147 </p>
148 <p>
149 The complete source of the final version of the example program
150 is included in the Berkeley DB distribution.
151 </p>
152 <div class="sect1" lang="en" xml:lang="en">
153 <div class="titlepage">
154 <div>
155 <div>
156 <h2 class="title" style="clear: both"><a id="definingentityclasses"></a>
157 Defining Entity Classes
158 </h2>
159 </div>
160 </div>
161 </div>
162 <p>
163 As described in the prior section, <span class="emphasis"><em>entity classes</em></span> are
164 combined key/value classes that are managed by entity bindings. In
165 this example the <code class="classname">Part</code>, <code class="classname">Supplier</code> and <code class="classname">Shipment</code>
166 classes are entity classes. These classes contain fields that are a
167 union of the fields of the key and value classes that were defined
168 earlier for each store.
169 </p>
170 <p>
171 In general, entity classes may be defined in any way desired by
172 the application. The entity binding, which is also defined by the
173 application, is responsible for mapping between key/value objects
174 and entity objects.
175 </p>
176 <p>
177 The <code class="classname">Part</code>, <code class="classname">Supplier</code> and <code class="classname">Shipment</code>
178 entity classes are
179 defined below.
180 </p>
181 <p>
182 An important difference between the entity classes defined here
183 and the key and value classes defined earlier is that the entity
184 classes are not serializable (do not implement the
185 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/io/Serializable.html" target="_top">Serializable</a>
186
187 interface). This is because the entity classes are not directly
188 stored. The entity binding decomposes an entity object into key and
189 value objects, and only the key and value objects are serialized
190 for storage.
191 </p>
192 <p>
193 One advantage of using entities can already be seen in the
194 <code class="methodname">toString()</code> method of the classes below. These return debugging
195 output for the combined key and value, and will be used later to
196 create a listing of the database that is more readable than in the
197 prior examples.
198 </p>
199 <a id="entity_part"></a>
200 <pre class="programlisting"><strong class="userinput"><code>public class Part
201 {
202 private String number;
203 private String name;
204 private String color;
205 private Weight weight;
206 private String city;
207
208 public Part(String number, String name, String color, Weight weight,
209 String city)
210 {
211 this.number = number;
212 this.name = name;
213 this.color = color;
214 this.weight = weight;
215 this.city = city;
216 }
217
218 public final String getNumber()
219 {
220 return number;
221 }
222
223 public final String getName()
224 {
225 return name;
226 }
227
228 public final String getColor()
229 {
230 return color;
231 }
232
233 public final Weight getWeight()
234 {
235 return weight;
236 }
237
238 public final String getCity()
239 {
240 return city;
241 }
242
243 public String toString()
244 {
245 return "Part: number=" + number +
246 " name=" + name +
247 " color=" + color +
248 " weight=" + weight +
249 " city=" + city + '.';
250 }
251 }</code></strong> </pre>
252 <a id="entity_supplier"></a>
253 <pre class="programlisting"><strong class="userinput"><code>public class Supplier
254 {
255 private String number;
256 private String name;
257 private int status;
258 private String city;
259
260 public Supplier(String number, String name, int status, String city)
261 {
262 this.number = number;
263 this.name = name;
264 this.status = status;
265 this.city = city;
266 }
267
268 public final String getNumber()
269 {
270 return number;
271 }
272
273 public final String getName()
274 {
275 return name;
276 }
277
278 public final int getStatus()
279 {
280 return status;
281 }
282
283 public final String getCity()
284 {
285 return city;
286 }
287
288 public String toString()
289 {
290 return "Supplier: number=" + number +
291 " name=" + name +
292 " status=" + status +
293 " city=" + city + '.';
294 }
295 } </code></strong> </pre>
296 <a id="entity_shipment"></a>
297 <pre class="programlisting"><strong class="userinput"><code>public class Shipment
298 {
299 private String partNumber;
300 private String supplierNumber;
301 private int quantity;
302
303 public Shipment(String partNumber, String supplierNumber, int quantity)
304 {
305 this.partNumber = partNumber;
306 this.supplierNumber = supplierNumber;
307 this.quantity = quantity;
308 }
309
310 public final String getPartNumber()
311 {
312 return partNumber;
313 }
314
315 public final String getSupplierNumber()
316 {
317 return supplierNumber;
318 }
319
320 public final int getQuantity()
321 {
322 return quantity;
323 }
324
325 public String toString()
326 {
327 return "Shipment: part=" + partNumber +
328 " supplier=" + supplierNumber +
329 " quantity=" + quantity + '.';
330 }
331 } </code></strong> </pre>
332 </div>
333 </div>
334 <div class="navfooter">
335 <hr />
336 <table width="100%" summary="Navigation footer">
337 <tr>
338 <td width="40%" align="left"><a accesskey="p" href="retrievingbyindexkey.html">Prev</a> </td>
339 <td width="20%" align="center"> </td>
340 <td width="40%" align="right"> <a accesskey="n" href="creatingentitybindings.html">Next</a></td>
341 </tr>
342 <tr>
343 <td width="40%" align="left" valign="top">
344 Retrieving Items by Index Key
345  </td>
346 <td width="20%" align="center">
347 <a accesskey="h" href="index.html">Home</a>
348 </td>
349 <td width="40%" align="right" valign="top"> 
350 Creating Entity Bindings
351 </td>
352 </tr>
353 </table>
354 </div>
355 </body>
356 </html>