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