docs/collections/tutorial/creatingentitybindings.html

   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>Creating Entity Bindings</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="Entity.html" title="Chapter 4.  Using Entity Classes" />
  11     <link rel="prev" href="Entity.html" title="Chapter 4.  Using Entity Classes" />
  12     <link rel="next" href="collectionswithentities.html" title="Creating Collections with 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">
  22                 Creating Entity Bindings
  23         </th>
  24         </tr>
  25         <tr>
  26           <td width="20%" align="left"><a accesskey="p" href="Entity.html">Prev</a> </td>
  27           <th width="60%" align="center">Chapter 4.
  28         Using Entity Classes
  29         </th>
  30           <td width="20%" align="right"> <a accesskey="n" href="collectionswithentities.html">Next</a></td>
  31         </tr>
  32       </table>
  33       <hr />
  34     </div>
  35     <div class="sect1" lang="en" xml:lang="en">
  36       <div class="titlepage">
  37         <div>
  38           <div>
  39             <h2 class="title" style="clear: both"><a id="creatingentitybindings"></a>
  40                 Creating Entity Bindings
  41         </h2>
  42           </div>
  43         </div>
  44       </div>
  45       <p>
  46     <span class="emphasis"><em>Entity bindings</em></span> are similar to ordinary bindings in that
  47         they convert between Java objects and the stored data format of
  48         keys and values. In addition, entity bindings map between key/value
  49         pairs and entity objects. An ordinary binding is a one-to-one
  50         mapping, while an entity binding is a two-to-one mapping.
  51 </p>
  52       <p>
  53     The <code class="literal">partValueBinding</code>, <code class="literal">supplierValueBinding</code> and
  54         <code class="literal">shipmentValueBinding</code> bindings are created below as entity
  55         bindings rather than (in the prior examples) serial bindings.
  56 </p>
  57       <a id="entity_sampleviews"></a>
  58       <pre class="programlisting">import com.sleepycat.bind.EntryBinding;
  59 <strong class="userinput"><code>import com.sleepycat.bind.EntityBinding;</code></strong>
  60 import com.sleepycat.bind.serial.SerialBinding;
  61 <strong class="userinput"><code>import com.sleepycat.bind.serial.SerialSerialBinding;</code></strong>
  62 ...
  63
  64 public class SampleViews
  65 {
  66     ...
  67     public SampleViews(SampleDatabase db)
  68     {
  69         ClassCatalog catalog = db.getClassCatalog();
  70         SerialBinding partKeyBinding =
  71             new SerialBinding(catalog, PartKey.class);
  72 <strong class="userinput"><code>        EntityBinding partValueBinding =
  73             new PartBinding(catalog, PartKey.class, PartData.class);</code></strong>
  74         SerialBinding supplierKeyBinding =
  75             new SerialBinding(catalog, SupplierKey.class);
  76 <strong class="userinput"><code>        EntityBinding supplierValueBinding =
  77             new SupplierBinding(catalog, SupplierKey.class,
  78                                 SupplierData.class);</code></strong>
  79         SerialBinding shipmentKeyBinding =
  80             new SerialBinding(catalog, ShipmentKey.class);
  81 <strong class="userinput"><code>        EntityBinding shipmentValueBinding =
  82             new ShipmentBinding(catalog, ShipmentKey.class,
  83                                 ShipmentData.class);</code></strong>
  84         SerialBinding cityKeyBinding =
  85             new SerialBinding(catalog, String.class);
  86         ...
  87     }
  88 } </pre>
  89       <p>
  90     The entity bindings will be used in the next section to
  91         construct stored map objects.
  92 </p>
  93       <p>
  94     The <code class="classname">PartBinding</code> class is defined below.
  95 </p>
  96       <a id="entity_partbinding"></a>
  97       <pre class="programlisting">public class SampleViews
  98 {
  99     ...
 100 <strong class="userinput"><code>    private static class PartBinding extends SerialSerialBinding {
 101         private PartBinding(ClassCatalog classCatalog,
 102                             Class keyClass,
 103                             Class dataClass)
 104         {
 105             super(classCatalog, keyClass, dataClass);
 106         }
 107
 108         public Object entryToObject(Object keyInput, Object dataInput)
 109         {
 110             PartKey key = (PartKey) keyInput;
 111             PartData data = (PartData) dataInput;
 112             return new Part(key.getNumber(), data.getName(),
 113                             data.getColor(), data.getWeight(),
 114                             data.getCity());
 115         }
 116
 117         public Object objectToKey(Object object)
 118         {
 119             Part part = (Part) object;
 120             return new PartKey(part.getNumber());
 121         }
 122
 123         public Object objectToData(Object object)
 124         {
 125             Part part = (Part) object;
 126             return new PartData(part.getName(), part.getColor(),
 127                                 part.getWeight(), part.getCity());
 128         }
 129     }</code></strong>
 130     ...
 131 } </pre>
 132       <p>
 133     In general, an entity binding is any class that implements the
 134         <a class="ulink" href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
 135
 136         interface, just as an ordinary binding is any class that implements
 137         the
 138     <a class="ulink" href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>
 139
 140         interface. In the prior examples the built-in
 141     <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
 142
 143         class (which implements
 144     <a class="ulink" href="../../java/com/sleepycat/bind/EntryBinding.html" target="_top">EntryBinding</a>)
 145         was used and no application-defined binding classes were needed.
 146 </p>
 147       <p>
 148     In this example, application-defined binding classes are used
 149         that extend the
 150     <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialSerialBinding.html" target="_top">SerialSerialBinding</a>
 151
 152         abstract base class. This base class implements
 153     <a class="ulink" href="../../java/com/sleepycat/bind/EntityBinding.html" target="_top">EntityBinding</a>
 154
 155         and provides the conversions between key/value bytes and key/value
 156         objects, just as the
 157     <a class="ulink" href="../../java/com/sleepycat/bind/serial/SerialBinding.html" target="_top">SerialBinding</a>
 158
 159         class does. The application-defined entity class implements the
 160         abstract methods defined in the base class that map between
 161         key/value objects and entity objects.
 162 </p>
 163       <p>
 164     Three abstract methods are implemented for each entity binding.
 165         The <code class="methodname">entryToObject()</code> method takes as input the key and data
 166         objects, which have been deserialized automatically by the base
 167         class. As output, it returns the combined <code class="classname">Part</code> entity.
 168 </p>
 169       <p>
 170     The <code class="methodname">objectToKey()</code> and <code class="methodname">objectToData()</code> methods take an
 171         entity object as input. As output they return the part key or data
 172         object that is extracted from the entity object. The key or data
 173         will then be serialized automatically by the base class.
 174 </p>
 175       <p>
 176     The <code class="classname">SupplierBinding</code> and <code class="classname">ShipmentBinding</code> classes
 177         are very similar to the <code class="classname">PartBinding</code> class.
 178 </p>
 179       <a id="entity_supplierbinding"></a>
 180       <pre class="programlisting">public class SampleViews
 181 {
 182     ...
 183 <strong class="userinput"><code>    private static class SupplierBinding extends SerialSerialBinding {
 184         private SupplierBinding(ClassCatalog classCatalog,
 185                                 Class keyClass,
 186                                 Class dataClass)
 187         {
 188             super(classCatalog, keyClass, dataClass);
 189         }
 190
 191         public Object entryToObject(Object keyInput, Object dataInput)
 192         {
 193             SupplierKey key = (SupplierKey) keyInput;
 194             SupplierData data = (SupplierData) dataInput;
 195             return new Supplier(key.getNumber(), data.getName(),
 196                                 data.getStatus(), data.getCity());
 197         }
 198
 199         public Object objectToKey(Object object)
 200         {
 201             Supplier supplier = (Supplier) object;
 202             return new SupplierKey(supplier.getNumber());
 203         }
 204
 205         public Object objectToData(Object object)
 206         {
 207             Supplier supplier = (Supplier) object;
 208             return new SupplierData(supplier.getName(),
 209                                     supplier.getStatus(),
 210                                     supplier.getCity());
 211         }
 212     }
 213
 214     private static class ShipmentBinding extends SerialSerialBinding {
 215         private ShipmentBinding(ClassCatalog classCatalog,
 216                                 Class keyClass,
 217                                 Class dataClass)
 218         {
 219             super(classCatalog, keyClass, dataClass);
 220         }
 221
 222         public Object entryToObject(Object keyInput, Object dataInput)
 223         {
 224             ShipmentKey key = (ShipmentKey) keyInput;
 225             ShipmentData data = (ShipmentData) dataInput;
 226             return new Shipment(key.getPartNumber(),
 227                                 key.getSupplierNumber(),
 228                                 data.getQuantity());
 229         }
 230
 231         public Object objectToKey(Object object)
 232         {
 233             Shipment shipment = (Shipment) object;
 234             return new ShipmentKey(shipment.getPartNumber(),
 235                                    shipment.getSupplierNumber());
 236         }
 237
 238         public Object objectToData(Object object)
 239         {
 240             Shipment shipment = (Shipment) object;
 241             return new ShipmentData(shipment.getQuantity());
 242         }
 243     }</code></strong>
 244     ...
 245 } </pre>
 246     </div>
 247     <div class="navfooter">
 248       <hr />
 249       <table width="100%" summary="Navigation footer">
 250         <tr>
 251           <td width="40%" align="left"><a accesskey="p" href="Entity.html">Prev</a> </td>
 252           <td width="20%" align="center">
 253             <a accesskey="u" href="Entity.html">Up</a>
 254           </td>
 255           <td width="40%" align="right"> <a accesskey="n" href="collectionswithentities.html">Next</a></td>
 256         </tr>
 257         <tr>
 258           <td width="40%" align="left" valign="top">Chapter 4.
 259         Using Entity Classes
 260          </td>
 261           <td width="20%" align="center">
 262             <a accesskey="h" href="index.html">Home</a>
 263           </td>
 264           <td width="40%" align="right" valign="top">
 265                 Creating Collections with Entity Bindings
 266         </td>
 267         </tr>
 268       </table>
 269     </div>
 270   </body>
 271 </html>