/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2000 Blacksmith, Inc.

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

/**
 * A pure java implementation of WOAssociation. <br>
 * <br>
 *
 * A WOAssociation represents the mapping of a property on a WOComponent to a
 * property on a WOAssociation. For example: <br>
 * <br>
 * 
 * MyAssociation: WOString { value = currentCustomer.location.city }; <br>
 * <br>
 *
 * This example represents a WOAssociation between the value field on a WOString
 * element and the city property of the location property of the currentCustomer
 * property of a WOComponent. <br>
 * <br>
 *
 * To resolve values, a property accessor method will be used in preference to a
 * public field, if both exist. Any null value in the path will produce null.
 * <br>
 * <br>
 *
 * A mapping represented in quotation marks: { value = "This is a test." } is
 * considered a constant value.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 893 $
 */
public class WOAssociation implements java.io.Serializable {
	protected Object value;
	protected String path;

	/**
	 * The default constructor. The static factory methods should be used to create
	 * instances of WOAssociation.
	 */
	protected WOAssociation() {
		value = null;
		path = null;
	}

	/**
	 * Creates a WOAssociation that maps to a constant value.
	 */
	public static WOAssociation associationWithValue(Object anObject) {
		WOAssociation result = new WOAssociation();
		result.value = anObject;
		return result;
	}

	/**
	 * Creates a WOAssociation that maps to the specified key path. If the path is
	 * null, the association will map to null. Throws an exception if the property
	 * cannot be resolved.
	 */
	public static WOAssociation associationWithKeyPath(String aString) {
		WOAssociation result = new WOAssociation();
		result.path = aString;
		return result;
	}

	/**
	 * Returns the value for this association's key path in the specified component,
	 * or null if any value in the path is null or if the key path is null.
	 */
	public Object valueInComponent(WOComponent aComponent) {
		if (aComponent == null)
			return null;
		if (value != null)
			return value;
		if (path != null)
			return aComponent.valueForKey(path);
		throw new RuntimeException("WOAssociation: neither value nor path specified!");
	}

	/**
	 * Sets the property in the specified component to the specified value. Throws
	 * an exception if the property cannot be resolved.
	 */
	public void setValue(Object aValue, WOComponent aComponent) {
		if (path != null) {
			aComponent.takeValueForKey(aValue, path);
			return;
		}
		throw new RuntimeException("WOAssociation: tried to set value but no path was specified!");
	}

	/**
	 * Returns true if this association is writable; that is, returns true if this
	 * association is not constant.
	 */
	public boolean isValueSettable() {
		return (path != null);
	}

	/**
	 * Returns true if this association is constant and therefore read-only.
	 */
	public boolean isValueConstant() {
		return (path == null);
	}

	/**
	 * For debugging purposes.
	 */
	public String toString() {
		if (path != null) {
			return "[WOAssociation:" + path + "]";
		}
		return "[WOAssociation:\"" + value + "\"]";
	}
}

/*
 * $Log$ Revision 1.1 2006/02/16 13:22:22 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.6 2003/01/24 20:13:22 mpowers Now accepting immutable NSDictionary
 * in constructor, not Map.
 *
 * Revision 1.5 2003/01/17 22:55:08 mpowers Straighted out the parent binding
 * issue (I think). Fixes for woextensions compatibility.
 *
 * Revision 1.3 2003/01/15 19:50:49 mpowers Fixed issues with WOSession and
 * Serializable. Can now persist sessions between classloaders (hot swap of
 * class impls).
 *
 * Revision 1.2 2003/01/14 15:51:48 mpowers Removed value() method from
 * WOAssociaton.
 *
 * Revision 1.1.1.1 2000/12/21 15:52:50 mpowers Contributing wotonomy.
 *
 * Revision 1.3 2000/12/20 16:25:49 michael Added log to all files.
 *
 *
 */