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