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

/**
 * EOKeyValueCoding defines an interface for classes that need to have more
 * control over the wotonomy's property introspection facilities. <br>
 * <br>
 * 
 * On an object that implements this interface, wotonomy will call these
 * methods, and otherwise use the static methods on EOKeyValueCodingSupport.
 * <br>
 * <br>
 *
 * EOKeyValueCodingSupport implements the default behaviors for each of these
 * methods, so classes implementing this interface can call those methods to
 * acheive the same behavior. <br>
 * <br>
 *
 * valueForKey and takeValueForKey are called in response to user actions, like
 * viewing an object or updating its value in a user interface. These should
 * call the public getter and setter methods on the object itself and the
 * operations should be subject to validation. <br>
 * <br>
 * 
 * storedValueForKey and takeStoredValueForKey are called in response to
 * wotonomy actions, like snapshotting, faulting, commits, and reverts. These
 * operations should bypass the public methods and directly modify the internal
 * state of the object without validation.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 893 $
 */
public interface EOKeyValueCoding extends NSKeyValueCoding {
	/**
	 * Returns the value for the specified property. If the property does not exist,
	 * this method should call handleQueryWithUnboundKey.
	 */
	Object valueForKey(String 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.
	 */
	void takeValueForKey(Object aValue, String aKey);

	/**
	 * Returns the value for the private field that corresponds to the specified
	 * property.
	 */
	Object storedValueForKey(String aKey);

	/**
	 * Sets the the private field that corresponds to the specified property to the
	 * specified value.
	 */
	void takeStoredValueForKey(Object aValue, String 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.
	 */
	Object handleQueryWithUnboundKey(String 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.
	 */
	void handleTakeValueForUnboundKey(Object aValue, String 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.
	 */
	void unableToSetNullForKey(String aKey);

}

/*
 * $Log$ Revision 1.1 2006/02/16 13:19:57 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.3 2003/01/16 22:47:30 mpowers Compatibility changes to support
 * compiling woextensions source. (34 out of 56 classes compile!)
 *
 * Revision 1.2 2001/03/28 16:12:30 mpowers Documented interface.
 *
 * Revision 1.1 2001/03/27 23:25:05 mpowers Contributing interface, no docs yet.
 *
 *
 */