001: /*-
002: * See the file LICENSE for redistribution information.
003: *
004: * Copyright (c) 2002,2008 Oracle. All rights reserved.
005: *
006: * $Id: Entity.java,v 1.11.2.4 2008/01/07 15:14:20 cwl Exp $
007: */
008:
009: package com.sleepycat.persist.model;
010:
011: import static java.lang.annotation.ElementType.TYPE;
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.PrimaryIndex;
019: import com.sleepycat.persist.SecondaryIndex;
020: import com.sleepycat.persist.evolve.IncompatibleClassException;
021: import com.sleepycat.persist.evolve.Mutations;
022:
023: /**
024: * Indicates a persistent entity class. For each entity class, a {@link
025: * PrimaryIndex} can be used to store and access instances of that class.
026: * Optionally, one or more {@link SecondaryIndex} objects may be used to access
027: * entity instances by secondary key.
028: *
029: * <p><strong>Entity Subclasses and Superclasses</strong></p>
030: *
031: * <p>An entity class may have any number of subclasses and superclasses;
032: * however, none of these may themselves be entity classes (annotated with
033: * {@code Entity}).</p>
034: *
035: * <p>Entity superclasses are used to share common definitions and instance
036: * data. For example, fields in an entity superclass may be defined as primary
037: * or secondary keys.</p>
038: *
039: * <p>Entity subclasses are used to provide polymorphism within a single {@code
040: * PrimaryIndex}. Instances of the entity class and its subclasses are stored
041: * in the same {@code PrimaryIndex}. Fields in an entity subclass may be
042: * defined as secondary keys.</p>
043: *
044: * <p>For example, the following {@code BaseClass} defines the primary key for
045: * any number of entity classes, using a single sequence to assign primary key
046: * values. The entity class {@code Pet} extends the base class, implicitly
047: * defining a primary index that will contain instances of it and its
048: * subclasses, including {@code Cat} which is defined below. The primary key
049: * ({@code id}) and secondary key ({@code name}) can be used to retrieve any
050: * {@code Pet} instance.</p>
051: * <pre class="code">
052: * {@literal @Persistent}
053: * class BaseClass {
054: * {@literal @PrimaryKey(sequence="ID")}
055: * long id;
056: * }
057: *
058: * {@literal @Entity}
059: * class Pet extends BaseClass {
060: * {@literal @SecondaryKey(relate=ONE_TO_ONE)}
061: * String name;
062: * float height;
063: * float weight;
064: * }</pre>
065: *
066: * <p>The entity subclass {@code Cat} defines a secondary key ({@code
067: * finickyness}) that only applies to {@code Cat} instances. Querying by this
068: * key will never retrieve a {@code Dog} instance, if such a subclass existed,
069: * because a {@code Dog} instance will never contain a {@code finickyness}
070: * key.</p>
071: * <pre class="code">
072: * {@literal @Persistent}
073: * class Cat extends Pet {
074: * {@literal @SecondaryKey(relate=MANY_TO_ONE)}
075: * int finickyness;
076: * }</pre>
077: *
078: * <p><strong>Persistent Fields and Types</strong></p>
079: *
080: * <p>All non-transient instance fields of an entity class, as well as its
081: * superclasses and subclasses, are persistent. {@code static} and {@code
082: * transient} fields are not persistent. The persistent fields of a class may
083: * be {@code private}, package-private (default access), {@code protected} or
084: * {@code public}.</p>
085: *
086: * <p>It is worthwhile to note the reasons that object persistence is defined
087: * in terms of fields rather than properties (getters and setters). This
088: * allows business methods (getters and setters) to be defined independently of
089: * the persistent state of an object; for example, a setter method may perform
090: * validation that could not be performed if it were called during object
091: * deserialization. Similarly, this allows public methods to evolve somewhat
092: * independently of the (typically non-public) persistent fields.</p>
093: *
094: * <p><a name="simpleTypes"><strong>Simple Types</strong></a></p>
095: *
096: * <p>Persistent types are divided into simple types, enum types, complex
097: * types, and array types. Simple types and enum types are single valued,
098: * while array types may contain multiple elements and complex types may
099: * 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
226: @Retention(RUNTIME)
227: @Target(TYPE)
228: public @interface Entity {
229:
230: /**
231: * Identifies a new version of a class when an incompatible class change
232: * has been made. Prior versions of a class are referred to by version
233: * number to perform class evolution and conversion using {@link
234: * Mutations}.
235: *
236: * <p>The first version of a class is version zero, if {@link #version} is
237: * not specified. When an incompatible class change is made, a version
238: * number must be assigned using {@link #version} that is higher than the
239: * previous version number for the class. If this is not done, an {@link
240: * IncompatibleClassException} will be thrown when the store is opened.</p>
241: */
242: int version() default 0;
243: }
|