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