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