/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2001 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 net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSDictionary;

/**
 * EOEnterpriseObject defines the required methods a data object must implement
 * to take full advantage of the control package.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 894 $
 */
public interface EOEnterpriseObject
		extends EOKeyValueCodingAdditions, EORelationshipManipulation, EODeferredFaulting, EOValidation {
	/**
	 * Returns a List of all property keys defined on this object. This includes
	 * both attributes and relationships.
	 */
	NSArray allPropertyKeys();

	/**
	 * Returns a list of all attributes defined on this object. Attributes are all
	 * properties that are not relationships.
	 */
	NSArray attributeKeys();

	// void awakeFromClientUpdate(EOEditingContext aContext)

	/**
	 * Called when the object has first been fetched into the specified editing
	 * context.
	 */
	void awakeFromFetch(EOEditingContext anEditingContext);

	/**
	 * Called when the object has been inserted into the specified editing context.
	 */
	void awakeFromInsertion(EOEditingContext anEditingContext);

	/**
	 * Returns a Map representing the delta of the current state from the state
	 * represented in the specified snapshot. The result will contain only the keys
	 * that have changed and their values. Relationship keys will map to an NSArray
	 * that contains an NSArray of added objects and an NSArray of removed objects,
	 * in that order.
	 */
	NSDictionary changesFromSnapshot(NSDictionary snapshot);

	/**
	 * Returns a class description for this object.
	 */
	EOClassDescription classDescription();

	/**
	 * Returns a class description for the object at the other end of the specified
	 * relationship key.
	 */
	EOClassDescription classDescriptionForDestinationKey(String aKey);

	/**
	 * Clears all property values for this object. This method is called to clean-up
	 * an object that will no longer be used, and implementations should ensure that
	 * all references are set to null to prevent problems with garbage-collection.
	 */
	void clearProperties();

	/**
	 * Returns the delete rule constant defined on EOClassDescription for the
	 * relationship defined by the specified key.
	 */
	int deleteRuleForRelationshipKey(String aRelationshipKey);

	/**
	 * Returns the editing context in which this object is registered.
	 */
	EOEditingContext editingContext();

	/**
	 * Returns the name of the entity that this object represents.
	 */
	String entityName();

	/**
	 * Returns a String containing all property keys and values for this object.
	 * Relationships should be represented by calling eoShallowDescription() on the
	 * object.
	 */
	String eoDescription();

	/**
	 * Returns a String containing all attribute keys and values for this object.
	 * Relationships are not included.
	 */
	String eoShallowDescription();

	/**
	 * Returns the key used to reference this object on the object at the other end
	 * of the specified relationship.
	 */
	String inverseForRelationshipKey(String aRelationshipKey);

	// Object invokeRemoteMethod(
	// String aMethodName, Class[] aTypeArray Object[] anArgumentArray)

	/**
	 * Returns whether the specified relationship key represents a to-many
	 * relationship.
	 */
	boolean isToManyKey(String aKey);

	/**
	 * Returns whether the objects at the other end of the specified relationship
	 * should be deleted when this object is deleted.
	 */
	boolean ownsDestinationObjectsForRelationshipKey(String aKey);

	// void prepareValuesForClient()

	/**
	 * Called to perform the delete propagation for this object on the specified
	 * editing context. All relationships should be processed according to their
	 * corresponding delete rule.
	 */
	void propagateDeleteWithEditingContext(EOEditingContext aContext);

	/**
	 * Applies the changes from the specified snapshot to this object.
	 * 
	 * @see #changesFromSnapshot(NSDictionary)
	 */
	void reapplyChangesFromDictionary(NSDictionary aDeltaSnapshot);

	/**
	 * Returns a snapshot of the current state of this object. All property keys are
	 * mapped to their values; nulls are represented by NSNull.
	 */
	NSDictionary snapshot();

	/**
	 * Returns a List of the to-many relationship keys for this object.
	 */
	NSArray toManyRelationshipKeys();

	/**
	 * Returns a List of the to-one relationship keys for this object.
	 */
	NSArray toOneRelationshipKeys();

	/**
	 * Applies the specified snapshot to this object, converting NSNulls to null and
	 * calling takeStoredValueForKey for each key in the Map.
	 */
	void updateFromSnapshot(NSDictionary aSnapshot);

	/**
	 * Returns a short, stateful string representation of this object.
	 */
	String userPresentableDescription();

	/**
	 * This method should be implemented to call EOObserverCenter.objectWillChange(
	 * this ), and it should be called by each setter method on this object before
	 * changes are made to the object's internal state.
	 */
	void willChange();
}

/*
 * $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.1 2001/11/13 04:13:59 mpowers Added interfaces needed to begin
 * work on EOCustomObject.
 *
 *
 */