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