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