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