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. 7 The Basic Program 8 </title> 9 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 10 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 11 <link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" /> 12 <link rel="up" href="index.html" title="Berkeley DB Collections Tutorial" /> 13 <link rel="previous" href="tutorialintroduction.html" title="Tutorial Introduction" /> 14 <link rel="next" href="opendbenvironment.html" title=" 		Opening and Closing the Database Environment 	" /> 15 </head> 16 <body> 17 <div class="navheader"> 18 <table width="100%" summary="Navigation header"> 19 <tr> 20 <th colspan="3" align="center">Chapter 2. 21 The Basic Program 22 </th> 23 </tr> 24 <tr> 25 <td width="20%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td> 26 <th width="60%" align="center"> </th> 27 <td width="20%" align="right"> <a accesskey="n" href="opendbenvironment.html">Next</a></td> 28 </tr> 29 </table> 30 <hr /> 31 </div> 32 <div class="chapter" lang="en" xml:lang="en"> 33 <div class="titlepage"> 34 <div> 35 <div> 36 <h2 class="title"><a id="BasicProgram"></a>Chapter 2. 37 The Basic Program 38 </h2> 39 </div> 40 </div> 41 <div></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></div> 139 </div> 140 <p> 141 The key and value classes for each type of shipment record — 142 Parts, Suppliers and Shipments — are defined as ordinary Java 143 classes. In this example the serialized form of the key and value 144 objects is stored directly in the database. Therefore these classes 145 must implement the standard Java java.io.Serializable interface. A 146 compact form of Java serialization is used that does not duplicate 147 the class description in each record. Instead the class 148 descriptions are stored in the class catalog store, which is 149 described in the next section. But in all other respects, standard 150 Java serialization is used. 151</p> 152 <p> 153 An important point is that instances of these classes are passed 154 and returned by value, not by reference, when they are stored and 155 retrieved from the database. This means that changing a key or 156 value object does not automatically change the database. The object 157 must be explicitly stored in the database after changing it. To 158 emphasize this point the key and value classes defined here have no 159 field setter methods. Setter methods can be defined, but it is 160 important to remember that calling a setter method will not cause 161 the change to be stored in the database. How to store and retrieve 162 objects in the database will be described later. 163</p> 164 <p> 165 Each key and value class contains a toString method that is used 166 to output the contents of the object in the example program. This 167 is meant for illustration only and is not required for database 168 objects in general. 169</p> 170 <p> 171 Notice that the key and value classes defined below do not 172 contain any references to <tt class="literal">com.sleepycat</tt> packages. An 173 important characteristic of these classes is that they are 174 independent of the database. Therefore, they may be easily used in 175 other contexts and may be defined in a way that is compatible with 176 other tools and libraries. 177</p> 178 <p> 179 The <tt class="classname">PartKey</tt> class contains only the Part's Number field. 180</p> 181 <p> 182 Note that <tt class="classname">PartKey</tt> (as well as <tt class="classname">SupplierKey</tt> below) 183 contain only a single String field. Instead of defining a specific 184 class for each type of key, the String class by itself could have 185 been used. Specific key classes were used to illustrate strong 186 typing and for consistency in the example. The use of a plain 187 String as an index key is illustrated in the next example program. 188 It is up to the developer to use either primitive Java classes such 189 as String and Integer, or strongly typed classes. When 190 there is the possibility that fields will be added later to a key 191 or value, a specific class should be used. 192 193</p> 194 <a id="cb_partkey"></a> 195 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 196 197public class PartKey implements Serializable 198{ 199 private String number; 200 201 public PartKey(String number) { 202 this.number = number; 203 } 204 205 public final String getNumber() { 206 return number; 207 } 208 209 public String toString() { 210 return "[PartKey: number=" + number + ']'; 211 } 212}</tt></b> </pre> 213 <p> 214 The <tt class="classname">PartData</tt> class contains the Part's Name, Color, 215 Weight and City fields. 216</p> 217 <a id="cb_partdata"></a> 218 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 219 220public class PartData implements Serializable 221{ 222 private String name; 223 private String color; 224 private Weight weight; 225 private String city; 226 227 public PartData(String name, String color, Weight weight, String city) 228 { 229 this.name = name; 230 this.color = color; 231 this.weight = weight; 232 this.city = city; 233 } 234 235 public final String getName() 236 { 237 return name; 238 } 239 240 public final String getColor() 241 { 242 return color; 243 } 244 245 public final Weight getWeight() 246 { 247 return weight; 248 } 249 250 public final String getCity() 251 { 252 return city; 253 } 254 255 public String toString() 256 { 257 return "[PartData: name=" + name + 258 " color=" + color + 259 " weight=" + weight + 260 " city=" + city + ']'; 261 } 262}</tt></b> </pre> 263 <p> 264 The <tt class="classname">Weight</tt> class is also defined here, and is used as the 265 type of the Part's Weight field. Just as in standard Java 266 serialization, nothing special is needed to store nested objects as 267 long as they are all Serializable. 268</p> 269 <a id="cb_weight"></a> 270 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 271 272public class Weight implements Serializable 273{ 274 public final static String GRAMS = "grams"; 275 public final static String OUNCES = "ounces"; 276 277 private double amount; 278 private String units; 279 280 public Weight(double amount, String units) 281 { 282 this.amount = amount; 283 this.units = units; 284 } 285 286 public final double getAmount() 287 { 288 return amount; 289 } 290 291 public final String getUnits() 292 { 293 return units; 294 } 295 296 public String toString() 297 { 298 return "[" + amount + ' ' + units + ']'; 299 } 300}</tt></b> </pre> 301 <p> 302 The <tt class="classname">SupplierKey</tt> class contains the Supplier's Number 303 field. 304</p> 305 <a id="cb_supplierkey"></a> 306 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 307 308public class SupplierKey implements Serializable 309{ 310 private String number; 311 312 public SupplierKey(String number) 313 { 314 this.number = number; 315 } 316 317 public final String getNumber() 318 { 319 return number; 320 } 321 322 public String toString() 323 { 324 return "[SupplierKey: number=" + number + ']'; 325 } 326}</tt></b> </pre> 327 <p> 328 The <tt class="classname">SupplierData</tt> class contains the Supplier's Name, 329 Status and City fields. 330</p> 331 <a id="cb_supplierdata"></a> 332 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 333 334public class SupplierData implements Serializable 335{ 336 private String name; 337 private int status; 338 private String city; 339 340 public SupplierData(String name, int status, String city) 341 { 342 this.name = name; 343 this.status = status; 344 this.city = city; 345 } 346 347 public final String getName() 348 { 349 return name; 350 } 351 352 public final int getStatus() 353 { 354 return status; 355 } 356 357 public final String getCity() 358 { 359 return city; 360 } 361 362 public String toString() 363 { 364 return "[SupplierData: name=" + name + 365 " status=" + status + 366 " city=" + city + ']'; 367 } 368}</tt></b> 369 </pre> 370 <p> 371 The <tt class="classname">ShipmentKey</tt> class contains the keys of both the Part 372 and Supplier. 373</p> 374 <a id="cb_shipmentkey"></a> 375 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 376 377public class ShipmentKey implements Serializable 378{ 379 private String partNumber; 380 private String supplierNumber; 381 382 public ShipmentKey(String partNumber, String supplierNumber) 383 { 384 this.partNumber = partNumber; 385 this.supplierNumber = supplierNumber; 386 } 387 388 public final String getPartNumber() 389 { 390 return partNumber; 391 } 392 393 public final String getSupplierNumber() 394 { 395 return supplierNumber; 396 } 397 398 public String toString() 399 { 400 return "[ShipmentKey: supplier=" + supplierNumber + 401 " part=" + partNumber + ']'; 402 } 403}</tt></b> </pre> 404 <p> 405 The <tt class="classname">ShipmentData</tt> class contains only the Shipment's 406 Quantity field. Like <tt class="classname">PartKey</tt> and <tt class="classname">SupplierKey</tt>, 407 <tt class="classname">ShipmentData</tt> contains only a single primitive field. 408 Therefore the Integer class could have been used instead of 409 defining a specific value class. 410</p> 411 <a id="cb_shipmentdata"></a> 412 <pre class="programlisting"><b class="userinput"><tt>import java.io.Serializable; 413 414public class ShipmentData implements Serializable 415{ 416 private int quantity; 417 418 public ShipmentData(int quantity) 419 { 420 this.quantity = quantity; 421 } 422 423 public final int getQuantity() 424 { 425 return quantity; 426 } 427 428 public String toString() 429 { 430 return "[ShipmentData: quantity=" + quantity + ']'; 431 } 432}</tt></b> </pre> 433 </div> 434 </div> 435 <div class="navfooter"> 436 <hr /> 437 <table width="100%" summary="Navigation footer"> 438 <tr> 439 <td width="40%" align="left"><a accesskey="p" href="tutorialintroduction.html">Prev</a> </td> 440 <td width="20%" align="center"> 441 <a accesskey="u" href="index.html">Up</a> 442 </td> 443 <td width="40%" align="right"> <a accesskey="n" href="opendbenvironment.html">Next</a></td> 444 </tr> 445 <tr> 446 <td width="40%" align="left" valign="top">Tutorial Introduction </td> 447 <td width="20%" align="center"> 448 <a accesskey="h" href="index.html">Home</a> 449 </td> 450 <td width="40%" align="right" valign="top"> 451 Opening and Closing the Database Environment 452 </td> 453 </tr> 454 </table> 455 </div> 456 </body> 457</html> 458