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