PersistenceContext


1   //$Id: PersistenceContext.java,v 1.46 2005/07/20 07:16:17 oneovthafew Exp $
2   package org.hibernate.engine;
3   
4   import java.io.Serializable  ;
5   import java.util.HashSet  ;
6   import java.util.Map  ;
7   
8   import org.hibernate.HibernateException;
9   import org.hibernate.LockMode;
10  import org.hibernate.MappingException;
11  import org.hibernate.collection.PersistentCollection;
12  import org.hibernate.persister.collection.CollectionPersister;
13  import org.hibernate.persister.entity.EntityPersister;
14  
15  /**
16   * Holds the state of the persistence context, including the 
17   * first-level cache, entries, snapshots, proxies, etc.
18   * 
19   * @author Gavin King
20   */
21  public interface PersistenceContext {
22      
23      public boolean isStateless();
24      
25      /**
26       * Get the session
27       */
28      public SessionImplementor getSession();
29      
30      /**
31       * Get the context for collection loading
32       */
33      public CollectionLoadContext getCollectionLoadContext();
34  
35      /**
36       * Add a collection which has no owner loaded
37       */
38      public void addUnownedCollection(CollectionKey key, PersistentCollection collection);
39  
40      /**
41       * Get and remove a collection whose owner is not yet loaded,
42       * when its owner is being loaded
43       */
44      public PersistentCollection useUnownedCollection(CollectionKey key);
45  
46      /**
47       * Get the <tt>BatchFetchQueue</tt>, instantiating one if
48       * necessary.
49       */
50      public BatchFetchQueue getBatchFetchQueue();
51      
52      /**
53       * Clear the state of the persistence context
54       */
55      public void clear();
56  
57      /**
58       * @return false if we know for certain that all the entities are read-only
59       */
60      public boolean hasNonReadOnlyEntities();
61  
62      /**
63       * Set the status of an entry
64       */
65      public void setEntryStatus(EntityEntry entry, Status status);
66  
67      /**
68       * Called after transactions end
69       */
70      public void afterTransactionCompletion();
71  
72      /**
73       * Get the current state of the entity as known to the underlying
74       * database, or null if there is no corresponding row 
75       */
76      public Object  [] getDatabaseSnapshot(Serializable   id, EntityPersister persister)
77              throws HibernateException;
78  
79      public Object  [] getCachedDatabaseSnapshot(EntityKey key);
80  
81      /**
82       * Add a canonical mapping from entity key to entity instance
83       */
84      public void addEntity(EntityKey key, Object   entity);
85  
86      /**
87       * Get the entity instance associated with the given 
88       * <tt>EntityKey</tt>
89       */
90      public Object   getEntity(EntityKey key);
91  
92      /**
93       * Is there an entity with the given key in the persistence context
94       */
95      public boolean containsEntity(EntityKey key);
96  
97      /**
98       * Remove an entity from the session cache, also clear
99       * up other state associated with the entity, all except
100      * for the <tt>EntityEntry</tt>
101      */
102     public Object   removeEntity(EntityKey key);
103 
104     /**
105      * Get an entity cached by unique key
106      */
107     public Object   getEntity(EntityUniqueKey euk);
108 
109     /**
110      * Add an entity to the cache by unique key
111      */
112     public void addEntity(EntityUniqueKey euk, Object   entity);
113 
114     /**
115      * Retreive the EntityEntry representation of the given entity.
116      *
117      * @param entity The entity for which to locate the EntityEntry.
118      * @return The EntityEntry for the given entity.
119      */
120     public EntityEntry getEntry(Object   entity);
121 
122     /**
123      * Remove an entity entry from the session cache
124      */
125     public EntityEntry removeEntry(Object   entity);
126 
127     /**
128      * Is there an EntityEntry for this instance?
129      */
130     public boolean isEntryFor(Object   entity);
131 
132     /**
133      * Get the collection entry for a persistent collection
134      */
135     public CollectionEntry getCollectionEntry(PersistentCollection coll);
136 
137     /**
138      * Adds an entity to the internal caches.
139      */
140     public EntityEntry addEntity(final Object   entity, final Status status,
141             final Object  [] loadedState, final EntityKey entityKey, final Object   version,
142             final LockMode lockMode, final boolean existsInDatabase,
143             final EntityPersister persister, final boolean disableVersionIncrement, boolean lazyPropertiesAreUnfetched);
144 
145     /**
146      * Generates an appropriate EntityEntry instance and adds it 
147      * to the event source's internal caches.
148      */
149     public EntityEntry addEntry(final Object   entity, final Status status,
150             final Object  [] loadedState, final Object   rowId, final Serializable   id,
151             final Object   version, final LockMode lockMode, final boolean existsInDatabase,
152             final EntityPersister persister, final boolean disableVersionIncrement, boolean lazyPropertiesAreUnfetched);
153 
154     /**
155      * Is the given proxy associated with this persistence context?
156      */
157     public boolean containsProxy(Object   proxy);
158 
159     /**
160      * Takes the given object and, if it represents a proxy, reassociates it with this event source.
161      *
162      * @param value The possible proxy to be reassociated.
163      * @return Whether the passed value represented an actual proxy which got initialized.
164      * @throws MappingException
165      */
166     public boolean reassociateIfUninitializedProxy(Object   value) throws MappingException;
167 
168     /**
169      * If a deleted entity instance is re-saved, and it has a proxy, we need to
170      * reset the identifier of the proxy 
171      */
172     public void reassociateProxy(Object   value, Serializable   id) throws MappingException;
173 
174     /**
175      * Get the entity instance underlying the given proxy, throwing
176      * an exception if the proxy is uninitialized. If the given object
177      * is not a proxy, simply return the argument.
178      */
179     public Object   unproxy(Object   maybeProxy) throws HibernateException;
180 
181     /**
182      * Possibly unproxy the given reference and reassociate it with the current session.
183      *
184      * @param maybeProxy The reference to be unproxied if it currently represents a proxy.
185      * @return The unproxied instance.
186      * @throws HibernateException
187      */
188     public Object   unproxyAndReassociate(Object   maybeProxy) throws HibernateException;
189 
190     /**
191      * Attempts to check whether the given key represents an entity already loaded within the
192      * current session.
193      * @param id The key to be checked.
194      * @param object The entity reference against which to perform the uniqueness check.
195      * @throws HibernateException
196      */
197     public void checkUniqueness(EntityKey key, Object   object) throws HibernateException;
198 
199     /**
200      * If the existing proxy is insufficiently "narrow" (derived), instantiate a new proxy
201      * and overwrite the registration of the old one. This breaks == and occurs only for
202      * "class" proxies rather than "interface" proxies. Also init the proxy to point to
203      * the given target implementation if necessary.
204      *
205      * @param proxy The proxy instance to be narrowed.
206      * @param persister The persister for the proxied entity.
207      * @param key The internal cache key for the proxied entity.
208      * @param object (optional) the actual proxied entity instance.
209      * @return An appropriately narrowed instance.
210      * @throws HibernateException
211      */
212     public Object   narrowProxy(Object   proxy, EntityPersister persister, EntityKey key, Object   object)
213             throws HibernateException;
214 
215     /**
216      * Return the existing proxy associated with the given <tt>EntityKey</tt>, or the
217      * third argument (the entity associated with the key) if no proxy exists. Init
218      * the proxy to the target implementation, if necessary.
219      */
220     public Object   proxyFor(EntityPersister persister, EntityKey key, Object   impl)
221             throws HibernateException;
222 
223     /**
224      * Return the existing proxy associated with the given <tt>EntityKey</tt>, or the
225      * argument (the entity associated with the key) if no proxy exists.
226      * (slower than the form above)
227      */
228     public Object   proxyFor(Object   impl) throws HibernateException;
229 
230     /**
231      * Get the entity that owns this persistent collection
232      */
233     public Object   getCollectionOwner(Serializable   key, CollectionPersister collectionPersister)
234             throws MappingException;
235 
236     /**
237      * add a collection we just loaded up (still needs initializing)
238      */
239     public void addUninitializedCollection(CollectionPersister persister,
240             PersistentCollection collection, Serializable   id);
241 
242     /**
243      * add a detached uninitialized collection
244      */
245     public void addUninitializedDetachedCollection(CollectionPersister persister,
246             PersistentCollection collection);
247 
248     /**
249      * Add a new collection (ie. a newly created one, just instantiated by the
250      * application, with no database state or snapshot)
251      * @param collection The collection to be associated with the persistence context
252      */
253     public void addNewCollection(CollectionPersister persister, PersistentCollection collection)
254             throws HibernateException;
255 
256     /**
257      * add an (initialized) collection that was created by another session and passed
258      * into update() (ie. one with a snapshot and existing state on the database)
259      */
260     public void addInitializedDetachedCollection(CollectionPersister collectionPersister,
261             PersistentCollection collection) throws HibernateException;
262 
263     /**
264      * add a collection we just pulled out of the cache (does not need initializing)
265      */
266     public CollectionEntry addInitializedCollection(CollectionPersister persister,
267             PersistentCollection collection, Serializable   id) throws HibernateException;
268 
269     /**
270      * Get the collection instance associated with the <tt>CollectionKey</tt>
271      */
272     public PersistentCollection getCollection(CollectionKey collectionKey);
273 
274     /**
275      * Register a collection for non-lazy loading at the end of the
276      * two-phase load
277      */
278     public void addNonLazyCollection(PersistentCollection collection);
279 
280     /**
281      * Force initialization of all non-lazy collections encountered during
282      * the current two-phase load (actually, this is a no-op, unless this
283      * is the "outermost" load)
284      */
285     public void initializeNonLazyCollections() throws HibernateException;
286 
287     /**
288      * Get the <tt>PersistentCollection</tt> object for an array
289      */
290     public PersistentCollection getCollectionHolder(Object   array);
291 
292     /**
293      * Register a <tt>PersistentCollection</tt> object for an array.
294      * Associates a holder with an array - MUST be called after loading 
295      * array, since the array instance is not created until endLoad().
296      */
297     public void addCollectionHolder(PersistentCollection holder);
298     
299     /**
300      * Remove the mapping of collection to holder during eviction
301      * of the owning entity
302      */
303     public PersistentCollection removeCollectionHolder(Object   array);
304 
305     /**
306      * Get the snapshot of the pre-flush collection state
307      */
308     public Serializable   getSnapshot(PersistentCollection coll);
309 
310     /**
311      * Is this the "inverse" end of a bidirectional association?
312      */
313     public boolean isInverseCollection(PersistentCollection collection);
314 
315     /**
316      * Get the collection entry for a collection passed to filter,
317      * which might be a collection wrapper, an array, or an unwrapped
318      * collection. Return null if there is no entry.
319      */
320     public CollectionEntry getCollectionEntryOrNull(Object   collection);
321 
322     /**
323      * Get an existing proxy by key
324      */
325     public Object   getProxy(EntityKey key);
326 
327     /**
328      * Add a proxy to the session cache
329      */
330     public void addProxy(EntityKey key, Object   proxy);
331 
332     /**
333      * Remove a proxy from the session cache
334      */
335     public Object   removeProxy(EntityKey key);
336 
337     /** 
338      * Retrieve the set of EntityKeys representing nullifiable references
339      */
340     public HashSet   getNullifiableEntityKeys();
341 
342     /**
343      * Get the mapping from key value to entity instance
344      */
345     public Map   getEntitiesByKey();
346     
347     /**
348      * Get the mapping from entity instance to entity entry
349      */
350     public Map   getEntityEntries();
351 
352     /**
353      * Get the mapping from collection instance to collection entry
354      */
355     public Map   getCollectionEntries();
356 
357     /**
358      * Get the mapping from collection key to collection instance
359      */
360     public Map   getCollectionsByKey();
361 
362     /**
363      * How deep are we cascaded?
364      */
365     public int getCascadeLevel();
366     
367     /**
368      * Called before cascading
369      */
370     public int incrementCascadeLevel();
371 
372     /**
373      * Called after cascading
374      */
375     public int decrementCascadeLevel();
376 
377     /**
378      * Is a flush cycle currently in process?
379      */
380     public boolean isFlushing();
381     
382     /**
383      * Called before and after the flushcycle
384      */
385     public void setFlushing(boolean flushing);
386 
387     /**
388      * Call this before begining a two-phase load
389      */
390     public void beforeLoad();
391 
392     /**
393      * Call this after finishing a two-phase load
394      */
395     public void afterLoad();
396 
397     /**
398      * Returns a string representation of the object.
399      *
400      * @return a string representation of the object.
401      */
402     public String   toString();
403 
404     /**
405      * Search the persistence context for an owner for the child object,
406      * given a collection role
407      */
408     public Serializable   getOwnerId(String   entity, String   property, Object   childObject, Map   mergeMap);
409 
410     /**
411      * Search the persistence context for an index of the child object,
412      * given a collection role
413      */
414     public Object   getIndexInOwner(String   entity, String   property, Object   childObject, Map   mergeMap);
415 
416     /**
417      * Record the fact that the association belonging to the keyed
418      * entity is null.
419      */
420     public void addNullProperty(EntityKey ownerKey, String   propertyName);
421 
422     /**
423      * Is the association property belonging to the keyed entity null?
424      */
425     public boolean isPropertyNull(EntityKey ownerKey, String   propertyName);
426     
427     /**
428      * Set the object to read only and discard it's snapshot
429      */
430     public void setReadOnly(Object   entity, boolean readOnly);
431 
432 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags