001: //$Id: PersistenceContext.java 11301 2007-03-19 20:43:46Z steve.ebersole@jboss.com $
002: package org.hibernate.engine;
003:
004: import java.io.Serializable;
005: import java.util.HashSet;
006: import java.util.Map;
007:
008: import org.hibernate.HibernateException;
009: import org.hibernate.LockMode;
010: import org.hibernate.MappingException;
011: import org.hibernate.engine.loading.LoadContexts;
012: import org.hibernate.collection.PersistentCollection;
013: import org.hibernate.persister.collection.CollectionPersister;
014: import org.hibernate.persister.entity.EntityPersister;
015:
016: /**
017: * Holds the state of the persistence context, including the
018: * first-level cache, entries, snapshots, proxies, etc.
019: *
020: * @author Gavin King
021: */
022: public interface PersistenceContext {
023:
024: public boolean isStateless();
025:
026: /**
027: * Get the session to which this persistence context is bound.
028: *
029: * @return The session.
030: */
031: public SessionImplementor getSession();
032:
033: /**
034: * Retrieve this persistence context's managed load context.
035: *
036: * @return The load context
037: */
038: public LoadContexts getLoadContexts();
039:
040: /**
041: * Add a collection which has no owner loaded
042: */
043: public void addUnownedCollection(CollectionKey key,
044: PersistentCollection collection);
045:
046: /**
047: * Get and remove a collection whose owner is not yet loaded,
048: * when its owner is being loaded
049: */
050: public PersistentCollection useUnownedCollection(CollectionKey key);
051:
052: /**
053: * Get the <tt>BatchFetchQueue</tt>, instantiating one if
054: * necessary.
055: */
056: public BatchFetchQueue getBatchFetchQueue();
057:
058: /**
059: * Clear the state of the persistence context
060: */
061: public void clear();
062:
063: /**
064: * @return false if we know for certain that all the entities are read-only
065: */
066: public boolean hasNonReadOnlyEntities();
067:
068: /**
069: * Set the status of an entry
070: */
071: public void setEntryStatus(EntityEntry entry, Status status);
072:
073: /**
074: * Called after transactions end
075: */
076: public void afterTransactionCompletion();
077:
078: /**
079: * Get the current state of the entity as known to the underlying
080: * database, or null if there is no corresponding row
081: */
082: public Object[] getDatabaseSnapshot(Serializable id,
083: EntityPersister persister) throws HibernateException;
084:
085: public Object[] getCachedDatabaseSnapshot(EntityKey key);
086:
087: public Object[] getNaturalIdSnapshot(Serializable id,
088: EntityPersister persister) throws HibernateException;
089:
090: /**
091: * Add a canonical mapping from entity key to entity instance
092: */
093: public void addEntity(EntityKey key, Object entity);
094:
095: /**
096: * Get the entity instance associated with the given
097: * <tt>EntityKey</tt>
098: */
099: public Object getEntity(EntityKey key);
100:
101: /**
102: * Is there an entity with the given key in the persistence context
103: */
104: public boolean containsEntity(EntityKey key);
105:
106: /**
107: * Remove an entity from the session cache, also clear
108: * up other state associated with the entity, all except
109: * for the <tt>EntityEntry</tt>
110: */
111: public Object removeEntity(EntityKey key);
112:
113: /**
114: * Get an entity cached by unique key
115: */
116: public Object getEntity(EntityUniqueKey euk);
117:
118: /**
119: * Add an entity to the cache by unique key
120: */
121: public void addEntity(EntityUniqueKey euk, Object entity);
122:
123: /**
124: * Retreive the EntityEntry representation of the given entity.
125: *
126: * @param entity The entity for which to locate the EntityEntry.
127: * @return The EntityEntry for the given entity.
128: */
129: public EntityEntry getEntry(Object entity);
130:
131: /**
132: * Remove an entity entry from the session cache
133: */
134: public EntityEntry removeEntry(Object entity);
135:
136: /**
137: * Is there an EntityEntry for this instance?
138: */
139: public boolean isEntryFor(Object entity);
140:
141: /**
142: * Get the collection entry for a persistent collection
143: */
144: public CollectionEntry getCollectionEntry(PersistentCollection coll);
145:
146: /**
147: * Adds an entity to the internal caches.
148: */
149: public EntityEntry addEntity(final Object entity,
150: final Status status, final Object[] loadedState,
151: final EntityKey entityKey, final Object version,
152: final LockMode lockMode, final boolean existsInDatabase,
153: final EntityPersister persister,
154: final boolean disableVersionIncrement,
155: boolean lazyPropertiesAreUnfetched);
156:
157: /**
158: * Generates an appropriate EntityEntry instance and adds it
159: * to the event source's internal caches.
160: */
161: public EntityEntry addEntry(final Object entity,
162: final Status status, final Object[] loadedState,
163: final Object rowId, final Serializable id,
164: final Object version, final LockMode lockMode,
165: final boolean existsInDatabase,
166: final EntityPersister persister,
167: final boolean disableVersionIncrement,
168: boolean lazyPropertiesAreUnfetched);
169:
170: /**
171: * Is the given collection associated with this persistence context?
172: */
173: public boolean containsCollection(PersistentCollection collection);
174:
175: /**
176: * Is the given proxy associated with this persistence context?
177: */
178: public boolean containsProxy(Object proxy);
179:
180: /**
181: * Takes the given object and, if it represents a proxy, reassociates it with this event source.
182: *
183: * @param value The possible proxy to be reassociated.
184: * @return Whether the passed value represented an actual proxy which got initialized.
185: * @throws MappingException
186: */
187: public boolean reassociateIfUninitializedProxy(Object value)
188: throws MappingException;
189:
190: /**
191: * If a deleted entity instance is re-saved, and it has a proxy, we need to
192: * reset the identifier of the proxy
193: */
194: public void reassociateProxy(Object value, Serializable id)
195: throws MappingException;
196:
197: /**
198: * Get the entity instance underlying the given proxy, throwing
199: * an exception if the proxy is uninitialized. If the given object
200: * is not a proxy, simply return the argument.
201: */
202: public Object unproxy(Object maybeProxy) throws HibernateException;
203:
204: /**
205: * Possibly unproxy the given reference and reassociate it with the current session.
206: *
207: * @param maybeProxy The reference to be unproxied if it currently represents a proxy.
208: * @return The unproxied instance.
209: * @throws HibernateException
210: */
211: public Object unproxyAndReassociate(Object maybeProxy)
212: throws HibernateException;
213:
214: /**
215: * Attempts to check whether the given key represents an entity already loaded within the
216: * current session.
217: * @param object The entity reference against which to perform the uniqueness check.
218: * @throws HibernateException
219: */
220: public void checkUniqueness(EntityKey key, Object object)
221: throws HibernateException;
222:
223: /**
224: * If the existing proxy is insufficiently "narrow" (derived), instantiate a new proxy
225: * and overwrite the registration of the old one. This breaks == and occurs only for
226: * "class" proxies rather than "interface" proxies. Also init the proxy to point to
227: * the given target implementation if necessary.
228: *
229: * @param proxy The proxy instance to be narrowed.
230: * @param persister The persister for the proxied entity.
231: * @param key The internal cache key for the proxied entity.
232: * @param object (optional) the actual proxied entity instance.
233: * @return An appropriately narrowed instance.
234: * @throws HibernateException
235: */
236: public Object narrowProxy(Object proxy, EntityPersister persister,
237: EntityKey key, Object object) throws HibernateException;
238:
239: /**
240: * Return the existing proxy associated with the given <tt>EntityKey</tt>, or the
241: * third argument (the entity associated with the key) if no proxy exists. Init
242: * the proxy to the target implementation, if necessary.
243: */
244: public Object proxyFor(EntityPersister persister, EntityKey key,
245: Object impl) throws HibernateException;
246:
247: /**
248: * Return the existing proxy associated with the given <tt>EntityKey</tt>, or the
249: * argument (the entity associated with the key) if no proxy exists.
250: * (slower than the form above)
251: */
252: public Object proxyFor(Object impl) throws HibernateException;
253:
254: /**
255: * Get the entity that owns this persistent collection
256: */
257: public Object getCollectionOwner(Serializable key,
258: CollectionPersister collectionPersister)
259: throws MappingException;
260:
261: /**
262: * add a collection we just loaded up (still needs initializing)
263: */
264: public void addUninitializedCollection(
265: CollectionPersister persister,
266: PersistentCollection collection, Serializable id);
267:
268: /**
269: * add a detached uninitialized collection
270: */
271: public void addUninitializedDetachedCollection(
272: CollectionPersister persister,
273: PersistentCollection collection);
274:
275: /**
276: * Add a new collection (ie. a newly created one, just instantiated by the
277: * application, with no database state or snapshot)
278: * @param collection The collection to be associated with the persistence context
279: */
280: public void addNewCollection(CollectionPersister persister,
281: PersistentCollection collection) throws HibernateException;
282:
283: /**
284: * add an (initialized) collection that was created by another session and passed
285: * into update() (ie. one with a snapshot and existing state on the database)
286: */
287: public void addInitializedDetachedCollection(
288: CollectionPersister collectionPersister,
289: PersistentCollection collection) throws HibernateException;
290:
291: /**
292: * add a collection we just pulled out of the cache (does not need initializing)
293: */
294: public CollectionEntry addInitializedCollection(
295: CollectionPersister persister,
296: PersistentCollection collection, Serializable id)
297: throws HibernateException;
298:
299: /**
300: * Get the collection instance associated with the <tt>CollectionKey</tt>
301: */
302: public PersistentCollection getCollection(
303: CollectionKey collectionKey);
304:
305: /**
306: * Register a collection for non-lazy loading at the end of the
307: * two-phase load
308: */
309: public void addNonLazyCollection(PersistentCollection collection);
310:
311: /**
312: * Force initialization of all non-lazy collections encountered during
313: * the current two-phase load (actually, this is a no-op, unless this
314: * is the "outermost" load)
315: */
316: public void initializeNonLazyCollections()
317: throws HibernateException;
318:
319: /**
320: * Get the <tt>PersistentCollection</tt> object for an array
321: */
322: public PersistentCollection getCollectionHolder(Object array);
323:
324: /**
325: * Register a <tt>PersistentCollection</tt> object for an array.
326: * Associates a holder with an array - MUST be called after loading
327: * array, since the array instance is not created until endLoad().
328: */
329: public void addCollectionHolder(PersistentCollection holder);
330:
331: /**
332: * Remove the mapping of collection to holder during eviction
333: * of the owning entity
334: */
335: public PersistentCollection removeCollectionHolder(Object array);
336:
337: /**
338: * Get the snapshot of the pre-flush collection state
339: */
340: public Serializable getSnapshot(PersistentCollection coll);
341:
342: /**
343: * Get the collection entry for a collection passed to filter,
344: * which might be a collection wrapper, an array, or an unwrapped
345: * collection. Return null if there is no entry.
346: */
347: public CollectionEntry getCollectionEntryOrNull(Object collection);
348:
349: /**
350: * Get an existing proxy by key
351: */
352: public Object getProxy(EntityKey key);
353:
354: /**
355: * Add a proxy to the session cache
356: */
357: public void addProxy(EntityKey key, Object proxy);
358:
359: /**
360: * Remove a proxy from the session cache
361: */
362: public Object removeProxy(EntityKey key);
363:
364: /**
365: * Retrieve the set of EntityKeys representing nullifiable references
366: */
367: public HashSet getNullifiableEntityKeys();
368:
369: /**
370: * Get the mapping from key value to entity instance
371: */
372: public Map getEntitiesByKey();
373:
374: /**
375: * Get the mapping from entity instance to entity entry
376: */
377: public Map getEntityEntries();
378:
379: /**
380: * Get the mapping from collection instance to collection entry
381: */
382: public Map getCollectionEntries();
383:
384: /**
385: * Get the mapping from collection key to collection instance
386: */
387: public Map getCollectionsByKey();
388:
389: /**
390: * How deep are we cascaded?
391: */
392: public int getCascadeLevel();
393:
394: /**
395: * Called before cascading
396: */
397: public int incrementCascadeLevel();
398:
399: /**
400: * Called after cascading
401: */
402: public int decrementCascadeLevel();
403:
404: /**
405: * Is a flush cycle currently in process?
406: */
407: public boolean isFlushing();
408:
409: /**
410: * Called before and after the flushcycle
411: */
412: public void setFlushing(boolean flushing);
413:
414: /**
415: * Call this before begining a two-phase load
416: */
417: public void beforeLoad();
418:
419: /**
420: * Call this after finishing a two-phase load
421: */
422: public void afterLoad();
423:
424: /**
425: * Returns a string representation of the object.
426: *
427: * @return a string representation of the object.
428: */
429: public String toString();
430:
431: /**
432: * Search the persistence context for an owner for the child object,
433: * given a collection role
434: */
435: public Serializable getOwnerId(String entity, String property,
436: Object childObject, Map mergeMap);
437:
438: /**
439: * Search the persistence context for an index of the child object,
440: * given a collection role
441: */
442: public Object getIndexInOwner(String entity, String property,
443: Object childObject, Map mergeMap);
444:
445: /**
446: * Record the fact that the association belonging to the keyed
447: * entity is null.
448: */
449: public void addNullProperty(EntityKey ownerKey, String propertyName);
450:
451: /**
452: * Is the association property belonging to the keyed entity null?
453: */
454: public boolean isPropertyNull(EntityKey ownerKey,
455: String propertyName);
456:
457: /**
458: * Set the object to read only and discard it's snapshot
459: */
460: public void setReadOnly(Object entity, boolean readOnly);
461:
462: void replaceDelayedEntityIdentityInsertKeys(EntityKey oldKey,
463: Serializable generatedId);
464: }
|