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