/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2000 Michael Powers

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

import java.util.Enumeration;

import net.wotonomy.control.EODelayedObserver;
import net.wotonomy.control.EOObserverCenter;
import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSMutableArray;
import net.wotonomy.foundation.NSMutableDictionary;

/**
* Associations observe DisplayGroups and associate
* a user interface component with one or more keys 
* on the objects in the display group. <br><br>
*
* Associations are created with a ui component in
* the constructor.  Then, one or more aspects are
* bound to display groups and/or property keys with
* the bindAspect() method.   Finally, the association
* is initialized with the establishConnection() 
* method. <br><br>
*
* Per the openstep convention, you do not need to 
* retain a reference to the association after it is 
* created; the association will be garbage-collected
* when the ui component is garbage-collected. <br><br> 
*
* (Because java components don't have delegates like
* openstep components do, java-based associations 
* will likely need to implement some sort of listener
* and add itself to the component's list of listeners
* so that the component will have a strong reference
* (and the only reference) to the association.) <br><br>
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 904 $
*/
public class EOAssociation extends EODelayedObserver
{
	// aspect constants 
	public static final String ActionAspect = "action";
	public static final String EnabledAspect = "enabled";
	public static final String SourceAspect = "source";
	public static final String ArgumentAspect = "argument";
	public static final String ParentAspect = "parent";
	public static final String TitlesAspect = "titles";
	public static final String BoldAspect = "bold";
	public static final String SelectedObjectAspect = "selectedObject";
	public static final String ValueAspect = "value";
	public static final String DestinationAspect = "destination";
	public static final String SelectedTitleAspect = "selectedTitle";
	public static final String URLAspect = "URL";
	public static final String ItalicAspect = "italic";
	public static final String ChildrenAspect = "children"; // not in spec
	public static final String IsLeafAspect = "isLeaf"; // not in spec
	public static final String EditableAspect = "editable"; // not in spec
	public static final String VisibleAspect = "visible"; // not in spec
	public static final String ObjectsAspect = "objects"; // not in spec
	public static final String LabelAspect = "label"; // not in spec
	public static final String IconAspect = "icon"; // not in spec
		
	public static final String AttributeAspectSignature = "A";
	public static final String NullAspectSignature = "";
	public static final String AttributeToOneAspectSignature = "A1"; 
	public static final String ToOneAspectSignature = "1";
	public static final String AttributeToOneToManyAspectSignature = "A1M"; 
	public static final String ToOneToManyAspectSignature = "1M";
	public static final String AttributeToManyAspectSignature = "AM";
	public static final String ToManyAspectSignature = "M";
		
    protected Object control;
    protected NSMutableDictionary aspectToGroup;
    protected NSMutableDictionary aspectToKey;

    /**
    * Default constructor.
    */ 
    public EOAssociation ()
    {
        aspectToGroup = new NSMutableDictionary();
        aspectToKey = new NSMutableDictionary();
        control = null;
    }
    
    /**
    * Constructor specifying the object to be controlled by this
    * association.  Does not establish connection.
    */
    public EOAssociation ( Object anObject )
    {
        this();
        control = anObject;
    }
    
    /**
    * Returns a List of aspect signatures whose contents
    * correspond with the aspects list.  Each element is 
    * a string whose characters represent a capability of
    * the corresponding aspect. <ul>
    * <li>"A" attribute: the aspect can be bound to
    * an attribute.</li>
    * <li>"1" to-one: the aspect can be bound to a
    * property that returns a single object.</li>
    * <li>"M" to-one: the aspect can be bound to a
    * property that returns multiple objects.</li>
    * </ul> 
    * An empty signature "" means that the aspect can
    * bind without needing a key.
    * This implementation returns "A1M" for each
    * element in the aspects array.
    */
    public static NSArray aspectSignatures ()
    {
        int size = aspects().count();
        NSMutableArray result = new NSMutableArray();
        for ( int i = 0; i < size; i++ )
        {
            result.addObject( AttributeToOneToManyAspectSignature );
        }
        return result;
    }
    
    /**
    * Returns a List that describes the aspects supported
    * by this class.  Each element in the list is the string
    * name of the aspect.  This implementation returns an
    * empty list.
    * 
    * TODO: Is this static in the WebObjects published API? If not, fix.
    */
    public static NSArray aspects ()
    {
        return new NSArray();
    }
    
    /**
    * Returns all registered subclasses of EOAssociation 
    * for which usableWithObject with the specified object
    * returns true.  You should only call this method on 
    * the EOAssociation class.
    */
    public static NSArray associationClassesForObject ( 
        Object anObject )
    {
        throw new RuntimeException( "Not implemented yet." );
    }
    
    /**
    * Returns a List of EOAssociation subclasses that,
    * for the objects that are usable for this association,
    * are less suitable than this association.
    * This implementation returns an empty list.
    */
    public static NSArray associationClassesSuperseded ()
    {
        return new NSArray();
    }
    

    /**
    * Binds the specified aspect of this association to the
    * specified key on the specified display group.
    */
    public void bindAspect ( 
        String anAspect, EODisplayGroup aDisplayGroup, String aKey )
    {
		// unattach old group, if any
		EODisplayGroup oldGroup = displayGroupForAspect( anAspect );
		if ( oldGroup != null )
		{
			EOObserverCenter.removeObserver( this, oldGroup );	
		}

		// attach new group
		if ( aDisplayGroup != null )
		{
			aspectToGroup.setObjectForKey( aDisplayGroup, anAspect );
		}
		else
		{
			aspectToGroup.removeObjectForKey( anAspect );	
		}
		// attach new key
		if ( aKey != null )
		{
			aspectToKey.setObjectForKey( aKey, anAspect );
		}
		else
		{
			aspectToKey.removeObjectForKey( anAspect );
		}
    }
    
    /**
    * Breaks the connection between this association and 
    * its object.  Override to stop listening for events
    * from the object, but remember to call this method.
    * This implementation unregisters this association
	* from observing each bound display group.
    */
    public void breakConnection ()
    {
        discardPendingNotification();
        Enumeration e = aspectToGroup.objectEnumerator();
		while ( e.hasMoreElements() )
		{
			EOObserverCenter.removeObserver( this, e.nextElement() );	
		}
    }

    /**
    * Returns whether this association can bind to the
    * specified display group on the specified key for
    * the specified aspect.  
    * This implementation returns false.
    */
    public boolean canBindAspect ( 
        String anAspect, EODisplayGroup aDisplayGroup, String aKey)
    {
        return false;
    }
    
    /**
    * Copies the binding for each aspect in this association
    * that has a matching aspect in the specified association.
    */
    public void copyMatchingBindingsFromAssociation ( 
        EOAssociation anAssociation )
    {
		//FIXME: this is broken: aspects() returns EOAssociation.aspects()
		//NOTE: This is actually quite crazy - should this even be static? -ceg
        NSMutableArray ourAspects = new NSMutableArray( this.aspects() );
        NSArray theirAspects = anAssociation.aspects();

        String aspect;
        Enumeration e = ourAspects.objectEnumerator();
        while ( e.hasMoreElements() )
        {
            aspect = e.nextElement().toString();
            if ( theirAspects.containsObject( aspect ) )
            {
                this.bindAspect(
                aspect,
                anAssociation.displayGroupForAspect( aspect ),
                anAssociation.displayGroupKeyForAspect( aspect ) );
            }
        }
    }
    
    /**
    * Returns the display group that is bound the specified
    * aspect, or null if no display group is currently 
    * bound to that aspect.
    */
    public EODisplayGroup displayGroupForAspect ( String anAspect )
    {
        return (EODisplayGroup) aspectToGroup.objectForKey( anAspect );
    }
    
    /**
    * Returns the key for the display group bound to the
    * specified aspect, or null if no display group is currently
    * bound to that aspect.
    */
    public String displayGroupKeyForAspect ( String anAspect )
    {
        return (String) aspectToKey.objectForKey( anAspect );
    }
    
    /**
    * The human-readable descriptive name for this association.
    * This implementation returns the class name.
    */
    public String displayName () // was static - can static method get class name?
    {
    	String className = getClass().getName();
	    int index = className.lastIndexOf( "." );
	    if ( index == -1 ) return className;
	    return className.substring( index+1 );
    }

    /**
    * Forces this association to cause the object to 
    * stop editing and validate the user's input.
    * This implementation returns true.
    * @return false if there were problems validating,
    * or true to continue.
    */
    public boolean endEditing ()
    {
        return true;
    }

    /**
    * Establishes a connection between this association
    * and the controlled object.  Subclasses should populate
	* their controlled object from the display group and begin
    * listening for events from their controlled object here,
	* but remember to call this method.  Any existing value
	* in the controlled object will be overwritten.
    * This implementation registers this assocation to 
	* observer changes to each of the bound display groups.
    */
    public void establishConnection ()
    {
        Enumeration e = aspectToGroup.objectEnumerator();
		while ( e.hasMoreElements() )
		{
			EOObserverCenter.addObserver( this, e.nextElement() );	
		}
    }
    
    /**
    * Returns whether this class can control the specified 
    * object.  This implementation returns false.
    */
    public static boolean isUsableWithObject ( Object anObject )
    {
        return false;
    }
    
    /**
    * Returns the object that is currently controlled by this
    * association, or null if no object is currently controlled.
    */
    public Object object ()
    {
        return control;
    }
    
    /**
    * Returns a List of properties of the controlled object
    * that are controlled by this class.  For example,
    * "stringValue", or "selected".
    * This implementation returns an empty list.
    */
    public static NSArray objectKeysTaken ()
    {
        return new NSArray();
    }
    
    /**
    * Returns the aspect that is considered primary
    * or default.  This is typically "value" or somesuch.
    * This implementation returns null.
    */
    public static String primaryAspect ()
    {
        return null;
    }
    
    /**
    * Writes the specified value for the display group
    * and key currently bound to the specified aspect.
    * This implementation calls 
    * EODisplayGroup.setSelectedObjectValue().
    * @return True if the value was successfully set,
    * otherwise false.
    */
    public boolean setValueForAspect ( 
        Object aValue,
        String anAspect )
    {
        EODisplayGroup group = (EODisplayGroup)
            aspectToGroup.objectForKey( anAspect );
        if ( group == null ) return false;
        String key = (String)
            aspectToKey.objectForKey( anAspect );
        if ( key == null ) return false;
        
        //FIXME: is this the right method to call
        return group.setSelectedObjectValue( aValue, key );
    }
    

    /**
    * Writes the specified value for the display group
    * and key currently bound to the specified aspect,
    * at the specified index (assuming it's an indexed
    * property).
    * This implementation calls 
    * EODisplayGroup.setValueForObjectAtIndex().
    * @return True if the value was successfully set,
    * otherwise false.
    */
    public boolean setValueForAspectAtIndex ( 
        Object aValue,
        String anAspect,
        int anIndex )
    {
        EODisplayGroup group = (EODisplayGroup)
            aspectToGroup.objectForKey( anAspect );
        if ( group == null ) return false;
        String key = (String)
            aspectToKey.objectForKey( anAspect );
        if ( key == null ) return false;
        
        //FIXME: is this the right method to call?
        return group.setValueForObjectAtIndex( aValue, anIndex, key );
    }
    
    /**
    * Called by subclasses to notify that the user's input
    * failed validation.  Notifies the display group for
    * the aspect, returning the result.
    * This implementation calls 
    * EODisplayGroup.associationFailedToValidateValue() 
    * with the display group's selected object.
    * @return True if the user should be allowed to continue,
    * meaning that the display group with handle user notification, 
    * otherwise false meaning the caller should notify the user.
    */
    public boolean shouldEndEditing ( 
        String anAspect,
        String anInvalidInput,
        String anErrorDescription )
    {
        EODisplayGroup group = (EODisplayGroup)
            aspectToGroup.objectForKey( anAspect );
        if ( group == null ) return false;
        String key = (String)
            aspectToKey.objectForKey( anAspect );
        if ( key == null ) return false;
        return group.associationFailedToValidateValue(
            this, anInvalidInput, key, 
            group.selectedObject(), //FIXME: is this correct?
            anErrorDescription );
    }
    
    /**
    * Called by subclasses to notify that the user's input
    * failed validation.  Notifies the display group for
    * the aspect, returning the result.
    * This implementation calls 
    * EODisplayGroup.associationFailedToValidateValue() 
    * with the object in the display group's displayed
    * objects array at the specified index.
    * @return True if the user should be allowed to continue,
    * meaning that the display group with handle user notification, 
    * otherwise false meaning the caller should notify the user.
    */
    public boolean shouldEndEditingAtIndex ( 
        String anAspect,
        String anInvalidInput,
        String anErrorDescription,
        int anIndex )
    {
        EODisplayGroup group = (EODisplayGroup)
            aspectToGroup.objectForKey( anAspect );
        if ( group == null ) return false;
        String key = (String)
            aspectToKey.objectForKey( anAspect );
        if ( key == null ) return false;
        return group.associationFailedToValidateValue(
            this, anInvalidInput, key, 
            group.displayedObjects().objectAtIndex( anIndex ), 
            //FIXME: is this correct?
            anErrorDescription );
    }
    
    /**
    * Called when either the selection or the contents of 
    * an associated display group have changed.
    * This implementation does nothing.
    */
    public void subjectChanged ()
    {
        // does nothing
    }
    
    /**
    * Returns the current value for the display group 
    * and key associated with the specified aspect.
    */
    public Object valueForAspect ( String anAspect )
    {
        EODisplayGroup group = (EODisplayGroup)
            aspectToGroup.objectForKey( anAspect );
        if ( group == null ) return null;
        String key = (String)
            aspectToKey.objectForKey( anAspect );
        if ( key == null ) return null;
        
        //FIXME: is this correct?  use selected object?
        return group.valueForObject( group.selectedObject(), key );
    }
    
    /**
    * Returns the current value for the display group 
    * and key associated with the specified aspect,
    * and the specified index (assuming multiple values).
    */
    public Object valueForAspectAtIndex ( 
        String anAspect, int anIndex )
    {
        EODisplayGroup group = (EODisplayGroup)
            aspectToGroup.objectForKey( anAspect );
        if ( group == null ) return null;
        String key = (String)
            aspectToKey.objectForKey( anAspect );
        if ( key == null ) return null;
        
        //FIXME: is this the right method to call?
        return group.valueForObjectAtIndex( anIndex, key );
    }
    
}

/*
 * $Log$
 * Revision 1.2  2006/02/18 23:14:35  cgruber
 * Update imports and maven dependencies.
 *
 * Revision 1.1  2006/02/16 13:22:22  cgruber
 * Check in all sources in eclipse-friendly maven-enabled packages.
 *
 * Revision 1.7  2005/05/11 15:21:53  cgruber
 * Change enum to enumeration, since enum is now a keyword as of Java 5.0
 *
 * A few other comments in the code.
 *
 * Revision 1.6  2003/08/06 23:07:52  chochos
 * general code cleanup (mostly, removing unused imports)
 *
 * Revision 1.5  2003/06/06 20:29:45  mpowers
 * Now dequeuing the association when connection is broken.
 * Coalesced change events had been processed even after breaking connection.
 *
 * Revision 1.4  2001/03/06 23:43:46  mpowers
 * Implemented icon aspect for text association.
 *
 * Revision 1.3  2001/02/17 16:52:05  mpowers
 * Changes in imports to support building with jdk1.1 collections.
 *
 * Revision 1.2  2001/01/25 17:46:11  mpowers
 * Clarified usage and gc expectations.
 *
 * Revision 1.1.1.1  2000/12/21 15:48:07  mpowers
 * Contributing wotonomy.
 *
 * Revision 1.11  2000/12/20 16:25:39  michael
 * Added log to all files.
 *
 *
 */