/*
   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.
  *
  *
  */