Debian Codegraph @

docs/collections/tutorial/BasicProgram.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 2.  The Basic Program</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="tutorialintroduction.html" title="Tutorial Introduction" />
12 <link rel="next" href="opendbenvironment.html" title="Opening and Closing the Database Environment" />
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 2. 
22 The Basic Program
23 </th>
24 </tr>
25 <tr>
26 <td width="20%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td>
27 <th width="60%" align="center"> </th>
28 <td width="20%" align="right"> <a accesskey="n" href="opendbenvironment.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="BasicProgram"></a>Chapter 2. 
38 The Basic Program
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="BasicProgram.html#keyandvalueclasses">
51 Defining Serialized Key and Value Classes
52 </a>
53 </span>
54 </dt>
55 <dt>
56 <span class="sect1">
57 <a href="opendbenvironment.html">
58 Opening and Closing the Database Environment
59 </a>
60 </span>
61 </dt>
62 <dt>
63 <span class="sect1">
64 <a href="openclasscatalog.html">
65 Opening and Closing the Class Catalog
66 </a>
67 </span>
68 </dt>
69 <dt>
70 <span class="sect1">
71 <a href="opendatabases.html">
72 Opening and Closing Databases
73 </a>
74 </span>
75 </dt>
76 <dt>
77 <span class="sect1">
78 <a href="createbindingscollections.html">
79 Creating Bindings and Collections
80 </a>
81 </span>
82 </dt>
83 <dt>
84 <span class="sect1">
85 <a href="implementingmain.html">
86 Implementing the Main Program
87 </a>
88 </span>
89 </dt>
90 <dt>
91 <span class="sect1">
92 <a href="usingtransactions.html">
93 Using Transactions
94 </a>
95 </span>
96 </dt>
97 <dt>
98 <span class="sect1">
99 <a href="addingdatabaseitems.html">
100 Adding Database Items
101 </a>
102 </span>
103 </dt>
104 <dt>
105 <span class="sect1">
106 <a href="retrievingdatabaseitems.html">
107 Retrieving Database Items
108 </a>
109 </span>
110 </dt>
111 <dt>
112 <span class="sect1">
113 <a href="handlingexceptions.html">
114 Handling Exceptions
115 </a>
116 </span>
117 </dt>
118 </dl>
119 </div>
120 <p>
121 The Basic example is a minimal implementation of the shipment
122 program. It writes and reads the part, supplier and shipment
123 databases.
124 </p>
125 <p>
126 The complete source of the final version of the example program
127 is included in the Berkeley DB distribution.
128 </p>
129 <div class="sect1" lang="en" xml:lang="en">
130 <div class="titlepage">
131 <div>
132 <div>
133 <h2 class="title" style="clear: both"><a id="keyandvalueclasses"></a>
134 Defining Serialized Key and Value Classes
135 </h2>
136 </div>
137 </div>
138 </div>
139 <p>
140 The key and value classes for each type of shipment record —
141 Parts, Suppliers and Shipments — are defined as ordinary Java
142 classes. In this example the serialized form of the key and value
143 objects is stored directly in the database. Therefore these classes
144 must implement the standard Java java.io.Serializable interface. A
145 compact form of Java serialization is used that does not duplicate
146 the class description in each record. Instead the class
147 descriptions are stored in the class catalog store, which is
148 described in the next section. But in all other respects, standard
149 Java serialization is used.
150 </p>
151 <p>
152 An important point is that instances of these classes are passed
153 and returned by value, not by reference, when they are stored and
154 retrieved from the database. This means that changing a key or
155 value object does not automatically change the database. The object
156 must be explicitly stored in the database after changing it. To
157 emphasize this point the key and value classes defined here have no
158 field setter methods. Setter methods can be defined, but it is
159 important to remember that calling a setter method will not cause
160 the change to be stored in the database. How to store and retrieve
161 objects in the database will be described later.
162 </p>
163 <p>
164 Each key and value class contains a toString method that is used
165 to output the contents of the object in the example program. This
166 is meant for illustration only and is not required for database
167 objects in general.
168 </p>
169 <p>
170 Notice that the key and value classes defined below do not
171 contain any references to <code class="literal">com.sleepycat</code> packages. An
172 important characteristic of these classes is that they are
173 independent of the database. Therefore, they may be easily used in
174 other contexts and may be defined in a way that is compatible with
175 other tools and libraries.
176 </p>
177 <p>
178 The <code class="classname">PartKey</code> class contains only the Part's Number field.
179 </p>
180 <p>
181 Note that <code class="classname">PartKey</code> (as well as <code class="classname">SupplierKey</code> below)
182 contain only a single String field. Instead of defining a specific
183 class for each type of key, the String class by itself could have
184 been used. Specific key classes were used to illustrate strong
185 typing and for consistency in the example. The use of a plain
186 String as an index key is illustrated in the next example program.
187 It is up to the developer to use either primitive Java classes such
188 as String and Integer, or strongly typed classes. When
189 there is the possibility that fields will be added later to a key
190 or value, a specific class should be used.
191
192 </p>
193 <a id="cb_partkey"></a>
194 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
195
196 public class PartKey implements Serializable
197 {
198 private String number;
199
200 public PartKey(String number) {
201 this.number = number;
202 }
203
204 public final String getNumber() {
205 return number;
206 }
207
208 public String toString() {
209 return "[PartKey: number=" + number + ']';
210 }
211 }</code></strong> </pre>
212 <p>
213 The <code class="classname">PartData</code> class contains the Part's Name, Color,
214 Weight and City fields.
215 </p>
216 <a id="cb_partdata"></a>
217 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
218
219 public class PartData implements Serializable
220 {
221 private String name;
222 private String color;
223 private Weight weight;
224 private String city;
225
226 public PartData(String name, String color, Weight weight, String city)
227 {
228 this.name = name;
229 this.color = color;
230 this.weight = weight;
231 this.city = city;
232 }
233
234 public final String getName()
235 {
236 return name;
237 }
238
239 public final String getColor()
240 {
241 return color;
242 }
243
244 public final Weight getWeight()
245 {
246 return weight;
247 }
248
249 public final String getCity()
250 {
251 return city;
252 }
253
254 public String toString()
255 {
256 return "[PartData: name=" + name +
257 " color=" + color +
258 " weight=" + weight +
259 " city=" + city + ']';
260 }
261 }</code></strong> </pre>
262 <p>
263 The <code class="classname">Weight</code> class is also defined here, and is used as the
264 type of the Part's Weight field. Just as in standard Java
265 serialization, nothing special is needed to store nested objects as
266 long as they are all Serializable.
267 </p>
268 <a id="cb_weight"></a>
269 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
270
271 public class Weight implements Serializable
272 {
273 public final static String GRAMS = "grams";
274 public final static String OUNCES = "ounces";
275
276 private double amount;
277 private String units;
278
279 public Weight(double amount, String units)
280 {
281 this.amount = amount;
282 this.units = units;
283 }
284
285 public final double getAmount()
286 {
287 return amount;
288 }
289
290 public final String getUnits()
291 {
292 return units;
293 }
294
295 public String toString()
296 {
297 return "[" + amount + ' ' + units + ']';
298 }
299 }</code></strong> </pre>
300 <p>
301 The <code class="classname">SupplierKey</code> class contains the Supplier's Number
302 field.
303 </p>
304 <a id="cb_supplierkey"></a>
305 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
306
307 public class SupplierKey implements Serializable
308 {
309 private String number;
310
311 public SupplierKey(String number)
312 {
313 this.number = number;
314 }
315
316 public final String getNumber()
317 {
318 return number;
319 }
320
321 public String toString()
322 {
323 return "[SupplierKey: number=" + number + ']';
324 }
325 }</code></strong> </pre>
326 <p>
327 The <code class="classname">SupplierData</code> class contains the Supplier's Name,
328 Status and City fields.
329 </p>
330 <a id="cb_supplierdata"></a>
331 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
332
333 public class SupplierData implements Serializable
334 {
335 private String name;
336 private int status;
337 private String city;
338
339 public SupplierData(String name, int status, String city)
340 {
341 this.name = name;
342 this.status = status;
343 this.city = city;
344 }
345
346 public final String getName()
347 {
348 return name;
349 }
350
351 public final int getStatus()
352 {
353 return status;
354 }
355
356 public final String getCity()
357 {
358 return city;
359 }
360
361 public String toString()
362 {
363 return "[SupplierData: name=" + name +
364 " status=" + status +
365 " city=" + city + ']';
366 }
367 }</code></strong>
368 </pre>
369 <p>
370 The <code class="classname">ShipmentKey</code> class contains the keys of both the Part
371 and Supplier.
372 </p>
373 <a id="cb_shipmentkey"></a>
374 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
375
376 public class ShipmentKey implements Serializable
377 {
378 private String partNumber;
379 private String supplierNumber;
380
381 public ShipmentKey(String partNumber, String supplierNumber)
382 {
383 this.partNumber = partNumber;
384 this.supplierNumber = supplierNumber;
385 }
386
387 public final String getPartNumber()
388 {
389 return partNumber;
390 }
391
392 public final String getSupplierNumber()
393 {
394 return supplierNumber;
395 }
396
397 public String toString()
398 {
399 return "[ShipmentKey: supplier=" + supplierNumber +
400 " part=" + partNumber + ']';
401 }
402 }</code></strong> </pre>
403 <p>
404 The <code class="classname">ShipmentData</code> class contains only the Shipment's
405 Quantity field. Like <code class="classname">PartKey</code> and <code class="classname">SupplierKey</code>,
406 <code class="classname">ShipmentData</code> contains only a single primitive field.
407 Therefore the Integer class could have been used instead of
408 defining a specific value class.
409 </p>
410 <a id="cb_shipmentdata"></a>
411 <pre class="programlisting"><strong class="userinput"><code>import java.io.Serializable;
412
413 public class ShipmentData implements Serializable
414 {
415 private int quantity;
416
417 public ShipmentData(int quantity)
418 {
419 this.quantity = quantity;
420 }
421
422 public final int getQuantity()
423 {
424 return quantity;
425 }
426
427 public String toString()
428 {
429 return "[ShipmentData: quantity=" + quantity + ']';
430 }
431 }</code></strong> </pre>
432 </div>
433 </div>
434 <div class="navfooter">
435 <hr />
436 <table width="100%" summary="Navigation footer">
437 <tr>
438 <td width="40%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td>
439 <td width="20%" align="center"> </td>
440 <td width="40%" align="right"> <a accesskey="n" href="opendbenvironment.html">Next</a></td>
441 </tr>
442 <tr>
443 <td width="40%" align="left" valign="top">Tutorial Introduction </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 Opening and Closing the Database Environment
449 </td>
450 </tr>
451 </table>
452 </div>
453 </body>
454 </html>