/*
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 java.util.List;
import java.util.Map;

/**
* NSKeyValueCodingAdditions defines an interface for classes
* that need to have more control over the wotonomy's bulk 
* property copying and cloning facilities.  <br><br>
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 893 $
*/
public interface NSKeyValueCodingAdditions extends NSKeyValueCoding
{
    /**
    * Returns the value for the specified key path, which is
    * a series of keys delimited by ".", for example:
    * "createTime.year.length".
    */
    Object valueForKeyPath( String aKeyPath );

    /**
    * Sets the value for the specified key path, which is
    * a series of keys delimited by ".", for example:
    * "createTime.year.length".
    * The value is set for the last object referenced by
    * the key path.
    */
    void takeValueForKeyPath( Object aValue, String aKeyPath );
    
    /**
    * Returns a Map of the specified keys to their values,
    * each of which might be obtained by calling valueForKey.
    */
    NSDictionary valuesForKeys( List aKeyList );
    
    /**
    * Takes the keys from the specified map as properties
    * and applies the corresponding values, each of which
    * might be set by calling takeValueForKey.
    */
    void takeValuesFromDictionary( Map aMap );
    
    
    /**
    * Static utility methods that
    * call the appropriate method if the object implements
    * NSKeyValueCodingAdditions, otherwise calls the method
    * on DefaultImplementation.
    */
    public class Utility
    {
        /**
        * Calls the appropriate method if the object implements
        * NSKeyValueCodingAdditions, otherwise calls the method
        * on DefaultImplementation.
        */
        public static void takeValuesFromDictionary(
            Object object, Map dictionary)
        {
            if (object instanceof NSKeyValueCodingAdditions) {
                ((NSKeyValueCodingAdditions)object).takeValuesFromDictionary(dictionary);
            } else {
                DefaultImplementation.takeValuesFromDictionary(object, dictionary);
            }
         }
            
        /**
        * Calls the appropriate method if the object implements
        * NSKeyValueCodingAdditions, otherwise calls the method
        * on DefaultImplementation.
        */
        public static void takeValueForKeyPath(
            Object object, Object aValue, String aKeyPath)
        {
            if (object instanceof NSKeyValueCodingAdditions) {
                ((NSKeyValueCodingAdditions)object).takeValueForKeyPath(aValue, aKeyPath);
            } else {
                DefaultImplementation.takeValueForKeyPath(object, aValue, aKeyPath);
            }
        }
        
        /**
        * Calls the appropriate method if the object implements
        * NSKeyValueCodingAdditions, otherwise calls the method
        * on DefaultImplementation.
        */
        public static NSDictionary valuesForKeys(
            Object object, List keys)
        {
            if (object instanceof NSKeyValueCodingAdditions) {
                return ((NSKeyValueCodingAdditions)object).valuesForKeys(keys);
            } else {
                return DefaultImplementation.valuesForKeys(object, keys);
            }
        }
        
        /**
        * Calls the appropriate method if the object implements
        * NSKeyValueCodingAdditions, otherwise calls the method
        * on DefaultImplementation.
        */
        public static Object valueForKeyPath(
            Object object, String aKeyPath)
        {
            if (object instanceof NSKeyValueCodingAdditions) {
                return ((NSKeyValueCodingAdditions)object).valueForKeyPath(aKeyPath);
            } else {
                return DefaultImplementation.valueForKeyPath(object, aKeyPath);
            }
        }
    }
    
    /**
    * Provides a reflection-based implementation for classes that
    * don't implement NSKeyValueCodingAdditions.
    */
    public class DefaultImplementation 
    {
        /**
        * Provides a reflection-based implementation for classes that
        * don't implement NSKeyValueCodingAdditions.
        */
        public static void takeValuesFromDictionary(
            Object object, Map dictionary)
        {
            throw new RuntimeException( "Not implemented yet." );
         }
            
        /**
        * Provides a reflection-based implementation for classes that
        * don't implement NSKeyValueCodingAdditions.
        */
        public static void takeValueForKeyPath(
            Object object, Object aValue, String aKeyPath)
        {
            // currently, NSKeyValueCoding.takeValueForKey accepts paths
            NSKeyValueCoding.DefaultImplementation.takeValueForKey( object, aValue, aKeyPath );
        }
        
        /**
        * Provides a reflection-based implementation for classes that
        * don't implement NSKeyValueCodingAdditions.
        */
        public static NSDictionary valuesForKeys(
            Object object, List keys)
        {
            throw new RuntimeException( "Not implemented yet." );
        }
        
        /**
        * Provides a reflection-based implementation for classes that
        * don't implement NSKeyValueCodingAdditions.
        */
        public static Object valueForKeyPath(
            Object object, String aKeyPath)
        {
            // currently, NSKeyValueCoding.valueForKey accepts paths
            return NSKeyValueCoding.DefaultImplementation.valueForKey( object, aKeyPath );
        }
    }
}

/*
 * $Log$
 * Revision 1.2  2006/02/16 13:15:00  cgruber
 * Check in all sources in eclipse-friendly maven-enabled packages.
 *
 * Revision 1.2  2003/01/18 23:30:42  mpowers
 * WODisplayGroup now compiles.
 *
 * Revision 1.1  2003/01/17 14:40:49  mpowers
 * Adding files to fix build.
 *
 * Revision 1.3  2001/12/10 15:25:11  mpowers
 * Now properly extending NSKeyValueCoding.
 *
 * Revision 1.2  2001/04/28 14:12:23  mpowers
 * Refactored cloning/copying into KeyValueCodingUtilities.
 *
 * Revision 1.1  2001/03/29 03:29:49  mpowers
 * Now using KeyValueCoding and Support instead of Introspector.
 *
 * 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.
 *
 *
 */