001: /*-
002: * See the file LICENSE for redistribution information.
003: *
004: * Copyright (c) 2002,2008 Oracle. All rights reserved.
005: *
006: * $Id: PrimaryKey.java,v 1.8.2.3 2008/01/07 15:14:20 cwl Exp $
007: */
008:
009: package com.sleepycat.persist.model;
010:
011: import static java.lang.annotation.ElementType.FIELD;
012: import static java.lang.annotation.RetentionPolicy.RUNTIME;
013:
014: import java.lang.annotation.Documented;
015: import java.lang.annotation.Retention;
016: import java.lang.annotation.Target;
017:
018: import com.sleepycat.persist.EntityStore;
019: import com.sleepycat.persist.PrimaryIndex;
020:
021: /**
022: * Indicates the primary key field of an entity class. The value of the
023: * primary key field is the unique identifier for the entity in a {@link
024: * PrimaryIndex}.
025: *
026: * <p>{@link PrimaryKey} may appear on at most one declared field per
027: * class.</p>
028: *
029: * <p>Primary key values may be automatically assigned as sequential integers
030: * using a {@link #sequence}. In this case the type of the key field is
031: * restricted to a simple integer type.</p>
032: *
033: * <p>A primary key field may not be null, unless it is being assigned from a
034: * sequence.</p>
035: *
036: * <p><a name="keyTypes"><strong>Key Field Types</strong></a></p>
037: *
038: * <p>The type of a key field must either be one of the following:</p>
039: * <ul>
040: * <li>Any of the {@link <a href="Entity.html#simpleTypes">simple
041: * types</a>}.</li>
042: * <li>A composite key class containing one or more simple type fields.</li>
043: * </ul>
044: * <p>Enum types and array types are not allowed.</p>
045: *
046: * <p>When using a composite key class containing more than one key field, each
047: * field of the composite key class must be annotated with {@link KeyField} to
048: * identify the storage order and default sort order. See {@link KeyField} for
049: * an example and more information on composite keys.</p>
050: *
051: * <p><a name="sortOrder"><strong>Key Sort Order</strong></a></p>
052: *
053: * <p>Key field types, being simple types, have a well defined and reasonable
054: * default sort order, described below. This sort order is based on a storage
055: * encoding that allows a fast byte-by-byte comparison.</p>
056: * <ul>
057: * <li>All simple types except for {@code String} are encoded so that they are
058: * sorted as expected, that is, as if the {@link Comparable#compareTo} method
059: * of their class (or, for primitives, their wrapper class) is called.</li>
060: * <br>
061: * <li>Strings are encoded as UTF-8 byte arrays. Zero (0x0000) character
062: * values are UTF encoded as non-zero values, and therefore embedded zeros in
063: * the string are supported. The sequence {@literal {0xC0,0x80}} is used to
064: * encode a zero character. This UTF encoding is the same one used by native
065: * Java UTF libraries. However, this encoding of zero does impact the
066: * lexicographical ordering, and zeros will not be sorted first (the natural
067: * order) or last. For all character values other than zero, the default UTF
068: * byte ordering is the same as the Unicode lexicographical character
069: * ordering.</li>
070: * </ul>
071: *
072: * <p>To override the default sort order, you can use a composite key class
073: * that implements {@link Comparable}. This allows overriding the sort order
074: * and is therefore useful even when there is only one key field in the
075: * composite key class. See {@link <a href="KeyField.html#comparable">Custom
076: * Sort Order</a>} for more information on sorting of composite keys.</p>
077: *
078: * <p><a name="inherit"><strong>Inherited Primary Key</strong></a></p>
079: *
080: * <p>If it does not appear on a declared field in the entity class, {@code
081: * PrimaryKey} must appear on a field of an entity superclass. In the
082: * following example, the primary key on the base class is used:</p>
083: *
084: * <pre class="code">
085: * {@literal @Persistent}
086: * class BaseClass {
087: * {@literal @PrimaryKey}
088: * long id;
089: * ...
090: * }
091: * {@literal @Entity}
092: * class Employee extends BaseClass {
093: * // inherits id primary key
094: * ...
095: * }</pre>
096: *
097: * <p>If more than one class with {@code PrimaryKey} is present in a class
098: * hierarchy, the key in the most derived class is used. In this case, primary
099: * key fields in superclasses are "shadowed" and are not persistent. In the
100: * following example, the primary key in the base class is not used and is not
101: * persistent:</p>
102: * <pre class="code">
103: * {@literal @Persistent}
104: * class BaseClass {
105: * {@literal @PrimaryKey}
106: * long id;
107: * ...
108: * }
109: * {@literal @Entity}
110: * class Employee extends BaseClass {
111: * // overrides id primary key
112: * {@literal @PrimaryKey}
113: * String uuid;
114: * ...
115: * }</pre>
116: *
117: * @author Mark Hayes
118: */
119: @Documented
120: @Retention(RUNTIME)
121: @Target(FIELD)
122: public @interface PrimaryKey {
123:
124: /**
125: * The name of a sequence from which to assign primary key values
126: * automatically. If a non-empty string is specified, sequential integers
127: * will be assigned from the named sequence.
128: *
129: * <p>A single sequence may be used for more than one entity class by
130: * specifying the same sequence name for each {@code PrimaryKey}. For
131: * each named sequence, a {@link com.sleepycat.je.Sequence} will be used to
132: * assign key values. For more information on configuring sequences, see
133: * {@link EntityStore#setSequenceConfig EntityStore.setSequenceConfig}.</p>
134: *
135: * <p>To use a sequence, the type of the key field must be a primitive
136: * integer type ({@code byte}, {@code short}, {@code int} or {@code long})
137: * or the primitive wrapper class for one of these types. A composite key
138: * class may also be used to override sort order, but it may contain only a
139: * single key field that has one of the types previously mentioned.</p>
140: *
141: * <p>When an entity with a primary key sequence is stored using one of the
142: * <code>put</code> methods in the {@link PrimaryIndex}, a new key will be
143: * assigned if the primary key field in the entity instance is null (for a
144: * reference type) or zero (for a primitive integer type). Specifying zero
145: * for a primitive integer key field is allowed because the initial value
146: * of the sequence is one (not zero) by default. If the sequence
147: * configuration is changed such that zero is part of the sequence, then
148: * the field type must be a primitive wrapper class and the field value
149: * must be null to cause a new key to be assigned.</p>
150: *
151: * <p>When one of the <code>put</code> methods in the {@link PrimaryIndex}
152: * is called and a new key is assigned, the assigned value is returned to
153: * the caller via the key field of the entity object that is passed as a
154: * parameter.</p>
155: */
156: String sequence() default "";
157: }
|