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