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.��Working with Indices</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 9 <link rel="home" href="index.html" title="Getting Started with Berkeley DB" /> 10 <link rel="up" href="dpl.html" title="Part��I.��Programming with the Direct Persistence Layer" /> 11 <link rel="previous" href="saveret.html" title="Saving a Retrieving Data" /> 12 <link rel="next" href="dplindexcreate.html" title="Creating Indexes" /> 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.��Working with Indices</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="saveret.html">Prev</a>��</td> 22 <th width="60%" align="center">Part��I.��Programming with the Direct Persistence Layer</th> 23 <td width="20%" align="right">��<a accesskey="n" href="dplindexcreate.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="chapter" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title"><a id="persist_index"></a>Chapter��4.��Working with Indices</h2> 33 </div> 34 </div> 35 <div></div> 36 </div> 37 <div class="toc"> 38 <p> 39 <b>Table of Contents</b> 40 </p> 41 <dl> 42 <dt> 43 <span class="sect1"> 44 <a href="persist_index.html#dplindexaccess">Accessing Indexes</a> 45 </span> 46 </dt> 47 <dd> 48 <dl> 49 <dt> 50 <span class="sect2"> 51 <a href="persist_index.html#primaryindexaccess">Accessing Primary Indices</a> 52 </span> 53 </dt> 54 <dt> 55 <span class="sect2"> 56 <a href="persist_index.html#secondaryindexaccess">Accessing Secondary Indices</a> 57 </span> 58 </dt> 59 </dl> 60 </dd> 61 <dt> 62 <span class="sect1"> 63 <a href="dplindexcreate.html">Creating Indexes</a> 64 </span> 65 </dt> 66 <dd> 67 <dl> 68 <dt> 69 <span class="sect2"> 70 <a href="dplindexcreate.html#dplprimaryidxdecl">Declaring a Primary Indexes</a> 71 </span> 72 </dt> 73 <dt> 74 <span class="sect2"> 75 <a href="dplindexcreate.html#dplsecondaryidxdecl">Declaring Secondary Indexes</a> 76 </span> 77 </dt> 78 <dt> 79 <span class="sect2"> 80 <a href="dplindexcreate.html#foreignkey">Foreign Key Constraints</a> 81 </span> 82 </dt> 83 </dl> 84 </dd> 85 </dl> 86 </div> 87 <p> 88 All entity classes stored in DB using the DPL must have a 89 primary index, or key, identified for them. All such classes may 90 also have one or more secondary keys declared for them. This 91 chapter describes primary and secondary indexes in detail, and 92 shows how to access the indexes created for a given entity class. 93 </p> 94 <p> 95 One way to organize access to your primary and secondary 96 indexes is to create a <span class="emphasis"><em>data accessor</em></span> 97 class. We show an implementation of a data accessor class in 98 <a href="simpleda.html">SimpleDA.class</a>. 99 </p> 100 <div class="sect1" lang="en" xml:lang="en"> 101 <div class="titlepage"> 102 <div> 103 <div> 104 <h2 class="title" style="clear: both"><a id="dplindexaccess"></a>Accessing Indexes</h2> 105 </div> 106 </div> 107 <div></div> 108 </div> 109 <p> 110 In order to retrieve any object from an entity store, you 111 must access at least the primary index for that object. 112 Different entity classes stored in an entity store can have 113 different primary indexes, but all entity classes must have a 114 primary index declared for it. The primary index is just 115 the default index used for the class. (That is, it is the 116 data's <span class="emphasis"><em>key</em></span> for the underlying database.) 117 </p> 118 <p> 119 Entity classes can optionally have secondary indexes 120 declared for them. In order to access these secondary 121 indexes, you must first access the primary index. 122 </p> 123 <div class="sect2" lang="en" xml:lang="en"> 124 <div class="titlepage"> 125 <div> 126 <div> 127 <h3 class="title"><a id="primaryindexaccess"></a>Accessing Primary Indices</h3> 128 </div> 129 </div> 130 <div></div> 131 </div> 132 <p> 133 You retrieve a primary index using the 134 <tt class="methodname">EntityStore.getPrimaryIndex()</tt> 135 method. To do this, you indicate the index key type 136 (that is, whether it is a String, Integer, and 137 so forth) and the class of the entities stored 138 in the index. 139 </p> 140 <p> 141 For example, the following retrieves the 142 primary index for an <tt class="classname">Inventory</tt> 143 class (we provide an implementation of this class in 144 <a href="inventoryclass.html">Inventory.class</a>). 145 These index keys are of type <tt class="classname">String</tt>. 146 </p> 147 <pre class="programlisting">PrimaryIndex<String,Inventory> inventoryBySku = 148 store.getPrimaryIndex(String.class, Inventory.class); </pre> 149 </div> 150 <div class="sect2" lang="en" xml:lang="en"> 151 <div class="titlepage"> 152 <div> 153 <div> 154 <h3 class="title"><a id="secondaryindexaccess"></a>Accessing Secondary Indices</h3> 155 </div> 156 </div> 157 <div></div> 158 </div> 159 <p> 160 You retrieve a secondary index using the 161 <tt class="methodname">EntityStore.getSecondaryIndex()</tt> 162 method. Because secondary indices actually 163 refer to a primary index somewhere in your data 164 store, to access a secondary index you: 165 </p> 166 <div class="orderedlist"> 167 <ol type="1"> 168 <li> 169 <p> 170 Provide the primary index as 171 returned by 172 <tt class="methodname">EntityStore.getPrimaryIndex()</tt>. 173 </p> 174 </li> 175 <li> 176 <p> 177 Identify the key data type used by 178 the secondary index 179 (<tt class="classname">String</tt>, 180 <tt class="classname">Long</tt>, 181 and so forth). 182 </p> 183 </li> 184 <li> 185 <p> 186 Identify the name of the 187 secondary key field. 188 When you declare the 189 <tt class="classname">SecondaryIndex</tt> 190 object, you identify the entity class 191 to which the secondary index 192 must refer. 193 </p> 194 </li> 195 </ol> 196 </div> 197 <p> 198 For example, the following first retrieves the 199 primary index, and then uses that to retrieve a secondary 200 index. The secondary key is held by the 201 <tt class="literal">itemName</tt> field of the 202 <tt class="classname">Inventory</tt> class. 203 </p> 204 <pre class="programlisting">PrimaryIndex<String,Inventory> inventoryBySku = 205store.getPrimaryIndex(String.class, Inventory.class); 206 207SecondaryIndex<String,String,Inventory> inventoryByName = 208 store.getSecondaryIndex(inventoryBySku, String.class, "itemName"); </pre> 209 </div> 210 </div> 211 </div> 212 <div class="navfooter"> 213 <hr /> 214 <table width="100%" summary="Navigation footer"> 215 <tr> 216 <td width="40%" align="left"><a accesskey="p" href="saveret.html">Prev</a>��</td> 217 <td width="20%" align="center"> 218 <a accesskey="u" href="dpl.html">Up</a> 219 </td> 220 <td width="40%" align="right">��<a accesskey="n" href="dplindexcreate.html">Next</a></td> 221 </tr> 222 <tr> 223 <td width="40%" align="left" valign="top">Saving a Retrieving Data��</td> 224 <td width="20%" align="center"> 225 <a accesskey="h" href="index.html">Home</a> 226 </td> 227 <td width="40%" align="right" valign="top">��Creating Indexes</td> 228 </tr> 229 </table> 230 </div> 231 </body> 232</html> 233