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