Entity


1   /*-
2    * See the file LICENSE for redistribution information.
3    *
4    * Copyright (c) 2002,2006 Oracle.  All rights reserved.
5    *
6    * $Id: Entity.java,v 1.11 2006/11/14 23:30:50 mark Exp $
7    */
8   
9   package com.sleepycat.persist.model;
10  
11  import static java.lang.annotation.ElementType.TYPE  ;
12  import static java.lang.annotation.RetentionPolicy.RUNTIME  ;
13  
14  import java.lang.annotation.Documented  ;
15  import java.lang.annotation.Retention  ;
16  import java.lang.annotation.Target  ;
17  
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 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>Object Graphs</strong></p>
181  *
182  * <p>When an entity instance is stored, the graph of objects refereneced via
183  * its fields is stored and retrieved as a graph.  In other words, if a single
184  * instance is referenced by two or more fields when the entity is stored, the
185  * same will be true when the entity is retrieved.</p>
186  *
187  * <p>However, the stored object graph is restricted in scope to a single
188  * entity instance.  This is because each entity instance is stored separately.
189  * If two entities have a reference to the same object when stored, they will
190  * refer to two separate instances when the entities are retrieved.</p>
191  *
192  * @see Persistent
193  * @see PrimaryKey
194  * @see SecondaryKey
195  * @see KeyField
196  *
197  * @author Mark Hayes
198  */
199 @Documented   @Retention  (RUNTIME) @Target  (TYPE)
200 public @interface Entity {
201 
202     /**
203      * Identifies a new version of a class when an incompatible class change
204      * has been made.  Prior versions of a class are referred to by version
205      * number to perform class evolution and conversion using {@link
206      * Mutations}.
207      *
208      * <p>The first version of a class is version zero, if {@link #version} is
209      * not specified.  When an incompatible class change is made, a version
210      * number must be assigned using {@link #version} that is higher than the
211      * previous version number for the class.  If this is not done, an {@link
212      * IncompatibleClassException} will be thrown when the store is opened.</p>
213      */
214     int version() default 0;
215 }
216
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags