Coverage Report

Coverage Report - net.wotonomy.control.EOObjectStore

Classes in this File

 /*
 Wotonomy: OpenStep design patterns for pure Java applications.
 Copyright (C) 2000 Michael Powers
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.
 
 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, see http://www.gnu.org
 */
 
 package net.wotonomy.control;
 
 import java.util.List;
 import java.util.Map;
 
 import net.wotonomy.foundation.NSArray;
 
 /**
 * EOObjectStore defines an object repository that tracks
 * object creations, deletions, and updates made by 
 * EOEditingContexts. <br><br>
 *
 * A concrete implementation would probably write these 
 * changes to some kind of persistent storage, like a
 * database. <br><br>
 *
 * EOEditingContext is itself a subclass of EOObjectStore
 * that requires an EOObjectStore parent for committing
 * its changes.  This means that EOEditingContexts can
 * use other EOEditingContexts as their parent, but there
 * still must exist an EOObjectStore as the root of the 
 * editing graph.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 894 $
 */
 public abstract class EOObjectStore
 {
     /**
     * Key for the user info of ObjectsChangedInStoreNotifications.
     * The key should retrieve an array of deleted EOGlobalIDs.
     */
     public static final String DeletedKey = "deleted";
 
     /**
     * Key for the user info of ObjectsChangedInStoreNotifications.
     * The key should retrieve an array of inserted EOGlobalIDs.
     */
     public static final String InsertedKey = "inserted";
 
     /**
     * Key for the user info of ObjectsChangedInStoreNotifications.
     * The key should retrieve an array of updated EOGlobalIDs.
     * EOEditingContexts should refault their copies of these objects.
     */
     public static final String UpdatedKey = "updated";
 
     /**
     * Key for the user info of ObjectsChangedInStoreNotification.
     * The key should retrieve an array of EOGlobalIDs.
     */
     public static final String InvalidatedKey = "invalidated";
 
     /**
     * Key for the NSNotification posted when this object store
     * is asked to invalidate all objects.  Object of the notification
     * will be this object store, and user info will contain the
     * InvalidatedKey.
     */
     public static final String 
         InvalidatedAllObjectsInStoreNotification = 
         "EOInvalidatedAllObjectsInStoreNotification";
 
     /**
     * Key for the NSNotification posted when this object store
     * is changed.  Object of the notification will be this object 
     * store, and user info will contain InsertedKey, UpdatedKey,
     * DeletedKey, and InvalidatedKey.
     */
     public static final String  
         ObjectsChangedInStoreNotification = 
         "EOObjectsChangedInStoreNotification";
  
     /**
     * Default constructor is responsible for initializing
     * internal state.
     */ 
         public EOObjectStore ()
     {
     }
 
     /**
     * Called by editing contexts when they no longer
     * need to track the specified id.  You will not need
     * to call this method, but you use use it for a hint
     * that the specified global id is not in use by that
     * child editing context.
     */
     public void editingContextDidForgetObjectWithGlobalID ( 
         EOEditingContext aContext,
         EOGlobalID aGlobalID )
     {
     }   
         
     /**
     * Returns a List of objects associated with the object 
     * with the specified id for the specified property 
     * relationship, or may return a placeholder array that
     * will defer the fetch until accessed (an array fault).
     * All objects must be registered the specified editing context.
     * The specified relationship key must produce a result of
     * type Collection for the source object or an exception is thrown.
     */
     public abstract NSArray arrayFaultWithSourceGlobalID ( 
         EOGlobalID aGlobalID,
         String aRelationship,
         EOEditingContext aContext );
      
     /**
     * Returns the object for the specified id.
     * The returned object may be a fault.
     * The object will be registered in the
     * specified editing context.
     */
     public abstract /*EOEnterpriseObject*/ Object faultForGlobalID ( 
         EOGlobalID aGlobalID,
         EOEditingContext aContext );
         
     /**
     * Returns a fault representing an object of 
     * the specified entity type with values from 
     * the specified dictionary.  The fault should
     * belong to the specified editing context.
     */        
     public abstract /*EOEnterpriseObject*/ Object faultForRawRow ( 
         Map aDictionary,
         String anEntityName,
         EOEditingContext aContext );
         
     /**
     * Given a newly instantiated object, this method 
     * initializes its properties to values appropriate
     * for the specified id.  The object should already
     * belong to the specified editing context.  
     * This method is called to populate faults.
     */        
     public abstract void initializeObject ( 
         /*EOEnterpriseObject*/ Object eo,
         EOGlobalID aGlobalID,
         EOEditingContext aContext );
         
     /**
     * Remove all values from all objects in memory,
     * turning them into faults, and posts an NSNotification
     * that all objects have been invalidated.
     * The notification should be named with the string
     * constant InvalidatedAllObjectsInStoreNotification
     * with this object store as the object and no user info.
     */
     public abstract void invalidateAllObjects ();
     
     /**
     * Removes values with the specified ids from memory,
     * turning them into faults, and posts a notification
     * that those objects have been invalidated.
     * The notification should be named with the string
     * constant ObjectsChangedInStoreNotification
     * with this object store as the object and user info
     * containing a key named InvalidateKey that returns
     * a List of the EOGlobalIDs of the invalidated objects.
     */
     public abstract void invalidateObjectsWithGlobalIDs ( 
         List aList );
         
     /**
     * Returns whether the object corresponding to the
     * specified id is locked.  The concept of object
     * locking is implementation-specific.
     */
     public abstract boolean isObjectLockedWithGlobalID ( 
         EOGlobalID aGlobalID,
         EOEditingContext aContext );
         
     /**
     * Locks the object corresponding to the
     * specified id is locked.  The concept of object
     * locking is implementation-specific.
     * The lock may be released when objects are
     * invalidated or commited, but this behavior
     * is not required.
     */
     public abstract void lockObjectWithGlobalID ( 
         EOGlobalID aGlobalID,
         EOEditingContext aContext );
         
     /**
     * Returns a List of objects associated with the object 
     * with the specified id for the specified property 
     * relationship.  This method may not return an array fault
     * because array faults call this method to fetch on demand.
     * All objects must be registered the specified editing context.
     * The specified relationship key must produce a result of
     * type Collection for the source object or an exception is thrown.
     */
     public abstract NSArray objectsForSourceGlobalID ( 
         EOGlobalID aGlobalID,
         String aRelationship,
         EOEditingContext aContext );
         
     /**
     * Returns a List of objects the meet the criteria of
     * the supplied specification.  Faults are not allowed in the array.
     * Each object is registered with the specified editing context.
     * If any object is already fetched in the specified context, 
     * it is not refetched and that object should be used in the array.
     */
     public abstract NSArray objectsWithFetchSpecification ( 
         EOFetchSpecification aFetchSpec,
         EOEditingContext aContext );
         
     /**
     * Removes all values from the specified object, 
     * converting it into a fault for the specified id.
     * New or deleted objects should not be refaulted.
     */
     public abstract void refaultObject ( 
         Object anObject,
         EOGlobalID aGlobalID,
         EOEditingContext aContext );
         
     /**
     * Writes all changes in the specified editing context
     * to the respository.  The object store is expected to
     * post a notification that should be named with the string
     * constant ObjectsChangedInStoreNotification
     * with this object store as the object and user info
     * containing keys named UpdatedKey, InsertedKey, and 
     * DeletedKey that return Lists of the EOGlobalIDs of the 
     * corresponding objects.
     */
     public abstract void saveChangesInEditingContext ( 
         EOEditingContext aContext ); 
 }
 
 /*
  * $Log$
  * Revision 1.2  2006/02/16 16:47:14  cgruber
  * Move some classes in to "internal" packages and re-work imports, etc.
  *
  * Also use UnsupportedOperationExceptions where appropriate, instead of WotonomyExceptions.
  *
  * Revision 1.1  2006/02/16 13:19:57  cgruber
  * Check in all sources in eclipse-friendly maven-enabled packages.
  *
  * Revision 1.15  2003/12/18 15:37:38  mpowers
  * Changes to retain ability to work with objects that don't necessarily
  * implement EOEnterpriseObject.  I would still like to preserve this case
  * for general usage, however the access package is free to assume that
  * those objects will be EOs and cast appropriately.
  *
  * Revision 1.14  2003/08/19 01:53:12  chochos
  * EOObjectStore had some incompatible return types (Object instead of EOEnterpriseObject, in fault methods mostly). It's internally consistent but I hope it doesn't break anything based on this, even though fault methods mostly throw exceptions for now.
  *
  * Revision 1.13  2002/02/13 21:20:15  mpowers
  * Updated comments.
  *
  * Revision 1.12  2001/05/05 23:05:42  mpowers
  * Implemented Array Faults.
  *
  * Revision 1.11  2001/02/21 21:17:32  mpowers
  * Now retaining a reference to the recent changes observer.
  * Better documented need to retain reference.
  * Started implementing notifications.
  *
  * Revision 1.10  2001/02/16 22:51:29  mpowers
  * Now deep-cloning objects passed between editing contexts.
  *
  * Revision 1.9  2001/02/16 18:34:19  mpowers
  * Implementing nested contexts.
  *
  * Revision 1.8  2001/02/15 21:13:30  mpowers
  * First draft implementation is complete.  Now on to debugging.
  *
  * Revision 1.7  2001/02/14 23:03:02  mpowers
  * A near-complete first draft of EOEditingContext.
  *
  * Revision 1.6  2001/02/13 23:24:29  mpowers
  * Implementing more of editing context.
  *
  * Revision 1.5  2001/02/12 20:36:36  mpowers
  * Documented methods.
  *
  * Revision 1.4  2001/02/09 22:09:34  mpowers
  * Completed implementation of EOObjectStore.
  *
  * Revision 1.3  2001/02/06 15:24:11  mpowers
  * Widened parameters on abstract method to fix build.
  *
  * Revision 1.2  2001/02/06 14:57:42  mpowers
  * Defined abstract methods.
  *
  * Revision 1.1.1.1  2000/12/21 15:46:42  mpowers
  * Contributing wotonomy.
  *
  * Revision 1.2  2000/12/20 16:25:35  michael
  * Added log to all files.
  *
  *
  */
     
 

1		/*
2		Wotonomy: OpenStep design patterns for pure Java applications.
3		Copyright (C) 2000 Michael Powers
4
5		This library is free software; you can redistribute it and/or
6		modify it under the terms of the GNU Lesser General Public
7		License as published by the Free Software Foundation; either
8		version 2.1 of the License, or (at your option) any later version.
9
10		This library is distributed in the hope that it will be useful,
11		but WITHOUT ANY WARRANTY; without even the implied warranty of
12		MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13		Lesser General Public License for more details.
14
15		You should have received a copy of the GNU Lesser General Public
16		License along with this library; if not, see http://www.gnu.org
17		*/
18
19		package net.wotonomy.control;
20
21		import java.util.List;
22		import java.util.Map;
23
24		import net.wotonomy.foundation.NSArray;
25
26		/**
27		* EOObjectStore defines an object repository that tracks
28		* object creations, deletions, and updates made by
29		* EOEditingContexts. <br><br>
30		*
31		* A concrete implementation would probably write these
32		* changes to some kind of persistent storage, like a
33		* database. <br><br>
34		*
35		* EOEditingContext is itself a subclass of EOObjectStore
36		* that requires an EOObjectStore parent for committing
37		* its changes. This means that EOEditingContexts can
38		* use other EOEditingContexts as their parent, but there
39		* still must exist an EOObjectStore as the root of the
40		* editing graph.
41		*
42		* @author michael@mpowers.net
43		* @author $Author: cgruber $
44		* @version $Revision: 894 $
45		*/
46		public abstract class EOObjectStore
47		{
48		/**
49		* Key for the user info of ObjectsChangedInStoreNotifications.
50		* The key should retrieve an array of deleted EOGlobalIDs.
51		*/
52		public static final String DeletedKey = "deleted";
53
54		/**
55		* Key for the user info of ObjectsChangedInStoreNotifications.
56		* The key should retrieve an array of inserted EOGlobalIDs.
57		*/
58		public static final String InsertedKey = "inserted";
59
60		/**
61		* Key for the user info of ObjectsChangedInStoreNotifications.
62		* The key should retrieve an array of updated EOGlobalIDs.
63		* EOEditingContexts should refault their copies of these objects.
64		*/
65		public static final String UpdatedKey = "updated";
66
67		/**
68		* Key for the user info of ObjectsChangedInStoreNotification.
69		* The key should retrieve an array of EOGlobalIDs.
70		*/
71		public static final String InvalidatedKey = "invalidated";
72
73		/**
74		* Key for the NSNotification posted when this object store
75		* is asked to invalidate all objects. Object of the notification
76		* will be this object store, and user info will contain the
77		* InvalidatedKey.
78		*/
79		public static final String
80		InvalidatedAllObjectsInStoreNotification =
81		"EOInvalidatedAllObjectsInStoreNotification";
82
83		/**
84		* Key for the NSNotification posted when this object store
85		* is changed. Object of the notification will be this object
86		* store, and user info will contain InsertedKey, UpdatedKey,
87		* DeletedKey, and InvalidatedKey.
88		*/
89		public static final String
90		ObjectsChangedInStoreNotification =
91		"EOObjectsChangedInStoreNotification";
92
93		/**
94		* Default constructor is responsible for initializing
95		* internal state.
96		*/
97	0	public EOObjectStore ()
98	0	{
99	0	}
100
101		/**
102		* Called by editing contexts when they no longer
103		* need to track the specified id. You will not need
104		* to call this method, but you use use it for a hint
105		* that the specified global id is not in use by that
106		* child editing context.
107		*/
108		public void editingContextDidForgetObjectWithGlobalID (
109		EOEditingContext aContext,
110		EOGlobalID aGlobalID )
111		{
112	0	}
113
114		/**
115		* Returns a List of objects associated with the object
116		* with the specified id for the specified property
117		* relationship, or may return a placeholder array that
118		* will defer the fetch until accessed (an array fault).
119		* All objects must be registered the specified editing context.
120		* The specified relationship key must produce a result of
121		* type Collection for the source object or an exception is thrown.
122		*/
123		public abstract NSArray arrayFaultWithSourceGlobalID (
124		EOGlobalID aGlobalID,
125		String aRelationship,
126		EOEditingContext aContext );
127
128		/**
129		* Returns the object for the specified id.
130		* The returned object may be a fault.
131		* The object will be registered in the
132		* specified editing context.
133		*/
134		public abstract /EOEnterpriseObject/ Object faultForGlobalID (
135		EOGlobalID aGlobalID,
136		EOEditingContext aContext );
137
138		/**
139		* Returns a fault representing an object of
140		* the specified entity type with values from
141		* the specified dictionary. The fault should
142		* belong to the specified editing context.
143		*/
144		public abstract /EOEnterpriseObject/ Object faultForRawRow (
145		Map aDictionary,
146		String anEntityName,
147		EOEditingContext aContext );
148
149		/**
150		* Given a newly instantiated object, this method
151		* initializes its properties to values appropriate
152		* for the specified id. The object should already
153		* belong to the specified editing context.
154		* This method is called to populate faults.
155		*/
156		public abstract void initializeObject (
157		/EOEnterpriseObject/ Object eo,
158		EOGlobalID aGlobalID,
159		EOEditingContext aContext );
160
161		/**
162		* Remove all values from all objects in memory,
163		* turning them into faults, and posts an NSNotification
164		* that all objects have been invalidated.
165		* The notification should be named with the string
166		* constant InvalidatedAllObjectsInStoreNotification
167		* with this object store as the object and no user info.
168		*/
169		public abstract void invalidateAllObjects ();
170
171		/**
172		* Removes values with the specified ids from memory,
173		* turning them into faults, and posts a notification
174		* that those objects have been invalidated.
175		* The notification should be named with the string
176		* constant ObjectsChangedInStoreNotification
177		* with this object store as the object and user info
178		* containing a key named InvalidateKey that returns
179		* a List of the EOGlobalIDs of the invalidated objects.
180		*/
181		public abstract void invalidateObjectsWithGlobalIDs (
182		List aList );
183
184		/**
185		* Returns whether the object corresponding to the
186		* specified id is locked. The concept of object
187		* locking is implementation-specific.
188		*/
189		public abstract boolean isObjectLockedWithGlobalID (
190		EOGlobalID aGlobalID,
191		EOEditingContext aContext );
192
193		/**
194		* Locks the object corresponding to the
195		* specified id is locked. The concept of object
196		* locking is implementation-specific.
197		* The lock may be released when objects are
198		* invalidated or commited, but this behavior
199		* is not required.
200		*/
201		public abstract void lockObjectWithGlobalID (
202		EOGlobalID aGlobalID,
203		EOEditingContext aContext );
204
205		/**
206		* Returns a List of objects associated with the object
207		* with the specified id for the specified property
208		* relationship. This method may not return an array fault
209		* because array faults call this method to fetch on demand.
210		* All objects must be registered the specified editing context.
211		* The specified relationship key must produce a result of
212		* type Collection for the source object or an exception is thrown.
213		*/
214		public abstract NSArray objectsForSourceGlobalID (
215		EOGlobalID aGlobalID,
216		String aRelationship,
217		EOEditingContext aContext );
218
219		/**
220		* Returns a List of objects the meet the criteria of
221		* the supplied specification. Faults are not allowed in the array.
222		* Each object is registered with the specified editing context.
223		* If any object is already fetched in the specified context,
224		* it is not refetched and that object should be used in the array.
225		*/
226		public abstract NSArray objectsWithFetchSpecification (
227		EOFetchSpecification aFetchSpec,
228		EOEditingContext aContext );
229
230		/**
231		* Removes all values from the specified object,
232		* converting it into a fault for the specified id.
233		* New or deleted objects should not be refaulted.
234		*/
235		public abstract void refaultObject (
236		Object anObject,
237		EOGlobalID aGlobalID,
238		EOEditingContext aContext );
239
240		/**
241		* Writes all changes in the specified editing context
242		* to the respository. The object store is expected to
243		* post a notification that should be named with the string
244		* constant ObjectsChangedInStoreNotification
245		* with this object store as the object and user info
246		* containing keys named UpdatedKey, InsertedKey, and
247		* DeletedKey that return Lists of the EOGlobalIDs of the
248		* corresponding objects.
249		*/
250		public abstract void saveChangesInEditingContext (
251		EOEditingContext aContext );
252		}
253
254		/*
255		* $Log$
256		* Revision 1.2 2006/02/16 16:47:14 cgruber
257		* Move some classes in to "internal" packages and re-work imports, etc.
258		*
259		* Also use UnsupportedOperationExceptions where appropriate, instead of WotonomyExceptions.
260		*
261		* Revision 1.1 2006/02/16 13:19:57 cgruber
262		* Check in all sources in eclipse-friendly maven-enabled packages.
263		*
264		* Revision 1.15 2003/12/18 15:37:38 mpowers
265		* Changes to retain ability to work with objects that don't necessarily
266		* implement EOEnterpriseObject. I would still like to preserve this case
267		* for general usage, however the access package is free to assume that
268		* those objects will be EOs and cast appropriately.
269		*
270		* Revision 1.14 2003/08/19 01:53:12 chochos
271		* EOObjectStore had some incompatible return types (Object instead of EOEnterpriseObject, in fault methods mostly). It's internally consistent but I hope it doesn't break anything based on this, even though fault methods mostly throw exceptions for now.
272		*
273		* Revision 1.13 2002/02/13 21:20:15 mpowers
274		* Updated comments.
275		*
276		* Revision 1.12 2001/05/05 23:05:42 mpowers
277		* Implemented Array Faults.
278		*
279		* Revision 1.11 2001/02/21 21:17:32 mpowers
280		* Now retaining a reference to the recent changes observer.
281		* Better documented need to retain reference.
282		* Started implementing notifications.
283		*
284		* Revision 1.10 2001/02/16 22:51:29 mpowers
285		* Now deep-cloning objects passed between editing contexts.
286		*
287		* Revision 1.9 2001/02/16 18:34:19 mpowers
288		* Implementing nested contexts.
289		*
290		* Revision 1.8 2001/02/15 21:13:30 mpowers
291		* First draft implementation is complete. Now on to debugging.
292		*
293		* Revision 1.7 2001/02/14 23:03:02 mpowers
294		* A near-complete first draft of EOEditingContext.
295		*
296		* Revision 1.6 2001/02/13 23:24:29 mpowers
297		* Implementing more of editing context.
298		*
299		* Revision 1.5 2001/02/12 20:36:36 mpowers
300		* Documented methods.
301		*
302		* Revision 1.4 2001/02/09 22:09:34 mpowers
303		* Completed implementation of EOObjectStore.
304		*
305		* Revision 1.3 2001/02/06 15:24:11 mpowers
306		* Widened parameters on abstract method to fix build.
307		*
308		* Revision 1.2 2001/02/06 14:57:42 mpowers
309		* Defined abstract methods.
310		*
311		* Revision 1.1.1.1 2000/12/21 15:46:42 mpowers
312		* Contributing wotonomy.
313		*
314		* Revision 1.2 2000/12/20 16:25:35 michael
315		* Added log to all files.
316		*
317		*
318		*/
319
320