PersistentCollection


1   //$Id: PersistentCollection.java,v 1.26 2005/06/18 14:54:43 oneovthafew Exp $
2   package org.hibernate.collection;
3   
4   import java.io.Serializable  ;
5   import java.sql.ResultSet  ;
6   import java.sql.SQLException  ;
7   import java.util.Collection  ;
8   import java.util.Iterator  ;
9   
10  import org.hibernate.HibernateException;
11  import org.hibernate.engine.SessionImplementor;
12  import org.hibernate.loader.CollectionAliases;
13  import org.hibernate.persister.collection.CollectionPersister;
14  import org.hibernate.type.Type;
15  
16  /**
17   * Persistent collections are treated as value objects by Hibernate.
18   * ie. they have no independent existence beyond the object holding
19   * a reference to them. Unlike instances of entity classes, they are
20   * automatically deleted when unreferenced and automatically become
21   * persistent when held by a persistent object. Collections can be
22   * passed between different objects (change "roles") and this might
23   * cause their elements to move from one database table to another.<br>
24   * <br>
25   * Hibernate "wraps" a java collection in an instance of
26   * PersistentCollection. This mechanism is designed to support
27   * tracking of changes to the collection's persistent state and
28   * lazy instantiation of collection elements. The downside is that
29   * only certain abstract collection types are supported and any
30   * extra semantics are lost<br>
31   * <br>
32   * Applications should <em>never</em> use classes in this package
33   * directly, unless extending the "framework" here.<br>
34   * <br>
35   * Changes to <em>structure</em> of the collection are recorded by the
36   * collection calling back to the session. Changes to mutable
37   * elements (ie. composite elements) are discovered by cloning their
38   * state when the collection is initialized and comparing at flush
39   * time.
40   *
41   * @author Gavin King
42   */
43  public interface PersistentCollection {
44      
45      /**
46       * Get the owning entity. Note that the owner is only
47       * set during the flush cycle, and when a new collection
48       * wrapper is created while loading an entity.
49       */
50      public Object   getOwner();
51      /**
52       * Set the reference to the owning entity
53       */
54      public void setOwner(Object   entity);
55      
56      /**
57       * Is the collection empty? (don't try to initialize the collection)
58       */
59      public boolean empty();
60  
61      /**
62       * After flushing, re-init snapshot state.
63       */
64      public void setSnapshot(Serializable   key, String   role, Serializable   snapshot);
65      
66      /**
67       * After flushing, clear any "queued" additions, since the
68       * database state is now synchronized with the memory state.
69       */
70      public void postAction();
71      
72      /**
73       * return the user-visible collection (or array) instance
74       */
75      public Object   getValue();
76  
77      /**
78       * Called just before reading any rows from the JDBC result set
79       */
80      public void beginRead();
81  
82      /**
83       * Called after reading all rows from the JDBC result set
84       */
85      public boolean endRead();
86      
87      /**
88       * Called after initializing from cache
89       */
90      public boolean afterInitialize();
91  
92      /**
93       * Could the application possibly have a direct reference to
94       * the underlying collection implementation?
95       */
96      public boolean isDirectlyAccessible();
97  
98      /**
99       * Disassociate this collection from the given session.
100      * @return true if this was currently associated with the given session
101      */
102     public boolean unsetSession(SessionImplementor currentSession);
103 
104     /**
105      * Associate the collection with the given session.
106      * @return false if the collection was already associated with the session
107      * @throws HibernateException if the collection was already associated
108      * with another open session
109      */
110     public boolean setCurrentSession(SessionImplementor session)
111             throws HibernateException;
112 
113     /**
114      * Read the state of the collection from a disassembled cached value
115      */
116     public void initializeFromCache(CollectionPersister persister,
117             Serializable   disassembled, Object   owner) throws HibernateException;
118 
119     /**
120      * Iterate all collection entries, during update of the database
121      */
122     public Iterator   entries(CollectionPersister persister);
123 
124     /**
125      * Read a row from the JDBC result set
126      */
127     public Object   readFrom(ResultSet   rs, CollectionPersister role, CollectionAliases descriptor, Object   owner)
128             throws HibernateException, SQLException  ;
129 
130     /**
131      * Get the index of the given collection entry
132      */
133     public Object   getIdentifier(Object   entry, int i);
134     
135     /**
136      * Get the index of the given collection entry
137      * @param persister it was more elegant before we added this...
138      */
139     public Object   getIndex(Object   entry, int i, CollectionPersister persister);
140     
141     /**
142      * Get the value of the given collection entry
143      */
144     public Object   getElement(Object   entry);
145     
146     /**
147      * Get the snapshot value of the given collection entry
148      */
149     public Object   getSnapshotElement(Object   entry, int i);
150 
151     /**
152      * Called before any elements are read into the collection,
153      * allowing appropriate initializations to occur.
154      */
155     public void beforeInitialize(CollectionPersister persister);
156 
157     /**
158      * Does the current state exactly match the snapshot?
159      */
160     public boolean equalsSnapshot(CollectionPersister persister) 
161         throws HibernateException;
162 
163     /**
164      * Is the snapshot empty?
165      */
166     public boolean isSnapshotEmpty(Serializable   snapshot);
167     
168     /**
169      * Disassemble the collection, ready for the cache
170      */
171     public Serializable   disassemble(CollectionPersister persister)
172     throws HibernateException;
173 
174     /**
175      * Do we need to completely recreate this collection when it changes?
176      */
177     public boolean needsRecreate(CollectionPersister persister);
178 
179     /**
180      * Return a new snapshot of the current state of the collection
181      */
182     public Serializable   getSnapshot(CollectionPersister persister)
183             throws HibernateException;
184 
185     /**
186      * To be called internally by the session, forcing
187      * immediate initialization.
188      */
189     public void forceInitialization() throws HibernateException;
190 
191     /**
192      * Does an element exist at this entry in the collection?
193      */
194     public boolean entryExists(Object   entry, int i); //note that i parameter is now unused (delete it?)
195 
196     /**
197      * Do we need to insert this element?
198      */
199     public boolean needsInserting(Object   entry, int i, Type elemType)
200             throws HibernateException;
201 
202     /**
203      * Do we need to update this element?
204      */
205     public boolean needsUpdating(Object   entry, int i, Type elemType)
206             throws HibernateException;
207     
208     public boolean isRowUpdatePossible();
209 
210     /**
211      * Get all the elements that need deleting
212      */
213     public Iterator   getDeletes(CollectionPersister persister, boolean indexIsFormula) 
214             throws HibernateException;
215 
216     /**
217      * Is this the wrapper for the given underlying collection instance?
218      */
219     public boolean isWrapper(Object   collection);
220 
221     /**
222      * Is this instance initialized?
223      */
224     public boolean wasInitialized();
225 
226     /**
227      * Does this instance have any "queued" additions?
228      */
229     public boolean hasQueuedAdditions();
230 
231     /**
232      * Iterate the "queued" additions
233      */
234     public Iterator   queuedAdditionIterator();
235     
236     /**
237      * Get the current collection key value
238      */
239     public Serializable   getKey();
240     
241     /**
242      * Get the current role name
243      */
244     public String   getRole();
245     
246     /**
247      * Is the collection unreferenced?
248      */
249     public boolean isUnreferenced();
250     
251     /**
252      * Is the collection dirty? Note that this is only
253      * reliable during the flush cycle, after the 
254      * collection elements are dirty checked against
255      * the snapshot.
256      */
257     public boolean isDirty();
258     
259     /**
260      * Clear the dirty flag, after flushing changes
261      * to the database.
262      */
263     public void clearDirty();
264     
265     /**
266      * Get the snapshot cached by the collection
267      * instance
268      */
269     public Serializable   getStoredSnapshot();
270     
271     /**
272      * Mark the collection as dirty
273      */
274     public void dirty();
275     
276     /**
277      * Called before inserting rows, to ensure that any surrogate keys
278      * are fully generated
279      */
280     public void preInsert(CollectionPersister persister)
281     throws HibernateException;
282 
283     /**
284      * Called after inserting a row, to fetch the natively generated id
285      */
286     public void afterRowInsert(CollectionPersister persister, Object   entry, int i) 
287     throws HibernateException;
288 
289     /**
290      * get all "orphaned" elements
291      */
292     public Collection   getOrphans(Serializable   snapshot, String   entityName)
293     throws HibernateException;
294     
295 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags