/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2001 Intersect Software Corporation

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.Collection;
import java.util.List;
import java.util.Map;

import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSDictionary;
import net.wotonomy.foundation.NSSet;
import net.wotonomy.foundation.internal.WotonomyException;

/**
 * EOCustomObject implements all the necessary interfaces to receive first-class
 * treatment from the control framework. The implementation delegates as much
 * class meta-behavior as possible to EOClassDescription, letting subclasses
 * focus exclusively on business logic while still allowing them to customize as
 * much class behavior as needed.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 894 $
 */
public class EOCustomObject implements EOEnterpriseObject, EOKeyValueCodingAdditions, EODeferredFaulting,
		EORelationshipManipulation, EOValidation {
	private transient static EOClassDescription classDescription;
	private transient EOEditingContext editingContext;

	// static configuration

	/**
	 * Specifies whether the implementation of EOKeyValueCoding is permitted to
	 * access field directly. This implementation returns true; subclasses may
	 * override to customize this behavior.
	 */
	public static boolean canAccessFieldsDirectly() {
		return true;
	}

	/**
	 * Specifies whether the implementation of EOKeyValueCoding is permitted to
	 * access private accessors. This implementation returns true; subclasses may
	 * override to customize this behavior.
	 */
	public static boolean shouldUseStoredAccessors() {
		return true;
	}

	/**
	 * Specifies whether deferred faults should be used. This implementation returns
	 * false; subclasses may override to customize this behavior.
	 */
	public static boolean usesDeferredFaultCreation() {
		return false;
	}

	// constructors

	/**
	 * Default constructor initializes private state. EditingContext and
	 * ClassDescription are set to null.
	 */
	public EOCustomObject() {
		editingContext = null;
		classDescription = null;
	}

	/**
	 * Preferred constructor, specifying an editing context, a class description,
	 * and a global id, any or all of which may be null. Subclasses should invoke
	 * this constructor.
	 */
	public EOCustomObject(EOEditingContext aContext, EOClassDescription aClassDescription, EOGlobalID aGlobalID) {
		editingContext = aContext;
		classDescription = aClassDescription;
	}

	// interface EOEnterpriseObject

	/**
	 * Returns a List of all property keys defined on this object. This includes
	 * both attributes and relationships. This implementation returns the union of
	 * attributeKeys, toOneRelationshipKeys, and toManyRelationshipKeys.
	 */
	public NSArray allPropertyKeys() {
		NSSet union = new NSSet();
		union.addAll(attributeKeys());
		union.addAll(toOneRelationshipKeys());
		union.addAll(toManyRelationshipKeys());
		return new NSArray((Collection) union);
	}

	/**
	 * Returns a list of all attributes defined on this object. Attributes are all
	 * properties that are not relationships. This implementation retrieves the keys
	 * from the class description.
	 */
	public NSArray attributeKeys() {
		return classDescription().attributeKeys();
	}

	// void awakeFromClientUpdate(EOEditingContext aContext)

	/**
	 * Called when the object has first been fetched into the specified editing
	 * context. This implementation calls awakeObjectFromFetch on the class
	 * description.
	 */
	public void awakeFromFetch(EOEditingContext anEditingContext) {
		classDescription().awakeObjectFromFetch(this, anEditingContext);
	}

	/**
	 * Called when the object has been inserted into the specified editing context.
	 * This implementation calls awakeObjectFromInsertion on the class description.
	 */
	public void awakeFromInsertion(EOEditingContext anEditingContext) {
		classDescription().awakeObjectFromInsertion(this, 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.
	 */
	public NSDictionary changesFromSnapshot(NSDictionary snapshot) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns a class description for this object. Calls
	 * EOClassDescription.classDescriptionForClass.
	 */
	public EOClassDescription classDescription() {
		if (classDescription == null) {
			classDescription = EOClassDescription.classDescriptionForClass(getClass());
			if (classDescription == null) {
				throw new WotonomyException("No class description found for class: " + getClass());
			}
		}
		return classDescription;
	}

	/**
	 * Returns a class description for the object at the other end of the specified
	 * relationship key. This implementation calls to the classDescription.
	 */
	public EOClassDescription classDescriptionForDestinationKey(String aKey) {
		return classDescription().classDescriptionForDestinationKey(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.
	 */
	public void clearProperties() {
		// FIXME: clear properties here
	}

	/**
	 * Returns the delete rule constant defined on EOClassDescription for the
	 * relationship defined by the specified key. This implementation calls to the
	 * classDescription.
	 */
	public int deleteRuleForRelationshipKey(String aRelationshipKey) {
		return classDescription().deleteRuleForRelationshipKey(aRelationshipKey);
	}

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

	/**
	 * Returns the name of the entity that this object represents.
	 */
	public String entityName() {
		return classDescription().entityName();
	}

	/**
	 * Returns a String containing all property keys and values for this object.
	 * Relationships should be represented by calling eoShallowDescription() on the
	 * object.
	 */
	public String eoDescription() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns a String containing all attribute keys and values for this object.
	 * Relationships are not included.
	 */
	public String eoShallowDescription() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns the key used to reference this object on the object at the other end
	 * of the specified relationship. This implementation calls to the class
	 * description.
	 */
	public String inverseForRelationshipKey(String aRelationshipKey) {
		return classDescription().inverseForRelationshipKey(aRelationshipKey);
	}

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

	/**
	 * Returns whether the specified relationship key represents a to-many
	 * relationship.
	 */
	public boolean isToManyKey(String aKey) {
		return toManyRelationshipKeys().containsObject(aKey);
	}

	/**
	 * Returns whether the objects at the other end of the specified relationship
	 * should be deleted when this object is deleted. This implementation calls to
	 * the class description.
	 */
	public boolean ownsDestinationObjectsForRelationshipKey(String aKey) {
		return classDescription().ownsDestinationObjectsForRelationshipKey(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. This implementation calls to the class
	 * description.
	 */
	public void propagateDeleteWithEditingContext(EOEditingContext aContext) {
		classDescription().propagateDeleteForObject(this, aContext);
	}

	/**
	 * Applies the changes from the specified snapshot to this object.
	 * 
	 * @see #changesFromSnapshot(NSDictionary)
	 */
	public void reapplyChangesFromDictionary(NSDictionary aDeltaSnapshot) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns a snapshot of the current state of this object. All property keys are
	 * mapped to their values; nulls are represented by NSNull.
	 */
	public NSDictionary snapshot() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns a List of the to-many relationship keys for this object. This
	 * implementation calls to the class description.
	 */
	public NSArray toManyRelationshipKeys() {
		return classDescription().toManyRelationshipKeys();
	}

	/**
	 * Returns a List of the to-one relationship keys for this object. This
	 * implementation calls to the class description.
	 */
	public NSArray toOneRelationshipKeys() {
		return classDescription().toOneRelationshipKeys();
	}

	/**
	 * Applies the specified snapshot to this object, converting NSNulls to null and
	 * calling takeStoredValueForKey for each key in the Map.
	 */
	public void updateFromSnapshot(NSDictionary aSnapshot) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns a short, stateful string representation of this object. This
	 * implementation calls to the class description.
	 */
	public String userPresentableDescription() {
		return classDescription().userPresentableDescriptionForObject(this);
	}

	/**
	 * This method should be called by each setter method on this object before
	 * changes are made to the object's internal state. This implementation calls
	 * EOObserverCenter.notifyObserversObjectWillChange( this ),
	 */
	public void willChange() {
		EOObserverCenter.notifyObserversObjectWillChange(this);
	}

	// interface EOKeyValueCoding

	/**
	 * Returns the value for the specified property. If the property does not exist,
	 * this method should call handleQueryWithUnboundKey.
	 */
	public Object valueForKey(String aKey) {
		return EOKeyValueCodingSupport.valueForKey(this, aKey);
	}

	/**
	 * Sets the property to the specified value. If the property does not exist,
	 * this method should call handleTakeValueForUnboundKey. If the property is of a
	 * type that cannot allow null (e.g. primitive types) and aValue is null, this
	 * method should call unableToSetNullForKey.
	 */
	public void takeValueForKey(Object aValue, String aKey) {
		EOKeyValueCodingSupport.takeValueForKey(this, aValue, aKey);
	}

	/**
	 * Returns the value for the private field that corresponds to the specified
	 * property.
	 */
	public Object storedValueForKey(String aKey) {
		return EOKeyValueCodingSupport.storedValueForKey(this, aKey);
	}

	/**
	 * Sets the the private field that corresponds to the specified property to the
	 * specified value.
	 */
	public void takeStoredValueForKey(Object aValue, String aKey) {
		EOKeyValueCodingSupport.takeStoredValueForKey(this, aValue, aKey);
	}

	/**
	 * Called by valueForKey when the specified key is not found on this object.
	 * Implementing classes should handle the specified value or otherwise throw an
	 * exception.
	 */
	public Object handleQueryWithUnboundKey(String aKey) {
		return EOKeyValueCodingSupport.handleQueryWithUnboundKey(this, aKey);
	}

	/**
	 * Called by takeValueForKey when the specified key is not found on this object.
	 * Implementing classes should handle the specified value or otherwise throw an
	 * exception.
	 */
	public void handleTakeValueForUnboundKey(Object aValue, String aKey) {
		EOKeyValueCodingSupport.handleTakeValueForUnboundKey(this, aValue, aKey);
	}

	/**
	 * Called by takeValueForKey when the type of the specified key is not allowed
	 * to be null, as is the case with primitive types. Implementing classes should
	 * handle this case appropriately or otherwise throw an exception.
	 */
	public void unableToSetNullForKey(String aKey) {
		EOKeyValueCodingSupport.unableToSetNullForKey(this, aKey);
	}

	// interface EOKeyValueCodingAdditions

	/**
	 * Returns the value for the specified key path, which is a series of keys
	 * delimited by ".", for example: "createTime.year.length".
	 */
	public Object valueForKeyPath(String aKeyPath) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Sets the value for the specified key path, which is a series of keys
	 * delimited by ".", for example: "createTime.year.length". The value is set for
	 * the last object referenced by the key path.
	 */
	public void takeValueForKeyPath(Object aValue, String aKeyPath) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns a Map of the specified keys to their values, each of which might be
	 * obtained by calling valueForKey.
	 */
	public NSDictionary valuesForKeys(List aKeyList) {
		return KeyValueCodingUtilities.valuesForKeys(this, aKeyList);
	}

	/**
	 * Takes the keys from the specified map as properties and applies the
	 * corresponding values, each of which might be set by calling takeValueForKey.
	 */
	public void takeValuesFromDictionary(Map aMap) {
		KeyValueCodingUtilities.takeValuesFromDictionary(this, aMap);
	}

	// interface EOFaulting

	/**
	 * Called by EOFaultHandler to prepare the object to be turned into a fault.
	 */
	public void clearFault() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns this object's EOFaultHandler.
	 */
	public EOFaultHandler faultHandler() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Returns whether this object is currently a fault. Returns true if this object
	 * has not yet retrieved any values.
	 */
	public boolean isFault() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Turns this object into a fault using the specified fault handler.
	 */
	public void turnIntoFault(EOFaultHandler aFaultHandler) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Called to completely fire the fault, reading all attributes. This method may
	 * be implemented to call willRead(null).
	 */
	public void willRead() {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Called to fire the fault for the specified key. The fault manager is required
	 * to populate the specified key with a value, and may populate any or all of
	 * the other values on this object. A null key will populate all values on the
	 * object. NOTE: This method is not part of the specification.
	 */
	public void willRead(String aKey) {
		throw new WotonomyException("Not implemented yet.");
	}

	// interface EODeferredFaulting

	/**
	 * Returns a fault for the specified deferred fault.
	 */
	public Object willReadRelationship(Object anObject) {
		throw new WotonomyException("Not implemented yet.");
	}

	// interface EORelationshipManipulation

	/**
	 * Adds the specified object to the relationship on this object specified by the
	 * key. For to-one relationships, this operation is the same as valueForKey.
	 */
	public void addObjectToPropertyWithKey(Object anObject, String aKey) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * Removes the specified object from the relationship on this object specified
	 * by the key. For to-one relationships, this operation is the same as
	 * takeValueForKey with a null value.
	 */
	public void removeObjectFromPropertyWithKey(Object anObject, String aKey) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * As addObjectToProperty with key, but also performs the reciprocal operation
	 * on the other side of the relationship.
	 */
	public void addObjectToBothSidesOfRelationshipWithKey(EORelationshipManipulation anObject, String aKey) {
		throw new WotonomyException("Not implemented yet.");
	}

	/**
	 * As removeObjectFromPropertyWithKey with key, but also performs the reciprocal
	 * operation on the other side of the relationship.
	 */
	public void removeObjectFromBothSidesOfRelationshipWithKey(EORelationshipManipulation anObject, String aKey) {
		throw new WotonomyException("Not implemented yet.");
	}

	// interface EOValidation

	/**
	 * Validates this object for delete. Throws an exception if this object cannot
	 * be deleted. This implementation calls to the class description.
	 */
	public void validateForDelete() {
		classDescription().validateObjectForDelete(this);
	}

	/**
	 * Validates this object for insertion into the external store. Throws an
	 * exception if this object cannot be inserted. Validations here should be
	 * specific to insertion. This implementation calls validateForSave().
	 */
	public void validateForInsert() {
		validateForSave();
	}

	/**
	 * Validates this object for a commit to the external store. Throws an exception
	 * if this object cannot be committed. Validations here are not specific to
	 * either inserts or updates. This implementation calls to the class
	 * description.
	 */
	public void validateForSave() {
		classDescription().validateObjectForSave(this);
	}

	/**
	 * Validates this object for update to the external store. Throws an exception
	 * if this object cannot be updated. Validations here should be specific to
	 * updates. This implementation calls validateForSave().
	 */
	public void validateForUpdate() {
		validateForSave();
	}
}

/*
 * $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.3 2001/12/06 16:42:29 mpowers Added appropriate constructor.
 *
 * Revision 1.2 2001/11/24 17:37:29 mpowers Implemented static methods.
 *
 * Revision 1.1 2001/11/17 17:18:15 mpowers Initial implementation of
 * EOCustomObject.
 *
 *
 */