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 Indexes</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="persist_index.html" title="Chapter��4.��Working with Indices" /> 11 <link rel="previous" href="persist_index.html" title="Chapter��4.��Working with Indices" /> 12 <link rel="next" href="persist_access.html" title="Chapter��5.��Saving and Retrieving Objects" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Creating Indexes</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="persist_index.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��4.��Working with Indices</th> 23 <td width="20%" align="right">��<a accesskey="n" href="persist_access.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="dplindexcreate"></a>Creating Indexes</h2> 33 </div> 34 </div> 35 <div></div> 36 </div> 37 <p> 38 To create an index using the DPL, you use Java 39 annotations to declare which feature on the class is used 40 for the primary index, and which features (if any) are to 41 be used as secondary indexes. 42 </p> 43 <p> 44 All entity classes stored in the DPL must have a 45 primary index declared for it. 46 </p> 47 <p> 48 Entity classes can have zero or more secondary 49 indexes declared for them. There is no limit on the 50 number of secondary indexes that you can declare. 51 </p> 52 <div class="sect2" lang="en" xml:lang="en"> 53 <div class="titlepage"> 54 <div> 55 <div> 56 <h3 class="title"><a id="dplprimaryidxdecl"></a>Declaring a Primary Indexes</h3> 57 </div> 58 </div> 59 <div></div> 60 </div> 61 <p> 62 You declare a primary key for an entity class by 63 using the <tt class="literal">@PrimaryKey</tt> 64 annotation. This annotation must appear 65 immediately before the data member which 66 represents the class's primary key. For example: 67 </p> 68 <pre class="programlisting">package persist.gettingStarted; 69 70import com.sleepycat.persist.model.Entity; 71import com.sleepycat.persist.model.PrimaryKey; 72 73@Entity 74public class Vendor { 75 76 private String address; 77 private String bizPhoneNumber; 78 private String city; 79 private String repName; 80 private String repPhoneNumber; 81 private String state; 82 83 // Primary key is the vendor's name 84 // This assumes that the vendor's name is 85 // unique in the database. 86 @PrimaryKey 87 private String vendor; 88 89 ... </pre> 90 <p> 91 For this class, the <tt class="literal">vendor</tt> value is set for an individual 92 <tt class="classname">Vendor</tt> class object by 93 the <tt class="methodname">setVendorName()</tt> 94 method. If our example code fails to set this 95 value before storing the object, the data 96 member used to store the primary key is set to a 97 null value. This would result in a runtime 98 error. 99 </p> 100 <p> 101 You can avoid the need to explicitly set a 102 value for a class's primary index by specifying 103 a sequence to be used for the primary key. This 104 results in an unique integer value being used 105 as the primary key for each stored object. 106 </p> 107 <p> 108 You declare a sequence is to be used by specifying 109 the <tt class="literal">sequence</tt> keyword to the 110 <tt class="literal">@PrimaryKey</tt> annotation. 111 For example: 112 </p> 113 <pre class="programlisting">@PrimaryKey(sequence="") 114long myPrimaryKey; </pre> 115 <p> 116 If you provide the <tt class="literal">sequence</tt> keyword with a name, 117 then the sequence is obtained from that named sequence. For example: 118 </p> 119 <pre class="programlisting">@PrimaryKey(sequence="Sequence_Namespace") 120long myPrimaryKey; </pre> 121 </div> 122 <div class="sect2" lang="en" xml:lang="en"> 123 <div class="titlepage"> 124 <div> 125 <div> 126 <h3 class="title"><a id="dplsecondaryidxdecl"></a>Declaring Secondary Indexes</h3> 127 </div> 128 </div> 129 <div></div> 130 </div> 131 <p> 132 To declare a secondary index, we use the 133 <tt class="literal">@SecondaryKey</tt> annotation. Note 134 that when we do this, we must declare what sort of 135 an index it is; that is, what is its relationship to 136 other data in the data store. 137 </p> 138 <p> 139 The <span class="emphasis"><em>kind</em></span> of indices that we 140 can declare are: 141 </p> 142 <div class="itemizedlist"> 143 <ul type="disc"> 144 <li> 145 <p> 146 <tt class="literal">ONE_TO_ONE</tt> 147 </p> 148 <p> 149 This relationship indicates that 150 the secondary key is unique to the 151 object. If an object is stored with a 152 secondary key that already 153 exists in the data store, a run 154 time error is raised. 155 </p> 156 <p> 157 For example, a person object might 158 be stored with a primary key of a 159 social security number (in the US), 160 with a secondary key of the 161 person's employee number. Both 162 values are expected to be unique in 163 the data store. 164 </p> 165 </li> 166 <li> 167 <p> 168 <tt class="literal">MANY_TO_ONE</tt> 169 </p> 170 <p> 171 Indicates that the secondary key 172 may be used for multiple 173 objects in the data store. That is, 174 the key appears more than 175 once, but for each stored object it 176 can be used only once. 177 </p> 178 <p> 179 Consider a data store that relates 180 managers to employees. A given 181 manager will have multiple 182 employees, but each employee is 183 assumed to have just one manager. 184 In this case, the manager's 185 employee number might be a 186 secondary key, so that you can 187 quickly locate all the objects 188 related to that manager's 189 employees. 190 </p> 191 </li> 192 <li> 193 <p> 194 <tt class="literal">ONE_TO_MANY</tt> 195 </p> 196 <p> 197 Indicates that the secondary key 198 might be used more than once for a 199 given object. Index keys 200 themselves are assumed to be 201 unique, but multiple instances of 202 the index can be used per object. 203 </p> 204 <p> 205 For example, employees might have 206 multiple unique email addresses. In 207 this case, any given object can be 208 access by one or more email 209 addresses. Each such address is 210 unique in the data store, but each 211 such address will relate to a 212 single employee object. 213 </p> 214 </li> 215 <li> 216 <p> 217 <tt class="literal">MANY_TO_MANY</tt> 218 </p> 219 <p> 220 There can be multiple keys for 221 any given object, and for any given 222 key there can be many related 223 objects. 224 </p> 225 <p> 226 For example, suppose your 227 organization has a shared 228 resource, such as printers. You 229 might want to track which 230 printers a given employee can 231 use (there might be more than 232 one). You might also want to 233 track which employees can use a 234 specific printer. This 235 represents a many-to-many 236 relationship. 237 </p> 238 </li> 239 </ul> 240 </div> 241 <p> 242 Note that for <tt class="literal">ONE_TO_ONE</tt> and 243 <tt class="literal">MANY_TO_ONE</tt> relationships, you 244 need a simple data member (not an array or 245 collection) to hold the key. For 246 <tt class="literal">ONE_TO_MANY</tt> and 247 <tt class="literal">MANY_TO_MANY</tt> relationships, you 248 need an array or collection to hold the keys: 249 </p> 250 <pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE) 251private String primaryEmailAddress = new String(); 252 253@SecondaryKey(relate=ONE_TO_MANY) 254private Set<String> emailAddresses = new HashSet<String>(); </pre> 255 </div> 256 <div class="sect2" lang="en" xml:lang="en"> 257 <div class="titlepage"> 258 <div> 259 <div> 260 <h3 class="title"><a id="foreignkey"></a>Foreign Key Constraints</h3> 261 </div> 262 </div> 263 <div></div> 264 </div> 265 <p> 266 Sometimes a secondary index is related in some 267 way to another entity class that is also 268 contained in the data store. That is, the 269 secondary key might be the primary key for 270 another entity class. If this is the case, you 271 can declare the foreign key constraint to make 272 data integrity easier to accomplish. 273 </p> 274 <p> 275 For example, you might have one class that is 276 used to represent employees. 277 You might have another that is used to 278 represent corporate divisions. When you add or 279 modify an employee record, you might want to 280 ensure that the division to which the employee 281 belongs is known to the data store. You do this 282 by specifying a foreign key constraint. 283 </p> 284 <p> 285 When a foreign key constraint is declared: 286 </p> 287 <div class="itemizedlist"> 288 <ul type="disc"> 289 <li> 290 <p> 291 When a new secondary key 292 for the object is stored, 293 it is checked to make sure 294 it exists as a primary 295 key for the related 296 entity object. If it does 297 not, a runtime error 298 occurs. 299 </p> 300 </li> 301 <li> 302 <p> 303 When a related entity is 304 deleted (that is, a 305 corporate division is 306 removed from the data 307 store), some action is 308 automatically taken for 309 the entities that refer to 310 this object (that is, the 311 employee objects). Exactly 312 what that action is, is 313 definable by you. See 314 below. 315 </p> 316 </li> 317 </ul> 318 </div> 319 <p> 320 When a related entity is deleted from the data 321 store, one of the following actions are taken: 322 </p> 323 <div class="itemizedlist"> 324 <ul type="disc"> 325 <li> 326 <p> 327 <tt class="literal">ABORT</tt> 328 </p> 329 <p> 330 The delete operation is not 331 allowed. A runtime error is 332 raised as a result of the 333 operation. This is the 334 default behavior. 335 </p> 336 </li> 337 <li> 338 <p> 339 <tt class="literal">CASCADE</tt> 340 </p> 341 <p> 342 All entities related to this 343 one are deleted as well. For 344 example, if you deleted a 345 <tt class="classname">Division</tt> 346 object, then all 347 <tt class="classname">Employee</tt> 348 objects that belonged to the 349 division are also deleted. 350 </p> 351 </li> 352 <li> 353 <p> 354 <tt class="literal">NULLIFY</tt> 355 </p> 356 <p> 357 All entities related to the 358 deleted entity are updated so 359 that the pertinent data member 360 is nullified. That is, if you 361 deleted a division, then all 362 employee objects related to 363 that division would have their 364 division key 365 automatically set to null. 366 </p> 367 </li> 368 </ul> 369 </div> 370 <p> 371 You declare a foreign key constraint by using 372 the <tt class="literal">relatedEntity</tt> keyword. You 373 declare the foreign key constraint deletion policy using the 374 <tt class="literal">onRelatedEntityDelete</tt> keyword. For 375 example, the following declares a foreign key 376 constraint to <tt class="classname">Division</tt> 377 class objects, and it causes related objects to 378 be deleted if the <tt class="classname">Division</tt> 379 class is deleted: 380 </p> 381 <pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE, relatedEntity=Division.class, 382 onRelatedEntityDelete=CASCADE) 383private String division = new String(); </pre> 384 </div> 385 </div> 386 <div class="navfooter"> 387 <hr /> 388 <table width="100%" summary="Navigation footer"> 389 <tr> 390 <td width="40%" align="left"><a accesskey="p" href="persist_index.html">Prev</a>��</td> 391 <td width="20%" align="center"> 392 <a accesskey="u" href="persist_index.html">Up</a> 393 </td> 394 <td width="40%" align="right">��<a accesskey="n" href="persist_access.html">Next</a></td> 395 </tr> 396 <tr> 397 <td width="40%" align="left" valign="top">Chapter��4.��Working with Indices��</td> 398 <td width="20%" align="center"> 399 <a accesskey="h" href="index.html">Home</a> 400 </td> 401 <td width="40%" align="right" valign="top">��Chapter��5.��Saving and Retrieving Objects</td> 402 </tr> 403 </table> 404 </div> 405 </body> 406</html> 407