PrimaryKey


1   /*-
2    * See the file LICENSE for redistribution information.
3    *
4    * Copyright (c) 2002,2006 Oracle.  All rights reserved.
5    *
6    * $Id: PrimaryKey.java,v 1.8 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  ;
12  import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
13  
14  import java.lang.annotation.Documented  ;
15  import java.lang.annotation.Retention  ;
16  import java.lang.annotation.Target  ;
17  
18  import com.sleepycat.persist.EntityStore;
19  import com.sleepycat.persist.PrimaryIndex;
20  
21  /**
22   * Indicates the primary key field of an entity class.  The value of the
23   * primary key field is the unique identifier for the entity in a {@link
24   * PrimaryIndex}.
25   *
26   * <p>{@link PrimaryKey} may appear on at most one declared field per class.
27   * If it does not appear on a declared field in the entity class, {@code
28   * PrimaryKey} must appear on a field of an entity superclass.  The nearest
29   * superclass declaration is used if more than one superclass with {@code
30   * PrimaryKey} is present.</p>
31   *
32   * <p>Primary key values may be automatically assigned as sequential integers
33   * using a {@link #sequence}.  In this case the type of the key field is
34   * restricted to a simple integer type.</p>
35   *
36   * <p>A primary key field may not be null, unless it is being assigned from a
37   * sequence.</p>
38   *
39   * <p><a name="keyTypes"><strong>Key Field Types</strong></a></p>
40   *
41   * <p>The type of a key field must either be one of the following:</p>
42   * <ul>
43   * <li>Any of the {@link <a HREF="Entity.html#simpleTypes">simple
44   * types</a>}.</li>
45   * <li>A composite key class containing one or more simple type fields.</li>
46   * </ul>
47   * <p>Enum types and array types are not allowed.</p>
48   *
49   * <p>When using a composite key class containing more than one key field, each
50   * field of the composite key class must be annotated with {@link KeyField} to
51   * identify the storage order and default sort order.  See {@link KeyField} for
52   * an example and more information on composite keys.</p>
53   *
54   * <p><a name="sortOrder"><strong>Key Sort Order</strong></a></p>
55   *
56   * <p>Key field types, being simple types, have a well defined and reasonable
57   * default sort order, described below.  This sort order is based on a storage
58   * encoding that allows a fast byte-by-byte comparison.</p>
59   * <ul>
60   * <li>All simple types except for {@code String} are encoded so that they are
61   * sorted as expected, that is, as if the {@link Comparable#compareTo} method
62   * of their class (or, for primitives, their wrapper class) is called.</li>
63   * <br>
64   * <li>Strings are encoded as UTF-8 byte arrays.  Zero (0x0000) character
65   * values are UTF encoded as non-zero values, and therefore embedded zeros in
66   * the string are supported.  The sequence {@literal {0xC0,0x80}} is used to
67   * encode a zero character.  This UTF encoding is the same one used by native
68   * Java UTF libraries.  However, this encoding of zero does impact the
69   * lexicographical ordering, and zeros will not be sorted first (the natural
70   * order) or last.  For all character values other than zero, the default UTF
71   * byte ordering is the same as the Unicode lexicographical character
72   * ordering.</li>
73   * </ul>
74   *
75   * <p>To override the default sort order, you can use a composite key class
76   * that implements {@link Comparable}.  This allows overriding the sort order
77   * and is therefore useful even when there is only one key field in the
78   * composite key class.  See {@link <a HREF="KeyField.html#comparable">Custom
79   * Sort Order</a>} for more information on sorting of composite keys.</p>
80   *
81   * @author Mark Hayes
82   */
83  @Documented   @Retention  (RUNTIME) @Target  (FIELD)
84  public @interface PrimaryKey {
85  
86      /**
87       * The name of a sequence from which to assign primary key values
88       * automatically.  If a non-empty string is specified, sequential integers
89       * will be assigned from the named sequence.
90       *
91       * <p>A single sequence may be used for more than one entity class by
92       * specifying the same sequence name for each {@code PrimaryKey}.  For
93       * each named sequence, a {@link com.sleepycat.je.Sequence} will be used to
94       * assign key values.  For more information on configuring sequences, see
95       * {@link EntityStore#setSequenceConfig EntityStore.setSequenceConfig}.</p>
96       *
97       * <p>To use a sequence, the type of the key field must be a primitive
98       * integer type ({@code byte}, {@code short}, {@code int} or {@code long})
99       * or the primitive wrapper class for one of these types.  A composite key
100      * class may also be used to override sort order, but it may contain only a
101      * single key field that has one of the types previously mentioned.</p>
102      *
103      * <p>When an entity with a primary key sequence is stored using one of the
104      * <code>put</code> methods in the {@link PrimaryIndex}, a new key will be
105      * assigned if the primary key field in the entity instance is null (for a
106      * reference type) or zero (for a primitive integer type).  Specifying zero
107      * for a primitive integer key field is allowed because the initial value
108      * of the sequence is one (not zero) by default.  If the sequence
109      * configuration is changed such that zero is part of the sequence, then
110      * the field type must be a primitive wrapper class and the field value
111      * must be null to cause a new key to be assigned.</p>
112      *
113      * <p>When one of the <code>put</code> methods in the {@link PrimaryIndex}
114      * is called and a new key is assigned, the assigned value is returned to
115      * the caller via the key field of the entity object that is passed as a
116      * parameter.</p>
117      */
118     String   sequence() default "";
119 }
120
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags