path: root/projects/net.wotonomy.ui/src/main/java/net/wotonomy/ui/MasterDetailAssociation.java

/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2000 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.ui;

import net.wotonomy.control.EOClassDescription;
import net.wotonomy.control.EODataSource;
import net.wotonomy.control.EOEditingContext;
import net.wotonomy.control.EOObserverCenter;
import net.wotonomy.control.PropertyDataSource;
import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSMutableArray;

/**
* MasterDetailAssociation binds a display group to a property
* on the selected object of another display group.
* Bindings are: 
* <ul>
* <li>parent: The property on the selected object of the
* bound display group that is expected to be an indexed property.</li> 
* </ul>
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 904 $
*/
public class MasterDetailAssociation extends EOAssociation
{
    static final NSArray aspects = 
        new NSArray( new Object[] {
            ParentAspect
        } );
    static final NSArray aspectSignatures = 
        new NSArray( new Object[] {
            AttributeToOneAspectSignature
        } );
    static final NSArray objectKeysTaken = 
        new NSArray( new Object[] {
            "allObjects" 
        } );

    /**
    * Used to be notified of changes to objects in the
    * controlled display group.  requalify() should place 
    * all objects fetched into the controlled group into
    * this array.
    * Otherwise, the parent object is only marked as 
    * changed for inserts and deletes.
    */
    protected NSMutableArray observableArray;
		
    /**
    * Constructor expecting an EODisplayGroup. 
    * If the controlled display group does not have a data source,
    * a new PropertyDataSource will be used.
    */
    public MasterDetailAssociation ( Object anObject )
    {
        super( anObject );
        observableArray = new ObservableArray( this );
    }
    
    /**
    * 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 ()
    {
        return aspectSignatures;
    }
    
    /**
    * 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.
    */
    public static NSArray aspects ()
    {
        return aspects;
    }
    
    /**
    * Returns a List of EOAssociation subclasses that,
    * for the objects that are usable for this association,
    * are less suitable than this association.
    */
    public static NSArray associationClassesSuperseded ()
    {
        return new NSArray();
    }
    
    /**
    * Returns whether this class can control the specified 
    * object. 
    */
    public static boolean isUsableWithObject ( Object anObject )
    {
        return ( anObject instanceof EODisplayGroup );
    }
    
    /**
    * Returns a List of properties of the controlled object
    * that are controlled by this class.  For example,
    * "stringValue", or "selected".
    */
    public static NSArray objectKeysTaken ()
    {
        return objectKeysTaken;
    }
    
    /**
    * Returns the aspect that is considered primary
    * or default.  This is typically "value" or somesuch.
    */
    public static String primaryAspect ()
    {
        return ParentAspect;
    }
        
    /**
    * Returns whether this association can bind to the
    * specified display group on the specified key for
    * the specified aspect.  
    */
    public boolean canBindAspect ( 
        String anAspect, EODisplayGroup aDisplayGroup, String aKey)
    {
        return ( aspects.containsObject( anAspect ) );
    }
    
    /**
    * Establishes a connection between this association
    * and the controlled object.  Subclasses should begin
    * listening for events from their controlled object here.
    */
    public void establishConnection ()
    {
        //NOTE: if nothing refers to this assocation, it gets gc'd.
        // otherwise, this is not needed.
        component().addObserver( this );

        EODisplayGroup displayGroup = 
            displayGroupForAspect( ParentAspect );
        String key = 
            displayGroupKeyForAspect( ParentAspect );

        // obtain and qualify new data source from existing source if necessary
        if ( component().dataSource() == null ) 
        {
            if ( ( displayGroup != null ) && ( displayGroup.dataSource() != null ) )
            {
                component().setDataSource( 
                    displayGroup.dataSource().
                        dataSourceQualifiedByKey( key ) );
            }
        }

        // set up proxy data source if necessary
        if ( component().dataSource() == null )
        {
            // get context and class desc from master group
            EOEditingContext editingContext = null;
            EOClassDescription classDesc = null;
            if ( displayGroup != null )
            {
                EODataSource dataSource = displayGroup.dataSource();
                if ( dataSource != null )
                {
                    editingContext = dataSource.editingContext();
                    EOClassDescription parentDesc = dataSource.classDescriptionForObjects();
                    if ( parentDesc != null )
                    {
                        classDesc = parentDesc.classDescriptionForDestinationKey( key );   
                    }
                }
            }
            
            //FIXME: should this be called DetailDataSource?
            component().setDataSource( 
               new PropertyDataSource( editingContext, classDesc ) );
        }

        super.establishConnection();
		requalify();
    }
    
    /**
    * Breaks the connection between this association and 
    * its object.  Override to stop listening for events
    * from the object.
    */
    public void breakConnection ()
    {
        //NOTE: if nothing refers to this assocation, it gets gc'd.
        // otherwise, this is not needed.
        component().deleteObserver( this );        

        super.breakConnection();
    }
	
    /**
    * Called when either the selection or the contents 
    * of an associated display group have changed.
    */
    public void subjectChanged ()
    {
		EODisplayGroup displayGroup;

		// parent aspect
		displayGroup = displayGroupForAspect( ParentAspect );
		if ( displayGroup != null )
		{
			if ( displayGroup.selectionChanged() )
			{
                requalify();
			}
			else
			if ( displayGroup.contentsChanged() )
			{
                requalify();
			}
		}
    }

    /**
    * Overridden to intercept notifications of changes to objects 
    * in the controlled display group and broadcast a change on the 
    * parent group's selected object.  All other notifications are
    * passed to the super implementation.
    */
    public void objectWillChange ( Object anObject )
    {
        // if child display group is notifying
        if ( ! ( anObject instanceof EODisplayGroup ) )
        {
            // mark parent group's object as changed
            EODisplayGroup displayGroup = displayGroupForAspect( ParentAspect );
            if ( displayGroup != null )
            {
                Object selected = displayGroup.selectedObject();
                if ( selected != null )
                {
                    // only notify if childrenKey is an attribute of parentDesc
                    // (and therefore not a toOne or toMany relationship)
                    EOClassDescription parentDesc = 
                        EOClassDescription.classDescriptionForClass( 
                            selected.getClass() );
                    String key = displayGroupKeyForAspect( ParentAspect );
                    if ( key != null )
                    {
                        int idx = key.indexOf( '.' );
                        if ( idx != -1 ) key = key.substring( 0, idx );
                        if ( parentDesc.attributeKeys().contains( key ) )
                        {
                            // only notify if we are an attribute key
                            EOObserverCenter.notifyObserversObjectWillChange( selected );
                        }
                    }
                }
            }
        }
        else // display group is notifying
        {
            // call super so subjectChanged will be called
            super.objectWillChange( anObject );
        }
    }
    
    /**
    * Called by subjectChanged() to requalify the controlled
    * display group with the selected object and the bound key.
    */
	protected void requalify()
	{
		EODisplayGroup component = component();
		EODisplayGroup displayGroup = displayGroupForAspect( ParentAspect );
		String key = displayGroupKeyForAspect( ParentAspect );
		
		if ( ( displayGroup.selectedObject() != null )
        && ( component.dataSource() != null ) )
		{
			component.dataSource().qualifyWithRelationshipKey( 
				key, displayGroup.selectedObject() );  
			component.fetch();
            observableArray.setArray( component.allObjects() );
		}
		else // no selection or no data source, clear
		{
			component.setObjectArray( null );
            observableArray.removeAllObjects();
		}
        component.updateDisplayedObjects();
	}
                  
    /**
	* This implementation returns ObserverPrioritySecond
	* so that master detail assocations are notified before
    * other associations.
    */
    public int priority ()
    {
        return ObserverPrioritySecond;
    }

	// convenience

    private EODisplayGroup component()
    {
        return (EODisplayGroup) object();
    }
    
}

/*
 * $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.14  2004/02/04 20:00:49  mpowers
 * Improved change notification for dotted key paths.
 *
 * Revision 1.13  2003/08/06 23:07:52  chochos
 * general code cleanup (mostly, removing unused imports)
 *
 * Revision 1.12  2001/10/26 18:39:05  mpowers
 * Now a delayed observer with a higher priority, so that it is processed
 * before other associations.
 *
 * Revision 1.11  2001/06/26 21:39:33  mpowers
 * Added check for null component data source before requalifying.
 *
 * Revision 1.10  2001/05/21 14:04:15  mpowers
 * No longer changing a detail group's data source if it's already specified.
 *
 * Revision 1.9  2001/05/18 21:08:46  mpowers
 * Now calling updateDisplayedObjects on detail after master changes.
 *
 * Revision 1.8  2001/05/14 15:26:42  mpowers
 * Modified logic for controlled groups that have no data source already set.
 *
 * Revision 1.7  2001/05/04 14:42:58  mpowers
 * Now getting stored values in KeyValueCoding.
 * MasterDetail now marks dirty based on whether it's an attribute
 * or relation.
 * Implemented editing context marker.
 *
 * Revision 1.6  2001/04/29 02:29:31  mpowers
 * Debugging relationship faulting.
 *
 * Revision 1.4  2001/02/20 16:38:55  mpowers
 * MasterDetailAssociations now observe their controlled display group's
 * objects for changes to that the parent object will be marked as updated.
 * Before, only inserts and deletes to an object's items are registered.
 * Also, moved ObservableArray to package access.
 *
 * Revision 1.3  2001/01/18 16:57:18  mpowers
 * Fixed problem with losing connection: the association was getting
 * garbage collected because nothing referred to it.  All other associations
 * make themselves listeners of their controlled object, and that has been
 * the only thing keeping them from getting gc'd.  This will need to be fixed.
 *
 * Revision 1.2  2001/01/17 23:06:09  mpowers
 * TreeAssociation now modifies the contents of the children display
 * group rather than adding items to the titles display group.
 *
 * Revision 1.1.1.1  2000/12/21 15:48:23  mpowers
 * Contributing wotonomy.
 *
 * Revision 1.5  2000/12/20 16:25:40  michael
 * Added log to all files.
 *
 *
 */