KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sleepycat > persist > model > SecondaryKey


1 /*-
2  * See the file LICENSE for redistribution information.
3  *
4  * Copyright (c) 2002,2006 Oracle. All rights reserved.
5  *
6  * $Id: SecondaryKey.java,v 1.9 2006/10/30 21:14:33 bostic Exp $
7  */

8
9 package com.sleepycat.persist.model;
10
11 import static java.lang.annotation.ElementType.FIELD JavaDoc;
12 import static java.lang.annotation.RetentionPolicy.RUNTIME JavaDoc;
13
14 import java.lang.annotation.Documented JavaDoc;
15 import java.lang.annotation.Retention JavaDoc;
16 import java.lang.annotation.Target JavaDoc;
17
18 import com.sleepycat.je.DatabaseException;
19 import com.sleepycat.persist.PrimaryIndex;
20 import com.sleepycat.persist.SecondaryIndex; // for javadoc
21
import com.sleepycat.persist.StoreConfig;
22
23 /**
24  * Indicates a secondary key field of an entity class. The value of the
25  * secondary key field is a unique or non-unique identifier for the entity and
26  * is accessed via a {@link SecondaryIndex}.
27  *
28  * <p>{@code SecondaryKey} may appear on any number of fields in an entity
29  * class, subclasses and superclasses. For a secondary key field in the entity
30  * class or one of its superclasses, all entity instances will be indexed by
31  * that field (if it is non-null). For a secondary key field in an entity
32  * subclass, only instances of that subclass will be indexed by that field (if
33  * it is non-null).</p>
34  *
35  * <p>If a secondary key field is null, the entity will not be indexed by that
36  * key. In other words, the entity cannot be queried by that secondary key nor
37  * can the entity be found by iterating through the secondary index.</p>
38  *
39  * <p>For a given entity class and its superclasses and subclasses, no two
40  * secondary keys may have the same name. By default, the field name
41  * identifies the secondary key and the secondary index for a given entity
42  * class. {@link #name} may be specified to override this default.</p>
43  *
44  * <p>Using {@link #relate}, instances of the entity class are related to
45  * secondary keys in a many-to-one, one-to-many, many-to-many, or one-to-one
46  * relationship. This required property specifies the <em>cardinality</em> of
47  * each side of the relationship.</p>
48  *
49  * <p>A secondary key may optionally be used to form a relationship with
50  * instances of another entity class using {@link #relatedEntity} and {@link
51  * #onRelatedEntityDelete}. This establishes <em>foreign key constraints</em>
52  * for the secondary key.</p>
53  *
54  * <p>The secondary key field type must be an array or collection type when a
55  * <em>x-to-many</em> relationship is used or a singular type when an
56  * <em>x-to-one</em> relationship is used; see {@link #relate}.</p>
57  *
58  * <p>The field type (or element type, when an array or collection type is
59  * used) of a secondary key field must follow the same rules as for a {@link
60  * <a HREF="PrimaryKey.html#keyTypes">primary key type</a>}. The {@link <a
61  * HREF="PrimaryKey.html#sortOrder">key sort order</a>} is also the same.</p>
62  *
63  * @author Mark Hayes
64  */

65 @Documented JavaDoc @Retention JavaDoc(RUNTIME) @Target JavaDoc(FIELD)
66 public @interface SecondaryKey {
67
68     /**
69      * Defines the relationship between instances of the entity class and the
70      * secondary keys.
71      *
72      * <p>The table below summarizes how to create all four variations of
73      * relationships.</p>
74      * <div>
75      * <table border="yes">
76      * <tr><th>Relationship</th>
77      * <th>Field type</th>
78      * <th>Key type</th>
79      * <th>Example</th>
80      * </tr>
81      * <tr><td>{@link Relationship#ONE_TO_ONE}</td>
82      * <td>Singular</td>
83      * <td>Unique</td>
84      * <td>A person record with a unique social security number
85      * key.</td>
86      * </tr>
87      * <tr><td>{@link Relationship#MANY_TO_ONE}</td>
88      * <td>Singular</td>
89      * <td>Duplicates</td>
90      * <td>A person record with a non-unique employer key.</td>
91      * </tr>
92      * <tr><td>{@link Relationship#ONE_TO_MANY}</td>
93      * <td>Array/Collection</td>
94      * <td>Unique</td>
95      * <td>A person record with multiple unique email address keys.</td>
96      * </tr>
97      * <tr><td>{@link Relationship#MANY_TO_MANY}</td>
98      * <td>Array/Collection</td>
99      * <td>Duplicates</td>
100      * <td>A person record with multiple non-unique organization
101      * keys.</td>
102      * </tr>
103      * </table>
104      * </div>
105      *
106      * <p>For a <em>many-to-x</em> relationship, the secondary index will
107      * have non-unique keys; in other words, duplicates will be allowed.
108      * Conversely, for <em>one-to-x</em> relationship, the secondary index
109      * will have unique keys.</p>
110      *
111      * <p>For a <em>x-to-one</em> relationship, the secondary key field is
112      * singular; in other words, it may not be an array or collection type.
113      * Conversely, for a <em>x-to-many</em> relationship, the secondary key
114      * field must be an array or collection type. A collection type is any
115      * implementation of {@link java.util.Collection}.</p>
116      */

117     Relationship relate();
118
119     /**
120      * Specifies the entity to which this entity is related, for establishing
121      * foreign key constraints. Values of this secondary key will be
122      * constrained to the set of primary key values for the given entity class.
123      *
124      * <p>The given class must be an entity class. This class is called the
125      * <em>related entity</em> or <em>foreign entity</em>.</p>
126      *
127      * <p>When a related entity class is specified, a check (foreign key
128      * constraint) is made every time a new secondary key value is stored for
129      * this entity, and every time a related entity is deleted.</p>
130      *
131      * <p>Whenever a new secondary key value is stored for this entity, it is
132      * checked to ensure it exists as a primary key value of the related
133      * entity. If it does not, a {@link DatabaseException} will be thrown
134      * by the {@link PrimaryIndex} {@code put} method.</p>
135      *
136      * <p>Whenever a related entity is deleted and its primary key value exists
137      * as a secondary key value for this entity, the action is taken that is
138      * specified using the {@link #onRelatedEntityDelete} property.</p>
139      *
140      * <p>Together, these two checks guarantee that a secondary key value for
141      * this entity will always exist as a primary key value for the related
142      * entity. Note, however, that a transactional store must be configured
143      * to guarantee this to be true in the face of a crash; see {@link
144      * StoreConfig#setTransactional}.</p>
145      */

146     Class JavaDoc relatedEntity() default void.class;
147
148     /**
149      * Specifies the action to take when a related entity is deleted having a
150      * primary key value that exists as a secondary key value for this entity.
151      *
152      * <p><em>Note:</em> This property only applies when {@link #relatedEntity}
153      * is specified to define the related entity.</p>
154      *
155      * <p>The default action, {@link DeleteAction#ABORT ABORT}, means that a
156      * {@link DatabaseException} is thrown in order to abort the current
157      * transaction.</p>
158      *
159      * <p>If {@link DeleteAction#CASCADE CASCADE} is specified, then this
160      * entity will be deleted also. This in turn could trigger further
161      * deletions, causing a cascading effect.</p>
162      *
163      * <p>If {@link DeleteAction#NULLIFY NULLIFY} is specified, then the
164      * secondary key in this entity is set to null and this entity is updated.
165      * If the key field type is singular, the field value is set to null;
166      * therefore, to specify {@code NULLIFY} for a singular key field type, a
167      * primitive wrapper type must be used instead of a primitive type. If the
168      * key field type is an array or collection type, the key is deleted from
169      * the array (the array is resized) or from the collection (using {@link
170      * java.util.Collection#remove Collection.remove}).</p>
171      */

172     DeleteAction onRelatedEntityDelete() default DeleteAction.ABORT;
173
174     /**
175      * Specifies the name of the key in order to use a name that is different
176      * than the field name.
177      *
178      * <p>This is convenient when prefixes or suffices are used on field names.
179      * For example:</p>
180      * <pre class="code">
181      * class Person {
182      * {@literal @SecondaryKey(relate=MANY_TO_ONE, relatedEntity=Person.class, name="parentSsn")}
183      * String m_parentSsn;
184      * }</pre>
185      *
186      * <p>It can also be used to uniquely name a key when multiple secondary
187      * keys for a single entity class have the same field name. For example,
188      * an entity class and its subclass may both have a field named 'date',
189      * and both fields are used as secondary keys. The {@code name} property
190      * can be specified for one or both fields to give each key a unique
191      * name.</p>
192      */

193     String JavaDoc name() default "";
194 }
195
Popular Tags