1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2002-2009 Oracle. All rights reserved. 5 * 6 * $Id$ 7 */ 8 9package com.sleepycat.persist.model; 10 11import static java.lang.annotation.ElementType.FIELD; 12import static java.lang.annotation.RetentionPolicy.RUNTIME; 13 14import java.lang.annotation.Documented; 15import java.lang.annotation.Retention; 16import java.lang.annotation.Target; 17 18import com.sleepycat.persist.EntityStore; 19import 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 27 * class.</p> 28 * 29 * <p>Primary key values may be automatically assigned as sequential integers 30 * using a {@link #sequence}. In this case the type of the key field is 31 * restricted to a simple integer type.</p> 32 * 33 * <p>A primary key field may not be null, unless it is being assigned from a 34 * sequence.</p> 35 * 36 * <p><a name="keyTypes"><strong>Key Field Types</strong></a></p> 37 * 38 * <p>The type of a key field must either be one of the following:</p> 39 * <ul> 40 * <li>Any of the {@link <a href="Entity.html#simpleTypes">simple 41 * types</a>}.</li> 42 * <li>An enum type.</p> 43 * <li>A composite key class containing one or more simple type or enum 44 * fields.</li> 45 * </ul> 46 * <p>Array types are not allowed.</p> 47 * 48 * <p>When using a composite key class, each field of the composite key class 49 * must be annotated with {@link KeyField} to identify the storage order and 50 * default sort order. See {@link KeyField} for an example and more 51 * information on composite keys.</p> 52 * 53 * <p><a name="sortOrder"><strong>Key Sort Order</strong></a></p> 54 * 55 * <p>Key field types, being simple types, have a well defined and reasonable 56 * default sort order, described below. This sort order is based on a storage 57 * encoding that allows a fast byte-by-byte comparison.</p> 58 * <ul> 59 * <li>All simple types except for {@code String} are encoded so that they are 60 * sorted as expected, that is, as if the {@link Comparable#compareTo} method 61 * of their class (or, for primitives, their wrapper class) is called.</li> 62 * <br> 63 * <li>Strings are encoded as UTF-8 byte arrays. Zero (0x0000) character 64 * values are UTF encoded as non-zero values, and therefore embedded zeros in 65 * the string are supported. The sequence {@literal {0xC0,0x80}} is used to 66 * encode a zero character. This UTF encoding is the same one used by native 67 * Java UTF libraries. However, this encoding of zero does impact the 68 * lexicographical ordering, and zeros will not be sorted first (the natural 69 * order) or last. For all character values other than zero, the default UTF 70 * byte ordering is the same as the Unicode lexicographical character 71 * ordering.</li> 72 * </ul> 73 * 74 * <p>When using a composite key class with more than one field, the sorting 75 * order among fields is determined by the {@link KeyField} annotations. To 76 * override the default sort order, you can use a composite key class that 77 * implements {@link Comparable}. This allows overriding the sort order and is 78 * therefore useful even when there is only one key field in the composite key 79 * class. See {@link <a href="KeyField.html#comparable">Custom Sort Order</a>} 80 * for more information on sorting of composite keys.</p> 81 * 82 * <p><a name="inherit"><strong>Inherited Primary Key</strong></a></p> 83 * 84 * <p>If it does not appear on a declared field in the entity class, {@code 85 * PrimaryKey} must appear on a field of an entity superclass. In the 86 * following example, the primary key on the base class is used:</p> 87 * 88 * <pre class="code"> 89 * {@literal @Persistent} 90 * class BaseClass { 91 * {@literal @PrimaryKey} 92 * long id; 93 * ... 94 * } 95 * {@literal @Entity} 96 * class Employee extends BaseClass { 97 * // inherits id primary key 98 * ... 99 * }</pre> 100 * 101 * <p>If more than one class with {@code PrimaryKey} is present in a class 102 * hierarchy, the key in the most derived class is used. In this case, primary 103 * key fields in superclasses are "shadowed" and are not persistent. In the 104 * following example, the primary key in the base class is not used and is not 105 * persistent:</p> 106 * <pre class="code"> 107 * {@literal @Persistent} 108 * class BaseClass { 109 * {@literal @PrimaryKey} 110 * long id; 111 * ... 112 * } 113 * {@literal @Entity} 114 * class Employee extends BaseClass { 115 * // overrides id primary key 116 * {@literal @PrimaryKey} 117 * String uuid; 118 * ... 119 * }</pre> 120 * 121 * <p>Note that a {@code PrimaryKey} is not allowed on entity subclasses. The 122 * following is illegal and will cause an {@code IllegalArgumentException} when 123 * trying to store an {@code Employee} instance:</p> 124 * <pre class="code"> 125 * {@literal @Entity} 126 * class Person { 127 * {@literal @PrimaryKey} 128 * long id; 129 * ... 130 * } 131 * {@literal @Persistent} 132 * class Employee extends Person { 133 * {@literal @PrimaryKey} 134 * String uuid; 135 * ... 136 * }</pre> 137 * 138 * @author Mark Hayes 139 */ 140@Documented @Retention(RUNTIME) @Target(FIELD) 141public @interface PrimaryKey { 142 143 /** 144 * The name of a sequence from which to assign primary key values 145 * automatically. If a non-empty string is specified, sequential integers 146 * will be assigned from the named sequence. 147 * 148 * <p>A single sequence may be used for more than one entity class by 149 * specifying the same sequence name for each {@code PrimaryKey}. For 150 * each named sequence, a {@link com.sleepycat.db.Sequence} will be used to 151 * assign key values. For more information on configuring sequences, see 152 * {@link EntityStore#setSequenceConfig EntityStore.setSequenceConfig}.</p> 153 * 154 * <p>To use a sequence, the type of the key field must be a primitive 155 * integer type ({@code byte}, {@code short}, {@code int} or {@code long}) 156 * or the primitive wrapper class for one of these types. A composite key 157 * class may also be used to override sort order, but it may contain only a 158 * single key field that has one of the types previously mentioned.</p> 159 * 160 * <p>When an entity with a primary key sequence is stored using one of the 161 * <code>put</code> methods in the {@link PrimaryIndex}, a new key will be 162 * assigned if the primary key field in the entity instance is null (for a 163 * reference type) or zero (for a primitive integer type). Specifying zero 164 * for a primitive integer key field is allowed because the initial value 165 * of the sequence is one (not zero) by default. If the sequence 166 * configuration is changed such that zero is part of the sequence, then 167 * the field type must be a primitive wrapper class and the field value 168 * must be null to cause a new key to be assigned.</p> 169 * 170 * <p>When one of the <code>put</code> methods in the {@link PrimaryIndex} 171 * is called and a new key is assigned, the assigned value is returned to 172 * the caller via the key field of the entity object that is passed as a 173 * parameter.</p> 174 */ 175 String sequence() default ""; 176} 177