EntityModel


1   /*-
2    * See the file LICENSE for redistribution information.
3    *
4    * Copyright (c) 2002,2006 Oracle.  All rights reserved.
5    *
6    * $Id: EntityModel.java,v 1.14 2006/12/04 18:52:56 linda Exp $
7    */
8   
9   package com.sleepycat.persist.model;
10  
11  import java.util.ArrayList  ;
12  import java.util.Collections  ;
13  import java.util.List  ;
14  import java.util.Set  ;
15  
16  import com.sleepycat.persist.EntityStore;
17  import com.sleepycat.persist.PrimaryIndex;
18  import com.sleepycat.persist.SecondaryIndex;
19  import com.sleepycat.persist.impl.Format;
20  import com.sleepycat.persist.impl.PersistCatalog;
21  import com.sleepycat.persist.raw.RawObject;
22  import com.sleepycat.persist.raw.RawType;
23  
24  /**
25   * The base class for classes that provide entity model metadata.  An {@link
26   * EntityModel} defines entity classes, primary keys, secondary keys, and
27   * relationships between entities.  For each entity class that is part of the
28   * model, a single {@link PrimaryIndex} object and zero or more {@link
29   * SecondaryIndex} objects may be accessed via an {@link EntityStore}.
30   * 
31   * <p>The built-in entity model, the {@link AnnotationModel}, is based on
32   * annotations that are added to entity classes and their key fields.
33   * Annotations are used in the examples in this package, and it is expected
34   * that annotations will normally be used; most readers should therefore skip
35   * to the {@link AnnotationModel} class.  However, a custom entity model class
36   * may define its own metadata.  This can be used to define entity classes and
37   * keys using mechanisms other than annotations.</p>
38   *
39   * <p>A concrete entity model class should extend this class and implement the
40   * {@link #getClassMetadata}, {@link #getEntityMetadata} and {@link
41   * #getKnownClasses} methods.</p>
42   *
43   * <p>This is an abstract class rather than an interface to allow adding
44   * capabilities to the model at a future date without causing
45   * incompatibilities.  For example, a method may be added in the future for
46   * returning new information about the model and subclasses may override this
47   * method to return the new information.  Any new methods will have default
48   * implementations that return default values, and the use of the new
49   * information will be optional.</p>
50   *
51   * @author Mark Hayes
52   */
53  public abstract class EntityModel {
54  
55      private PersistCatalog catalog;
56  
57      /**
58       * The default constructor for use by subclasses.
59       */
60      protected EntityModel() {
61      }
62  
63      /**
64       * Returns whether the model is associated with an open store.
65       *
66       * <p>The {@link #registerClass} method may only be called when the model
67       * is not yet open.  Certain other methods may only be called when the
68       * model is open:</p>
69       * <ul>
70       * <li>{@link #convertRawObject}</li>
71       * <li>{@link #getAllRawTypeVersions}</li>
72       * <li>{@link #getRawType}</li>
73       * <li>{@link #getRawTypeVersion}</li>
74       * </ul>
75       */
76      public final boolean isOpen() {
77          return catalog != null;
78      }
79  
80      /**
81       * Registers a persistent class, most importantly, a {@link
82       * PersistentProxy} class.  Any persistent class may be registered in
83       * advance of using it, to avoid the overhead of updating the catalog
84       * database when an instance of the class is first stored.  This method
85       * <em>must</em> be called to register {@link PersistentProxy} classes.
86       * This method must be called before opening a store based on this model.
87       *
88       * @throws IllegalStateException if this method is called for a model that
89       * is associated with an open store.
90       *
91       * @throws IllegalArgumentException if the given class is not persistent.
92       */
93      public final void registerClass(Class   persistentClass) {
94          if (catalog != null) {
95              throw new IllegalStateException  ("Store is already open");
96          } else {
97              String   className = persistentClass.getName();
98              ClassMetadata meta = getClassMetadata(className);
99              if (meta == null) {
100                 throw new IllegalArgumentException  
101                     ("Class is not persistent: " + className);
102             }
103         }
104     }
105 
106     /**
107      * Gives this model access to the catalog, which is used for returning
108      * raw type information.
109      */
110     void setCatalog(PersistCatalog catalog) {
111         this.catalog = catalog;
112     }
113 
114     /**
115      * Returns the metadata for a given persistent class name, including proxy
116      * classes and entity classes.
117      *
118      * @return the metadata or null if the class is not persistent or does not
119      * exist.
120      */
121     public abstract ClassMetadata getClassMetadata(String   className);
122 
123     /**
124      * Returns the metadata for a given entity class name.
125      *
126      * @return the metadata or null if the class is not an entity class or does
127      * not exist.
128      */
129     public abstract EntityMetadata getEntityMetadata(String   className);
130 
131     /**
132      * Returns the names of all known persistent classes.  A type becomes known
133      * when an instance of the type is stored for the first time or metadata or
134      * type information is queried for a specific class name.
135      *
136      * @return an unmodifiable set of class names.
137      *
138      * @throws IllegalStateException if this method is called for a model that
139      * is not associated with an open store.
140      */
141     public abstract Set  <String  > getKnownClasses();
142 
143     /**
144      * Returns the type information for the current version of a given class,
145      * or null if the class is not currently persistent.
146      *
147      * @param className the name of the current version of the class.
148      *
149      * @throws IllegalStateException if this method is called for a model that
150      * is not associated with an open store.
151      */
152     public final RawType getRawType(String   className) {
153         if (catalog != null) {
154             return catalog.getFormat(className);
155         } else {
156             throw new IllegalStateException  ("Store is not open");
157         }
158     }
159 
160     /**
161      * Returns the type information for a given version of a given class,
162      * or null if the given version of the class is unknown.
163      *
164      * @param className the name of the latest version of the class.
165      *
166      * @param version the desired version of the class.
167      *
168      * @throws IllegalStateException if this method is called for a model that
169      * is not associated with an open store.
170      *
171      * @throws IllegalStateException if this method is called for a model that
172      * is not associated with an open store.
173      */
174     public final RawType getRawTypeVersion(String   className, int version) {
175         if (catalog != null) {
176             Format format = catalog.getLatestVersion(className);
177             while (format != null) {
178                 if (version == format.getVersion()) {
179                     return format;
180                 }
181             }
182             return null;
183         } else {
184             throw new IllegalStateException  ("Store is not open");
185         }
186     }
187 
188     /**
189      * Returns all known versions of type information for a given class name,
190      * or null if no persistent version of the class is known.
191      *
192      * @param className the name of the latest version of the class.
193      *
194      * @return an unmodifiable list of types for the given class name in order
195      * from most recent to least recent.
196      *
197      * @throws IllegalStateException if this method is called for a model that
198      * is not associated with an open store.
199      */
200     public final List  <RawType> getAllRawTypeVersions(String   className) {
201         if (catalog != null) {
202             Format format = catalog.getLatestVersion(className);
203             if (format != null) {
204                 List  <RawType> list = new ArrayList  <RawType>();
205                 while (format != null) {
206                     list.add(format);
207                     format = format.getPreviousVersion();
208                 }
209                 return Collections.unmodifiableList(list);
210             } else {
211                 return null;
212             }
213         } else {
214             throw new IllegalStateException  ("Store is not open");
215         }
216     }
217 
218     /**
219      * Converts a given raw object to a live object according to the current
220      * class definitions.
221      *
222      * <p>The given raw object must conform to the current class definitions.
223      * However, the raw type ({@link RawObject#getType}) is allowed to be from
224      * a different store, as long as the class names and the value types match.
225      * This allows converting raw objects that are read from one store to live
226      * objects in another store, for example, in a conversion program.</p>
227      */
228     public final Object   convertRawObject(RawObject raw) {
229         return catalog.convertRawObject(raw, null);
230     }
231 }
232
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags