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