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.TYPE; 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; 20import com.sleepycat.persist.SecondaryIndex; 21import com.sleepycat.persist.evolve.IncompatibleClassException; 22import com.sleepycat.persist.evolve.Mutations; 23 24/** 25 * Indicates a persistent entity class. For each entity class, a {@link 26 * PrimaryIndex} can be used to store and access instances of that class. 27 * Optionally, one or more {@link SecondaryIndex} objects may be used to access 28 * entity instances by secondary key. 29 * 30 * <p><strong>Entity Subclasses and Superclasses</strong></p> 31 * 32 * <p>An entity class may have any number of subclasses and superclasses; 33 * however, none of these may themselves be entity classes (annotated with 34 * {@code Entity}).</p> 35 * 36 * <p>Entity superclasses are used to share common definitions and instance 37 * data. For example, fields in an entity superclass may be defined as primary 38 * or secondary keys.</p> 39 * 40 * <p>Entity subclasses are used to provide polymorphism within a single {@code 41 * PrimaryIndex}. Instances of the entity class and its subclasses are stored 42 * in the same {@code PrimaryIndex}. Fields in an entity subclass may be 43 * defined as secondary keys.</p> 44 * 45 * <p>For example, the following {@code BaseClass} defines the primary key for 46 * any number of entity classes, using a single sequence to assign primary key 47 * values. The entity class {@code Pet} extends the base class, implicitly 48 * defining a primary index that will contain instances of it and its 49 * subclasses, including {@code Cat} which is defined below. The primary key 50 * ({@code id}) and secondary key ({@code name}) can be used to retrieve any 51 * {@code Pet} instance.</p> 52 * <pre class="code"> 53 * {@literal @Persistent} 54 * class BaseClass { 55 * {@literal @PrimaryKey(sequence="ID")} 56 * long id; 57 * } 58 * 59 * {@literal @Entity} 60 * class Pet extends BaseClass { 61 * {@literal @SecondaryKey(relate=ONE_TO_ONE)} 62 * String name; 63 * float height; 64 * float weight; 65 * }</pre> 66 * 67 * <p>The entity subclass {@code Cat} defines a secondary key ({@code 68 * finickyness}) that only applies to {@code Cat} instances. Querying by this 69 * key will never retrieve a {@code Dog} instance, if such a subclass existed, 70 * because a {@code Dog} instance will never contain a {@code finickyness} 71 * key.</p> 72 * <pre class="code"> 73 * {@literal @Persistent} 74 * class Cat extends Pet { 75 * {@literal @SecondaryKey(relate=MANY_TO_ONE)} 76 * int finickyness; 77 * }</pre> 78 * 79 * <p><em>WARNING:</em> Entity subclasses that define secondary keys must be 80 * registered prior to storing an instance of the class. This can be done in 81 * two ways:</p> 82 * <ol> 83 * <li>The {@link EntityModel#registerClass registerClass} method may be called 84 * to register the subclass before opening the entity store.</li> 85 * <li>The {@link EntityStore#getSubclassIndex getSubclassIndex} method may be 86 * called to implicitly register the subclass after opening the entity 87 * store.</li> 88 * </ol> 89 * 90 * <p><strong>Persistent Fields and Types</strong></p> 91 * 92 * <p>All non-transient instance fields of an entity class, as well as its 93 * superclasses and subclasses, are persistent. {@code static} and {@code 94 * transient} fields are not persistent. The persistent fields of a class may 95 * be {@code private}, package-private (default access), {@code protected} or 96 * {@code public}.</p> 97 * 98 * <p>It is worthwhile to note the reasons that object persistence is defined 99 * in terms of fields rather than properties (getters and setters). This 100 * allows business methods (getters and setters) to be defined independently of 101 * the persistent state of an object; for example, a setter method may perform 102 * validation that could not be performed if it were called during object 103 * deserialization. Similarly, this allows public methods to evolve somewhat 104 * independently of the (typically non-public) persistent fields.</p> 105 * 106 * <p><a name="simpleTypes"><strong>Simple Types</strong></a></p> 107 * 108 * <p>Persistent types are divided into simple types, enum types, complex 109 * types, and array types. Simple types and enum types are single valued, 110 * while array types may contain multiple elements and complex types may 111 * contain one or more named fields.</p> 112 * 113 * <p>Simple types include:</p> 114 * <ul> 115 * <li>Java primitive types: {@code boolean, char, byte, short, int, long, 116 * float, double}</p> 117 * <li>The wrapper classes for Java primitive types</p> 118 * <!-- 119 * <li>{@link java.math.BigDecimal}</p> 120 * --> 121 * <li>{@link java.math.BigInteger}</p> 122 * <li>{@link java.lang.String}</p> 123 * <li>{@link java.util.Date}</p> 124 * </ul> 125 * 126 * <p>When null values are required (for optional key fields, for example), 127 * primitive wrapper classes must be used instead of primitive types.</p> 128 * 129 * <p>Simple types, enum types and array types do not require annotations to 130 * make them persistent.</p> 131 * 132 * <p><a name="proxyTypes"><strong>Complex and Proxy Types</strong></a></p> 133 * 134 * <p>Complex persistent classes must be annotated with {@link Entity} or 135 * {@link Persistent}, or must be proxied by a persistent proxy class 136 * (described below). This includes entity classes, subclasses and 137 * superclasses, and all other complex classes referenced via fields of these 138 * classes.</p> 139 * 140 * <p>All complex persistent classes must have a default constructor. The 141 * default constructor may be {@code private}, package-private (default 142 * access), {@code protected}, or {@code public}. Other constructors are 143 * allowed but are not used by the persistence mechanism.</p> 144 * 145 * <p>It is sometimes desirable to store instances of a type that is externally 146 * defined and cannot be annotated or does not have a default constructor; for 147 * example, a class defined in the Java standard libraries or a 3rd party 148 * library. In this case, a {@link PersistentProxy} class may be used to 149 * represent the stored values for the externally defined type. The proxy 150 * class itself must be annotated with {@link Persistent} like other persistent 151 * classes, and the {@link Persistent#proxyFor} property must be specified.</p> 152 * 153 * <p>For convenience, built-in proxy classes are included for several common 154 * classes (listed below) in the Java library. If you wish, you may define 155 * your own {@link PersistentProxy} to override these built-in proxies.</p> 156 * <ul> 157 * <li>{@link java.util.HashSet}</li> 158 * <li>{@link java.util.TreeSet}</li> 159 * <li>{@link java.util.HashMap}</li> 160 * <li>{@link java.util.TreeMap}</li> 161 * <li>{@link java.util.ArrayList}</li> 162 * <li>{@link java.util.LinkedList}</li> 163 * </ul> 164 * 165 * <p>Complex persistent types should in general be application-defined 166 * classes. This gives the application control over the persistent state and 167 * its evolution over time.</p> 168 * 169 * <p><strong>Other Type Restrictions</strong></p> 170 * 171 * <p>Entity classes and subclasses may not be used in field declarations for 172 * persistent types. Fields of entity classes and subclasses must be simple 173 * types or non-entity persistent types (annotated with {@link Persistent} not 174 * with {@link Entity}).</p> 175 * 176 * <p>Entity classes, subclasses and superclasses may be {@code abstract} and 177 * may implement arbitrary interfaces. Interfaces do not need to be annotated 178 * with {@link Persistent} in order to be used in a persistent class, since 179 * interfaces do not contain instance fields.</p> 180 * 181 * <p>Persistent instances of static nested classes are allowed, but the nested 182 * class must be annotated with {@link Persistent} or {@link Entity}. Inner 183 * classes (non-static nested classes, including anonymous classes) are not 184 * currently allowed as persistent types.</p> 185 * 186 * <p>Arrays of simple and persistent complex types are allowed as fields of 187 * persistent types. Arrays may be multidimensional. However, an array may 188 * not be stored as a top level instance in a primary index. Only instances of 189 * entity classes and subclasses may be top level instances in a primary 190 * index.</p> 191 * 192 * <p><strong>Embedded Objects</strong></p> 193 * 194 * <p>As stated above, the embedded (or member) non-transient non-static fields 195 * of an entity class are themselves persistent and are stored along with their 196 * parent entity object. This allows embedded objects to be stored in an 197 * entity to an arbitrary depth.</p> 198 * 199 * <p>There is no arbitrary limit to the nesting depth of embedded objects 200 * within an entity; however, there is a practical limit. When an entity is 201 * marshalled, each level of nesting is implemented internally via recursive 202 * method calls. If the nesting depth is large enough, a {@code 203 * StackOverflowError} can occur. In practice, this has been observed with a 204 * nesting depth of 12,000, using the default Java stack size.</p> 205 * 206 * <p>This restriction on the nesting depth of embedded objects does not apply 207 * to cyclic references, since these are handled specially as described 208 * below.</p> 209 * 210 * <p><strong>Object Graphs</strong></p> 211 * 212 * <p>When an entity instance is stored, the graph of objects referenced via 213 * its fields is stored and retrieved as a graph. In other words, if a single 214 * instance is referenced by two or more fields when the entity is stored, the 215 * same will be true when the entity is retrieved.</p> 216 * 217 * <p>When a reference to a particular object is stored as a member field 218 * inside that object or one of its embedded objects, this is called a cyclic 219 * reference. Because multiple references to a single object are stored as 220 * such, cycles are also represented correctly and do not cause infinite 221 * recursion or infinite processing loops. If an entity containing a cyclic 222 * reference is stored, the cyclic reference will be present when the entity is 223 * retrieved.</p> 224 * 225 * <p>Note that the stored object graph is restricted in scope to a single 226 * entity instance. This is because each entity instance is stored separately. 227 * If two entities have a reference to the same object when stored, they will 228 * refer to two separate instances when the entities are retrieved.</p> 229 * 230 * @see Persistent 231 * @see PrimaryKey 232 * @see SecondaryKey 233 * @see KeyField 234 * 235 * @author Mark Hayes 236 */ 237@Documented @Retention(RUNTIME) @Target(TYPE) 238public @interface Entity { 239 240 /** 241 * Identifies a new version of a class when an incompatible class change 242 * has been made. Prior versions of a class are referred to by version 243 * number to perform class evolution and conversion using {@link 244 * Mutations}. 245 * 246 * <p>The first version of a class is version zero, if {@link #version} is 247 * not specified. When an incompatible class change is made, a version 248 * number must be assigned using {@link #version} that is higher than the 249 * previous version number for the class. If this is not done, an {@link 250 * IncompatibleClassException} will be thrown when the store is opened.</p> 251 */ 252 int version() default 0; 253} 254