/*

 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.foundation;

 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;

 /**

 * NSKeyValueCodingSupport defines default behavior for

 * classes implementing NSKeyValueSupport.  <br><br>

 * 

 * On an object that does not implement NSKeyValueCoding,

 * wotonomy will call the methods on this class directly.  

 *

 * @author michael@mpowers.net

 * @author $Author: cgruber $

 * @version $Revision: 892 $

 */

 public class NSKeyValueCodingSupport

 {

     /**

     * 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 NSKeyValueCoding, 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 NSKeyValueCoding )

             {

                 return ((NSKeyValueCoding)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 NSKeyValueCoding, 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 NSKeyValueCoding, 

     * 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 NSKeyValueCoding )

             {

                 ((NSKeyValueCoding)anObject).unableToSetNullForKey( aKey );

             } 

             else

             {

                 unableToSetNullForKey( anObject, aKey );   

             }

         }

         catch ( MissingPropertyException exc )

         {

             if ( anObject instanceof NSKeyValueCoding )

             {

                 ((NSKeyValueCoding)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 NSKeyValueCoding.

     *

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

     *

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

     *

     * 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.1  2006/02/16 12:47:16  cgruber

  * Check in all sources in eclipse-friendly maven-enabled packages.

  *

  * Revision 1.1  2003/01/17 14:40:50  mpowers

  * Adding files to fix build.

  *

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

  *

  *

  */