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