EntityPersister


1   //$Id: EntityPersister.java,v 1.12 2005/07/16 22:20:47 oneovthafew Exp $
2   package org.hibernate.persister.entity;
3   
4   import java.io.Serializable  ;
5   import java.util.Map  ;
6   
7   import org.hibernate.HibernateException;
8   import org.hibernate.LockMode;
9   import org.hibernate.MappingException;
10  import org.hibernate.EntityMode;
11  import org.hibernate.cache.CacheConcurrencyStrategy;
12  import org.hibernate.cache.entry.CacheEntryStructure;
13  import org.hibernate.engine.CascadeStyle;
14  import org.hibernate.engine.SessionFactoryImplementor;
15  import org.hibernate.engine.SessionImplementor;
16  import org.hibernate.id.IdentifierGenerator;
17  import org.hibernate.metadata.ClassMetadata;
18  import org.hibernate.type.Type;
19  import org.hibernate.type.VersionType;
20  
21  /**
22   * Concrete <tt>EntityPersister</tt>s implement mapping and persistence logic for a particular persistent class.
23   * <br><br>
24   * Implementors must be threadsafe (preferrably immutable) and must provide a constructor
25   * of type
26   * <tt>(org.hibernate.map.PersistentClass, org.hibernate.impl.SessionFactoryImplementor)</tt>.
27   *
28   * @author Gavin King
29   */
30  public interface EntityPersister {
31  
32      /**
33       * The property name of the "special" identifier property in HQL
34       */
35      public static final String   ENTITY_ID = "id";
36  
37      /**
38       * Finish the initialization of this object, once all <tt>ClassPersisters</tt> have been instantiated.
39       *
40       * Called only once, before any other method.
41       */
42      public void postInstantiate() throws MappingException;
43  
44      /**
45       * Return the SessionFactory to which this persister "belongs".
46       *
47       * @return The owning SessionFactory.
48       */
49      public SessionFactoryImplementor getFactory();
50  
51  
52      // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
53      // stuff that is persister-centric and/or EntityInfo-centric ~~~~~~~~~~~~~~
54      // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55  
56      /**
57       * Returns an object that identifies the space in which identifiers of this class hierarchy are unique.
58       *
59       * A table name, a JNDI URL, etc.
60       */
61      public String   getRootEntityName();
62  
63      /**
64       * The classname of the persistent class (used only for messages)
65       */
66      public String   getEntityName();
67      
68      /**
69       * Is the given entity name the name of a subclass, or this class?
70       */
71      public boolean isSubclassEntityName(String   entityName);
72  
73      /**
74       * Returns an array of objects that identify spaces in which properties of this class are persisted,
75       * for instances of this class only.
76       */
77      public Serializable  [] getPropertySpaces();
78  
79      /**
80       * Returns an array of objects that identify spaces in which properties of this class are persisted,
81       * for instances of this class and its subclasses.
82       */
83      public Serializable  [] getQuerySpaces();
84  
85      /**
86       * Does this class support dynamic proxies.
87       */
88      public boolean hasProxy();
89  
90      /**
91       * Do instances of this class contain collections.
92       */
93      public boolean hasCollections();
94      
95      /**
96       * Does this entity declare any properties of
97       * mutable type?
98       */
99      public boolean hasMutableProperties();
100     
101     /**
102      * Does this entity own any collections which are
103      * fetchable by subselect?
104      */
105     public boolean hasSubselectLoadableCollections();
106 
107     /**
108      * Does this class declare any cascading save/update/deletes.
109      */
110     public boolean hasCascades();
111 
112     /**
113      * Are instances of this class mutable.
114      */
115     public boolean isMutable();
116 
117     /**
118      * Is this class mapped as a subclass of another class?
119      */
120     public boolean isInherited();
121 
122     /**
123      * Is the identifier assigned before the insert by an <tt>IDGenerator</tt>. Or
124      * is it returned by the <tt>insert()</tt> method? This determines which form
125      * of <tt>insert()</tt> will be called.
126      */
127     public boolean isIdentifierAssignedByInsert();
128 
129     /**
130      * Get the type of a particular property
131      */
132     public Type getPropertyType(String   propertyName) throws MappingException;
133 
134     /**
135      * Compare two snapshots of the state of an instance to determine if the persistent state
136      * was modified
137      * @return <tt>null</tt> or the indices of the dirty properties
138      */
139     public int[] findDirty(Object  [] x, Object  [] y, Object   owner, SessionImplementor session)
140     throws HibernateException;
141 
142     /**
143      * Compare the state of an instance to the current database state
144      * @return <tt>null</tt> or the indices of the dirty properties
145      */
146     public int[] findModified(Object  [] old, Object  [] current, Object   object, SessionImplementor session)
147     throws HibernateException;
148 
149     /**
150      * Does the class have a property holding the identifier value?
151      */
152     public boolean hasIdentifierProperty();
153     /**
154      * Do detached instances of this class carry their own identifier value?
155      */
156     public boolean hasIdentifierPropertyOrEmbeddedCompositeIdentifier();
157 
158     /**
159      * Are instances of this class versioned by a timestamp or version number column.
160      */
161     public boolean isVersioned();
162 
163     /**
164      * Get the type of versioning (optional operation)
165      */
166     public VersionType getVersionType();
167 
168     /**
169      * Which property holds the version number (optional operation).
170      */
171     public int getVersionProperty();
172     
173     /**
174      * Does this entity declare a natural id?
175      */
176     public boolean hasNaturalIdentifier();
177 
178     /**
179      * Which properties hold the natural id?
180      */
181     public int[] getNaturalIdentifierProperties();
182     
183     /**
184      * Return the <tt>IdentifierGenerator</tt> for the class
185      */
186     public IdentifierGenerator getIdentifierGenerator() throws HibernateException;
187 
188     /**
189      * Load an instance of the persistent class.
190      */
191     public Object   load(Serializable   id, Object   optionalObject, LockMode lockMode, SessionImplementor session)
192     throws HibernateException;
193 
194     /**
195      * Do a version check (optional operation)
196      */
197     public void lock(Serializable   id, Object   version, Object   object, LockMode lockMode, SessionImplementor session)
198     throws HibernateException;
199 
200     /**
201      * Persist an instance
202      */
203     public void insert(Serializable   id, Object  [] fields, Object   object, SessionImplementor session)
204     throws HibernateException;
205 
206     /**
207      * Persist an instance, using a natively generated identifier (optional operation)
208      */
209     public Serializable   insert(Object  [] fields, Object   object, SessionImplementor session)
210     throws HibernateException;
211 
212     /**
213      * Delete a persistent instance
214      */
215     public void delete(Serializable   id, Object   version, Object   object, SessionImplementor session)
216     throws HibernateException;
217 
218     /**
219      * Update a persistent instance
220      */
221     public void update(
222         Serializable   id,
223         Object  [] fields,
224         int[] dirtyFields,
225         boolean hasDirtyCollection,
226         Object  [] oldFields,
227         Object   oldVersion,
228         Object   object,
229         Object   rowId,
230         SessionImplementor session
231     ) throws HibernateException;
232 
233     /**
234      * Get the Hibernate types of the class properties
235      */
236     public Type[] getPropertyTypes();
237 
238     /**
239      * Get the names of the class properties - doesn't have to be the names of the
240      * actual Java properties (used for XML generation only)
241      */
242     public String  [] getPropertyNames();
243 
244     /**
245      * Get the "insertability" of the properties of this class
246      * (does the property appear in an SQL INSERT)
247      */
248     public boolean[] getPropertyInsertability();
249 
250     /**
251      * Get the "updateability" of the properties of this class
252      * (does the property appear in an SQL UPDATE)
253      */
254     public boolean[] getPropertyUpdateability();
255     
256     /**
257      * Get the "checkability" of the properties of this class
258      * (is the property dirty checked, does the cache need
259      * to be updated)
260      */
261     public boolean[] getPropertyCheckability();
262 
263     /**
264      * Get the nullability of the properties of this class
265      */
266     public boolean[] getPropertyNullability();
267 
268     /**
269      * Get the "versionability" of the properties of this class
270      * (is the property optimistic-locked)
271      */
272     public boolean[] getPropertyVersionability();
273     /**
274      * Get the cascade styles of the propertes (optional operation)
275      */
276     public CascadeStyle[] getPropertyCascadeStyles();
277 
278     /**
279      * Get the identifier type
280      */
281     public Type getIdentifierType();
282 
283     /**
284      * Get the name of the identifier property (or return null) - need not return the
285      * name of an actual Java property
286      */
287     public String   getIdentifierPropertyName();
288 
289     /**
290      * Should we always invalidate the cache instead of
291      * recaching updated state
292      */
293     public boolean isCacheInvalidationRequired();
294     /**
295      * Does this class have a cache.
296      */
297     public boolean hasCache();
298     /**
299      * Get the cache (optional operation)
300      */
301     public CacheConcurrencyStrategy getCache();
302     /**
303      * Get the cache structure
304      */
305     public CacheEntryStructure getCacheEntryStructure();
306 
307     /**
308      * Get the user-visible metadata for the class (optional operation)
309      */
310     public ClassMetadata getClassMetadata();
311 
312     /**
313      * Is batch loading enabled?
314      */
315     public boolean isBatchLoadable();
316 
317     /**
318      * Is select snapshot before update enabled?
319      */
320     public boolean isSelectBeforeUpdateRequired();
321 
322     /**
323      * Get the current database state of the object, in a "hydrated" form, without
324      * resolving identifiers
325      * @return null if there is no row in the database
326      */
327     public Object  [] getDatabaseSnapshot(Serializable   id, SessionImplementor session)
328     throws HibernateException;
329 
330     /**
331      * Get the current version of the object, or return null if there is no row for
332      * the given identifier. In the case of unversioned data, return any object
333      * if the row exists.
334      */
335     public Object   getCurrentVersion(Serializable   id, SessionImplementor session)
336     throws HibernateException;
337 
338     public EntityMode guessEntityMode(Object   object);
339 
340 
341     // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
342     // stuff that is tuplizer-centric, but is passed a session ~~~~~~~~~~~~~~~~
343     // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
344 
345     /**
346      * Called just after the entities properties have been initialized
347      */
348     public void afterInitialize(Object   entity, boolean lazyPropertiesAreUnfetched, SessionImplementor session);
349 
350     /**
351      * Called just after the entity has been reassociated with the session
352      */
353     public void afterReassociate(Object   entity, SessionImplementor session);
354 
355     /**
356      * Create a new proxy instance
357      */
358     public Object   createProxy(Serializable   id, SessionImplementor session)
359     throws HibernateException;
360 
361     /**
362      * Is this a new transient instance?
363      */
364     public Boolean   isTransient(Object   object, SessionImplementor session) throws HibernateException;
365 
366     /**
367      * Return the values of the insertable properties of the object (including backrefs)
368      */
369     public Object  [] getPropertyValuesToInsert(Object   object, Map   mergeMap, SessionImplementor session) throws HibernateException;
370 
371 
372     // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
373     // stuff that is Tuplizer-centric ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
374     // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
375 
376     /**
377      * The persistent class, or null
378      */
379     public Class   getMappedClass(EntityMode entityMode);
380 
381     /**
382      * Does the class implement the <tt>Lifecycle</tt> interface.
383      */
384     public boolean implementsLifecycle(EntityMode entityMode);
385 
386     /**
387      * Does the class implement the <tt>Validatable</tt> interface.
388      */
389     public boolean implementsValidatable(EntityMode entityMode);
390     /**
391      * Get the proxy interface that instances of <em>this</em> concrete class will be 
392      * cast to (optional operation).
393      */
394     public Class   getConcreteProxyClass(EntityMode entityMode);
395 
396     /**
397      * Set the given values to the mapped properties of the given object
398      */
399     public void setPropertyValues(Object   object, Object  [] values, EntityMode entityMode) throws HibernateException;
400 
401     /**
402      * Set the value of a particular property
403      */
404     public void setPropertyValue(Object   object, int i, Object   value, EntityMode entityMode) throws HibernateException;
405 
406     /**
407      * Return the (loaded) values of the mapped properties of the object (not including backrefs)
408      */
409     public Object  [] getPropertyValues(Object   object, EntityMode entityMode) throws HibernateException;
410 
411     /**
412      * Get the value of a particular property
413      */
414     public Object   getPropertyValue(Object   object, int i, EntityMode entityMode) throws HibernateException;
415     
416     /**
417      * Get the value of a particular property
418      */
419     public Object   getPropertyValue(Object   object, String   propertyName, EntityMode entityMode) throws HibernateException;
420 
421     /**
422      * Get the identifier of an instance (throw an exception if no identifier property)
423      */
424     public Serializable   getIdentifier(Object   object, EntityMode entityMode) throws HibernateException;
425     
426     /**
427      * Set the identifier of an instance (or do nothing if no identifier property)
428      */
429     public void setIdentifier(Object   object, Serializable   id, EntityMode entityMode) throws HibernateException;
430 
431     /**
432      * Get the version number (or timestamp) from the object's version property (or return null if not versioned)
433      */
434     public Object   getVersion(Object   object, EntityMode entityMode) throws HibernateException;
435 
436     /**
437      * Create a class instance initialized with the given identifier
438      */
439     public Object   instantiate(Serializable   id, EntityMode entityMode) throws HibernateException;
440 
441     /**
442      * Is the given object an instance of this entity?
443      */
444     public boolean isInstance(Object   object, EntityMode entityMode);
445     
446     /**
447      * Does the given instance have any uninitialized lazy properties?
448      */
449     public boolean hasUninitializedLazyProperties(Object   object, EntityMode entityMode);
450     
451     /**
452      * Set the identifier and version of the given instance back 
453      * to its "unsaved" value, returning the id
454      * @param currentId TODO
455      * @param currentVersion TODO
456      */
457     public void resetIdentifier(Object   entity, Serializable   currentId, Object   currentVersion, EntityMode entityMode);
458 
459     /**
460      * Get the persister for an instance of this class or a subclass
461      */
462     public EntityPersister getSubclassEntityPersister(Object   instance, SessionFactoryImplementor factory, EntityMode entityMode);
463 }
464
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags