001: //$Id: PersistentCollection.java 10086 2006-07-05 18:17:27Z steve.ebersole@jboss.com $
002: package org.hibernate.collection;
003:
004: import java.io.Serializable;
005: import java.sql.ResultSet;
006: import java.sql.SQLException;
007: import java.util.Collection;
008: import java.util.Iterator;
009:
010: import org.hibernate.HibernateException;
011: import org.hibernate.engine.SessionImplementor;
012: import org.hibernate.loader.CollectionAliases;
013: import org.hibernate.persister.collection.CollectionPersister;
014: import org.hibernate.type.Type;
015:
016: /**
017: * Persistent collections are treated as value objects by Hibernate.
018: * ie. they have no independent existence beyond the object holding
019: * a reference to them. Unlike instances of entity classes, they are
020: * automatically deleted when unreferenced and automatically become
021: * persistent when held by a persistent object. Collections can be
022: * passed between different objects (change "roles") and this might
023: * cause their elements to move from one database table to another.<br>
024: * <br>
025: * Hibernate "wraps" a java collection in an instance of
026: * PersistentCollection. This mechanism is designed to support
027: * tracking of changes to the collection's persistent state and
028: * lazy instantiation of collection elements. The downside is that
029: * only certain abstract collection types are supported and any
030: * extra semantics are lost<br>
031: * <br>
032: * Applications should <em>never</em> use classes in this package
033: * directly, unless extending the "framework" here.<br>
034: * <br>
035: * Changes to <em>structure</em> of the collection are recorded by the
036: * collection calling back to the session. Changes to mutable
037: * elements (ie. composite elements) are discovered by cloning their
038: * state when the collection is initialized and comparing at flush
039: * time.
040: *
041: * @author Gavin King
042: */
043: public interface PersistentCollection {
044:
045: /**
046: * Get the owning entity. Note that the owner is only
047: * set during the flush cycle, and when a new collection
048: * wrapper is created while loading an entity.
049: */
050: public Object getOwner();
051:
052: /**
053: * Set the reference to the owning entity
054: */
055: public void setOwner(Object entity);
056:
057: /**
058: * Is the collection empty? (don't try to initialize the collection)
059: */
060: public boolean empty();
061:
062: /**
063: * After flushing, re-init snapshot state.
064: */
065: public void setSnapshot(Serializable key, String role,
066: Serializable snapshot);
067:
068: /**
069: * After flushing, clear any "queued" additions, since the
070: * database state is now synchronized with the memory state.
071: */
072: public void postAction();
073:
074: /**
075: * return the user-visible collection (or array) instance
076: */
077: public Object getValue();
078:
079: /**
080: * Called just before reading any rows from the JDBC result set
081: */
082: public void beginRead();
083:
084: /**
085: * Called after reading all rows from the JDBC result set
086: */
087: public boolean endRead();
088:
089: /**
090: * Called after initializing from cache
091: */
092: public boolean afterInitialize();
093:
094: /**
095: * Could the application possibly have a direct reference to
096: * the underlying collection implementation?
097: */
098: public boolean isDirectlyAccessible();
099:
100: /**
101: * Disassociate this collection from the given session.
102: * @return true if this was currently associated with the given session
103: */
104: public boolean unsetSession(SessionImplementor currentSession);
105:
106: /**
107: * Associate the collection with the given session.
108: * @return false if the collection was already associated with the session
109: * @throws HibernateException if the collection was already associated
110: * with another open session
111: */
112: public boolean setCurrentSession(SessionImplementor session)
113: throws HibernateException;
114:
115: /**
116: * Read the state of the collection from a disassembled cached value
117: */
118: public void initializeFromCache(CollectionPersister persister,
119: Serializable disassembled, Object owner)
120: throws HibernateException;
121:
122: /**
123: * Iterate all collection entries, during update of the database
124: */
125: public Iterator entries(CollectionPersister persister);
126:
127: /**
128: * Read a row from the JDBC result set
129: */
130: public Object readFrom(ResultSet rs, CollectionPersister role,
131: CollectionAliases descriptor, Object owner)
132: throws HibernateException, SQLException;
133:
134: /**
135: * Get the index of the given collection entry
136: */
137: public Object getIdentifier(Object entry, int i);
138:
139: /**
140: * Get the index of the given collection entry
141: * @param persister it was more elegant before we added this...
142: */
143: public Object getIndex(Object entry, int i,
144: CollectionPersister persister);
145:
146: /**
147: * Get the value of the given collection entry
148: */
149: public Object getElement(Object entry);
150:
151: /**
152: * Get the snapshot value of the given collection entry
153: */
154: public Object getSnapshotElement(Object entry, int i);
155:
156: /**
157: * Called before any elements are read into the collection,
158: * allowing appropriate initializations to occur.
159: *
160: * @param persister The underlying collection persister.
161: * @param anticipatedSize The anticipated size of the collection after initilization is complete.
162: */
163: public void beforeInitialize(CollectionPersister persister,
164: int anticipatedSize);
165:
166: /**
167: * Does the current state exactly match the snapshot?
168: */
169: public boolean equalsSnapshot(CollectionPersister persister)
170: throws HibernateException;
171:
172: /**
173: * Is the snapshot empty?
174: */
175: public boolean isSnapshotEmpty(Serializable snapshot);
176:
177: /**
178: * Disassemble the collection, ready for the cache
179: */
180: public Serializable disassemble(CollectionPersister persister)
181: throws HibernateException;
182:
183: /**
184: * Do we need to completely recreate this collection when it changes?
185: */
186: public boolean needsRecreate(CollectionPersister persister);
187:
188: /**
189: * Return a new snapshot of the current state of the collection
190: */
191: public Serializable getSnapshot(CollectionPersister persister)
192: throws HibernateException;
193:
194: /**
195: * To be called internally by the session, forcing
196: * immediate initialization.
197: */
198: public void forceInitialization() throws HibernateException;
199:
200: /**
201: * Does an element exist at this entry in the collection?
202: */
203: public boolean entryExists(Object entry, int i); //note that i parameter is now unused (delete it?)
204:
205: /**
206: * Do we need to insert this element?
207: */
208: public boolean needsInserting(Object entry, int i, Type elemType)
209: throws HibernateException;
210:
211: /**
212: * Do we need to update this element?
213: */
214: public boolean needsUpdating(Object entry, int i, Type elemType)
215: throws HibernateException;
216:
217: public boolean isRowUpdatePossible();
218:
219: /**
220: * Get all the elements that need deleting
221: */
222: public Iterator getDeletes(CollectionPersister persister,
223: boolean indexIsFormula) throws HibernateException;
224:
225: /**
226: * Is this the wrapper for the given underlying collection instance?
227: */
228: public boolean isWrapper(Object collection);
229:
230: /**
231: * Is this instance initialized?
232: */
233: public boolean wasInitialized();
234:
235: /**
236: * Does this instance have any "queued" additions?
237: */
238: public boolean hasQueuedOperations();
239:
240: /**
241: * Iterate the "queued" additions
242: */
243: public Iterator queuedAdditionIterator();
244:
245: /**
246: * Get the "queued" orphans
247: */
248: public Collection getQueuedOrphans(String entityName);
249:
250: /**
251: * Get the current collection key value
252: */
253: public Serializable getKey();
254:
255: /**
256: * Get the current role name
257: */
258: public String getRole();
259:
260: /**
261: * Is the collection unreferenced?
262: */
263: public boolean isUnreferenced();
264:
265: /**
266: * Is the collection dirty? Note that this is only
267: * reliable during the flush cycle, after the
268: * collection elements are dirty checked against
269: * the snapshot.
270: */
271: public boolean isDirty();
272:
273: /**
274: * Clear the dirty flag, after flushing changes
275: * to the database.
276: */
277: public void clearDirty();
278:
279: /**
280: * Get the snapshot cached by the collection
281: * instance
282: */
283: public Serializable getStoredSnapshot();
284:
285: /**
286: * Mark the collection as dirty
287: */
288: public void dirty();
289:
290: /**
291: * Called before inserting rows, to ensure that any surrogate keys
292: * are fully generated
293: */
294: public void preInsert(CollectionPersister persister)
295: throws HibernateException;
296:
297: /**
298: * Called after inserting a row, to fetch the natively generated id
299: */
300: public void afterRowInsert(CollectionPersister persister,
301: Object entry, int i) throws HibernateException;
302:
303: /**
304: * get all "orphaned" elements
305: */
306: public Collection getOrphans(Serializable snapshot,
307: String entityName) throws HibernateException;
308:
309: }
|