/*
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 net.wotonomy.foundation.internal.Introspector;
import net.wotonomy.foundation.internal.IntrospectorException;
import net.wotonomy.foundation.internal.MissingPropertyException;
import net.wotonomy.foundation.internal.NullPrimitiveException;
import net.wotonomy.foundation.internal.WotonomyException;

/**
 * EOKeyValueCodingSupport defines default behavior for classes implementing
 * EOKeyValueSupport. <br>
 * <br>
 * 
 * On an object that does not implement EOKeyValueCoding, wotonomy will call the
 * methods on this class directly.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 894 $
 */
public class EOKeyValueCodingSupport {
	/**
	 * Returns the value for the specified property key on the specified object.
	 * <br>
	 * <br>
	 *
	 * If the property does not exist, this method calls handleQueryWithUnboundKey
	 * on the object if it implements EOKeyValueCoding, otherwise calls
	 * handleQueryWithUnboundKey on this class. <br>
	 * <br>
	 */
	static public Object valueForKey(Object anObject, String aKey) {
		// TODO: may need to handle "." nesting here so
		// that handleQueryWithUnboundKey gets called for
		// for the nested object, not the parent object

		// Correction: need to handle key paths in
		// KeyValueCodingAdditionsSupport.

		try {
			return Introspector.get(anObject, aKey);
		} catch (IntrospectorException exc) {
			if (anObject instanceof EOKeyValueCoding) {
				return ((EOKeyValueCoding) anObject).handleQueryWithUnboundKey(aKey);
			}
			return handleQueryWithUnboundKey(anObject, aKey);
		}
	}

	/**
	 * Sets the property to the specified value on the specified object.
	 *
	 * If the property does not exist, this method calls
	 * handleTakeValueForUnboundKey on the object if it implements EOKeyValueCoding,
	 * otherwise calls handleTakeValueForUnboundKey on this class.
	 * 
	 * If the property is of a type that cannot allow null (e.g. primitive types)
	 * and aValue is null, this method should call unableToSetNullForKey on the
	 * object if it implements EOKeyValueCoding, otherwise calls
	 * unableToSetNullForKey on this class.
	 */
	static public void takeValueForKey(Object anObject, Object aValue, String aKey) {
		// TODO: may need to handle "." nesting here so
		// that handleTakeValueForUnboundKey gets called for
		// for the nested object, not the parent object

		try {
			Introspector.set(anObject, aKey, aValue);
		} catch (NullPrimitiveException exc) {
			if (anObject instanceof EOKeyValueCoding) {
				((EOKeyValueCoding) anObject).unableToSetNullForKey(aKey);
			} else {
				unableToSetNullForKey(anObject, aKey);
			}
		} catch (MissingPropertyException exc) {
			if (anObject instanceof EOKeyValueCoding) {
				((EOKeyValueCoding) anObject).handleTakeValueForUnboundKey(aValue, aKey);
			} else {
				handleTakeValueForUnboundKey(anObject, aValue, aKey);
			}
		}

	}

	/**
	 * Returns the value for the private field that corresponds to the specified
	 * property on the specified object.
	 *
	 * This implementation currently calls valueForKey, because java security
	 * currently prevents us from accessing the fields of another object.
	 */
	static public Object storedValueForKey(Object anObject, String aKey) {
		// TODO: this currently just calls valueForKey
		return valueForKey(anObject, aKey);
	}

	/**
	 * Sets the the private field that corresponds to the specified property to the
	 * specified value on the specified object.
	 *
	 * This implementation currently calls takeValueForKey, because java security
	 * currently prevents us from accessing the fields of another object.
	 */
	static public void takeStoredValueForKey(Object anObject, Object aValue, String aKey) {
		// TODO: this currently just calls takeValueForKey
		takeValueForKey(anObject, aValue, aKey);
	}

	/**
	 * Called by valueForKey when the specified key is not found on the specified
	 * object, if that object does not implement EOKeyValueCoding.
	 *
	 * This implementation throws a WotonomyException.
	 */
	static public Object handleQueryWithUnboundKey(Object anObject, String aKey) {
		throw new WotonomyException("Key not found for object: " + aKey + " : " + anObject);
	}

	/**
	 * Called by takeValueForKey when the specified key is not found on the
	 * specified object, if that object does not implement EOKeyValueCoding.
	 *
	 * This implementation throws a WotonomyException.
	 */
	static public void handleTakeValueForUnboundKey(Object anObject, Object aValue, String aKey) {
		throw new WotonomyException(
				"Key not found for object while setting value: " + aKey + " : " + anObject + " : " + aValue);
	}

	/**
	 * Called by takeValueForKey when the type of the specified key is not allowed
	 * to be null, as is the case with primitive types, if the specified object does
	 * not implement EOKeyValueCoding.
	 *
	 * This implementation throws a WotonomyException.
	 */
	static public void unableToSetNullForKey(Object anObject, String aKey) {
		throw new WotonomyException("Tried to key on object to null: " + aKey + " : " + anObject);
	}

}

/*
 * $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.5 2003/01/16 22:47:30 mpowers Compatibility changes to support
 * compiling woextensions source. (34 out of 56 classes compile!)
 *
 * Revision 1.4 2001/05/18 21:04:33 mpowers Reimplemented
 * EditingContext.initializeObject.
 *
 * Revision 1.3 2001/04/27 00:28:29 mpowers Fixed a return value.
 *
 * Revision 1.2 2001/04/03 20:36:01 mpowers Fixed
 * refaulting/reverting/invalidating to be self-consistent.
 *
 * Revision 1.1 2001/03/28 17:49:33 mpowers Implemented EOKeyValueCodingSupport.
 *
 *
 */