Edit File: dplindexcreate.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>Creating Indexes</title> <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> <link rel="home" href="index.html" title="Getting Started with Berkeley DB" /> <link rel="up" href="persist_index.html" title="Chapter 4. Working with Indices" /> <link rel="previous" href="persist_index.html" title="Chapter 4. Working with Indices" /> <link rel="next" href="persist_access.html" title="Chapter 5. Saving and Retrieving Objects" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">Creating Indexes</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="persist_index.html">Prev</a> </td> <th width="60%" align="center">Chapter 4. Working with Indices</th> <td width="20%" align="right"> <a accesskey="n" href="persist_access.html">Next</a></td> </tr> </table> <hr /> </div> <div class="sect1" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"><a id="dplindexcreate"></a>Creating Indexes</h2> </div> </div> <div></div> </div> <p> To create an index using the DPL, you use Java annotations to declare which feature on the class is used for the primary index, and which features (if any) are to be used as secondary indexes. </p> <p> All entity classes stored in the DPL must have a primary index declared for it. </p> <p> Entity classes can have zero or more secondary indexes declared for them. There is no limit on the number of secondary indexes that you can declare. </p> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="dplprimaryidxdecl"></a>Declaring a Primary Indexes</h3> </div> </div> <div></div> </div> <p> You declare a primary key for an entity class by using the <tt class="literal">@PrimaryKey</tt> annotation. This annotation must appear immediately before the data member which represents the class's primary key. For example: </p> <pre class="programlisting">package persist.gettingStarted; import com.sleepycat.persist.model.Entity; import com.sleepycat.persist.model.PrimaryKey; @Entity public class Vendor { private String address; private String bizPhoneNumber; private String city; private String repName; private String repPhoneNumber; private String state; // Primary key is the vendor's name // This assumes that the vendor's name is // unique in the database. @PrimaryKey private String vendor; ... </pre> <p> For this class, the <tt class="literal">vendor</tt> value is set for an individual <tt class="classname">Vendor</tt> class object by the <tt class="methodname">setVendorName()</tt> method. If our example code fails to set this value before storing the object, the data member used to store the primary key is set to a null value. This would result in a runtime error. </p> <p> You can avoid the need to explicitly set a value for a class's primary index by specifying a sequence to be used for the primary key. This results in an unique integer value being used as the primary key for each stored object. </p> <p> You declare a sequence is to be used by specifying the <tt class="literal">sequence</tt> keyword to the <tt class="literal">@PrimaryKey</tt> annotation. For example: </p> <pre class="programlisting">@PrimaryKey(sequence="") long myPrimaryKey; </pre> <p> If you provide the <tt class="literal">sequence</tt> keyword with a name, then the sequence is obtained from that named sequence. For example: </p> <pre class="programlisting">@PrimaryKey(sequence="Sequence_Namespace") long myPrimaryKey; </pre> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="dplsecondaryidxdecl"></a>Declaring Secondary Indexes</h3> </div> </div> <div></div> </div> <p> To declare a secondary index, we use the <tt class="literal">@SecondaryKey</tt> annotation. Note that when we do this, we must declare what sort of an index it is; that is, what is its relationship to other data in the data store. </p> <p> The <span class="emphasis"><em>kind</em></span> of indices that we can declare are: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> <tt class="literal">ONE_TO_ONE</tt> </p> <p> This relationship indicates that the secondary key is unique to the object. If an object is stored with a secondary key that already exists in the data store, a run time error is raised. </p> <p> For example, a person object might be stored with a primary key of a social security number (in the US), with a secondary key of the person's employee number. Both values are expected to be unique in the data store. </p> </li> <li> <p> <tt class="literal">MANY_TO_ONE</tt> </p> <p> Indicates that the secondary key may be used for multiple objects in the data store. That is, the key appears more than once, but for each stored object it can be used only once. </p> <p> Consider a data store that relates managers to employees. A given manager will have multiple employees, but each employee is assumed to have just one manager. In this case, the manager's employee number might be a secondary key, so that you can quickly locate all the objects related to that manager's employees. </p> </li> <li> <p> <tt class="literal">ONE_TO_MANY</tt> </p> <p> Indicates that the secondary key might be used more than once for a given object. Index keys themselves are assumed to be unique, but multiple instances of the index can be used per object. </p> <p> For example, employees might have multiple unique email addresses. In this case, any given object can be access by one or more email addresses. Each such address is unique in the data store, but each such address will relate to a single employee object. </p> </li> <li> <p> <tt class="literal">MANY_TO_MANY</tt> </p> <p> There can be multiple keys for any given object, and for any given key there can be many related objects. </p> <p> For example, suppose your organization has a shared resource, such as printers. You might want to track which printers a given employee can use (there might be more than one). You might also want to track which employees can use a specific printer. This represents a many-to-many relationship. </p> </li> </ul> </div> <p> Note that for <tt class="literal">ONE_TO_ONE</tt> and <tt class="literal">MANY_TO_ONE</tt> relationships, you need a simple data member (not an array or collection) to hold the key. For <tt class="literal">ONE_TO_MANY</tt> and <tt class="literal">MANY_TO_MANY</tt> relationships, you need an array or collection to hold the keys: </p> <pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE) private String primaryEmailAddress = new String(); @SecondaryKey(relate=ONE_TO_MANY) private Set<String> emailAddresses = new HashSet<String>(); </pre> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="foreignkey"></a>Foreign Key Constraints</h3> </div> </div> <div></div> </div> <p> Sometimes a secondary index is related in some way to another entity class that is also contained in the data store. That is, the secondary key might be the primary key for another entity class. If this is the case, you can declare the foreign key constraint to make data integrity easier to accomplish. </p> <p> For example, you might have one class that is used to represent employees. You might have another that is used to represent corporate divisions. When you add or modify an employee record, you might want to ensure that the division to which the employee belongs is known to the data store. You do this by specifying a foreign key constraint. </p> <p> When a foreign key constraint is declared: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> When a new secondary key for the object is stored, it is checked to make sure it exists as a primary key for the related entity object. If it does not, a runtime error occurs. </p> </li> <li> <p> When a related entity is deleted (that is, a corporate division is removed from the data store), some action is automatically taken for the entities that refer to this object (that is, the employee objects). Exactly what that action is, is definable by you. See below. </p> </li> </ul> </div> <p> When a related entity is deleted from the data store, one of the following actions are taken: </p> <div class="itemizedlist"> <ul type="disc"> <li> <p> <tt class="literal">ABORT</tt> </p> <p> The delete operation is not allowed. A runtime error is raised as a result of the operation. This is the default behavior. </p> </li> <li> <p> <tt class="literal">CASCADE</tt> </p> <p> All entities related to this one are deleted as well. For example, if you deleted a <tt class="classname">Division</tt> object, then all <tt class="classname">Employee</tt> objects that belonged to the division are also deleted. </p> </li> <li> <p> <tt class="literal">NULLIFY</tt> </p> <p> All entities related to the deleted entity are updated so that the pertinent data member is nullified. That is, if you deleted a division, then all employee objects related to that division would have their division key automatically set to null. </p> </li> </ul> </div> <p> You declare a foreign key constraint by using the <tt class="literal">relatedEntity</tt> keyword. You declare the foreign key constraint deletion policy using the <tt class="literal">onRelatedEntityDelete</tt> keyword. For example, the following declares a foreign key constraint to <tt class="classname">Division</tt> class objects, and it causes related objects to be deleted if the <tt class="classname">Division</tt> class is deleted: </p> <pre class="programlisting">@SecondaryKey(relate=ONE_TO_ONE, relatedEntity=Division.class, onRelatedEntityDelete=CASCADE) private String division = new String(); </pre> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="persist_index.html">Prev</a> </td> <td width="20%" align="center"> <a accesskey="u" href="persist_index.html">Up</a> </td> <td width="40%" align="right"> <a accesskey="n" href="persist_access.html">Next</a></td> </tr> <tr> <td width="40%" align="left" valign="top">Chapter 4. Working with Indices </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> <td width="40%" align="right" valign="top"> Chapter 5. Saving and Retrieving Objects</td> </tr> </table> </div> </body> </html>
Back to File Manager