Formatting pass

1 files changed, 201 insertions, 264 deletions

diff --git a/projects/net.wotonomy.persistence/src/main/java/net/wotonomy/control/EOObjectStore.java b/projects/net.wotonomy.persistence/src/main/java/net/wotonomy/control/EOObjectStore.java
index cd18e36..4f60045 100644
--- a/projects/net.wotonomy.persistence/src/main/java/net/wotonomy/control/EOObjectStore.java
+++ b/projects/net.wotonomy.persistence/src/main/java/net/wotonomy/control/EOObjectStore.java
@@ -24,297 +24,234 @@ 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";
+ * 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";
 
-    /**
-    * Key for the user info of ObjectsChangedInStoreNotifications.
-    * The key should retrieve an array of inserted EOGlobalIDs.
-    */
-    public static final String InsertedKey = "inserted";
+	/**
+	 * Default constructor is responsible for initializing internal state.
+	 */
+	public EOObjectStore() {
+	}
 
-    /**
-    * 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";
+	/**
+	 * 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) {
+	}
 
-    /**
-    * Key for the user info of ObjectsChangedInStoreNotification.
-    * The key should retrieve an array of EOGlobalIDs.
-    */
-    public static final String InvalidatedKey = "invalidated";
+	/**
+	 * 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);
 
-    /**
-    * 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";
+	/**
+	 * 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);
 
-    /**
-    * 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 ()
-    {
-    }
+	/**
+	 * 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);
 
-    /**
-    * 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 ); 
+	/**
+	 * 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.
+ * $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.
+ * 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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.
+ * Revision 1.2 2000/12/20 16:25:35 michael Added log to all files.
  *
  *
  */
-    
-