path: root/projects/net.wotonomy.persistence/src/main/java/net/wotonomy/control/EOObserverCenter.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.control;

import java.lang.ref.Reference;
import java.lang.ref.ReferenceQueue;
import java.lang.ref.WeakReference;
import java.util.ArrayList;
import java.util.Hashtable;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Observable;
import java.util.Observer;

import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSMutableArray;

/**
* EOObserverCenter is a static singleton-like class
* that manages EOObservings that want to be notified
* of changes to those objects that call 
* notifyObserversObjectWillChange() before their 
* properties change. <br><br>
*
* Implementation note: Because Java implements the
* Observer pattern in java.util.Observable, this
* class knows how to register itself as an Observer
* with Observables as well.  However, users should
* note that Observables only notify their Observers
* of changes after their property has changed.
* EODelayedObservers would see no difference because
* they always receive their notification after all
* changes have taken place. <br><br>
*
* This implementation uses weak references for observers
* and observables.  The advantage to this approach is
* that you do not need to explicitly unregister observers
* or observables; they will be unregistered when they are
* garbage-collected.  Note that you will need to retain
* a reference to any objects you register or they may
* become unregistered if no other object references them.
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 894 $
*/
public class EOObserverCenter implements Observer
{
    /**
    * Would much rather use a WeakHashMap, but that class
    * compares by value, and we need to compare by reference.
    * This means we need to recreate a weak hashmap with
    * the ReferenceKey class below.  Using hashtable for
    * thread safety.
    */
	private static Map observableToObservers = new Hashtable();
    
	private static List omniscients = new LinkedList();
	
	// suppression count
	private static int suppressions = 0;
	
	// singleton instance - needed for Observer
	private static EOObserverCenter instance = null;
    
    // optimization: remember last request and result
    private static Object lastRequest;
    private static NSArray lastResult;
	
	/**
	* Registers the specified EOObserving for 
	* notifications from the specified object.
	* An EOObserving can only be registered 
	* once for a given object.
	*/
	public static void addObserver( 
		EOObserving anObserver, Object anObject )
	{
		// atomic operation
		synchronized ( instance() )
		{
			// find observer list
			List observers = (List) 
				observableToObservers.get( new ReferenceKey( anObject ) );
				
			// if observer list not found, create and add item
			if ( observers == null )
			{
				observers = new ArrayList();
				observers.add( new WeakReference( anObserver ) );
                processQueue();
				observableToObservers.put( new ReferenceKey( anObject, queue ), observers );

				// support for java.util.Observable
				if ( anObject instanceof Observable )
				{
					((Observable)anObject).addObserver( instance() );
				}
			}
			else // observer list found - scan for observer
			if ( indexOf( observers, anObserver ) < 0 )
			{
				// observer not found, register it
				observers.add( new WeakReference( anObserver ) );
			}
            
            lastRequest = null;
            lastResult = null;
		}
	}

	/**
	* Registers the specified EOObserving for notifications
	* on all object changes.  An EOObserving can be 
	* registered as an omniscient observer at most once.
	* Use omniscient observers with caution.
	*/
	public static void addOmniscientObserver(
		EOObserving anObserver )
	{
		if ( indexOf( omniscients, anObserver ) < 0 )
		{
			omniscients.add( anObserver );
		}
	}

	/**
	* Notifies all EOObservings registered for 
	* notifications for the specified object.
	* This method is typically called by objects
	* that wish to broadcast a notification before
	* a property change takes place, passing itself
	* as the argument.
	*/
	public static void notifyObserversObjectWillChange(
		Object anObject )
	{
		if ( observerNotificationSuppressCount() == 0 )
		{
			List observers = observersForObject( anObject );
			EOObserving o;
			Iterator it = observers.iterator();
			while ( it.hasNext() )
			{
				o = (EOObserving) it.next();
				o.objectWillChange( anObject );
			}
		}
	}

	/**
	* Returns an observer that is an instance of
	* the specified class and 
	* that is registered for notifications about 
	* the specified object.  If more than one
	* such observer exists, which observer is 
	* returned is undetermined - use 
	* observersForObject instead.  If no observer
	* exists, returns null.
	*/
	public static EOObserving observerForObject( 
		Object anObject, Class aClass )
	{
		List result = observersForObject( anObject );
		if ( result.size() == 0 ) return null;
		
		Object o;
		Iterator it = result.iterator();
		while ( it.hasNext() ) 
		{
			o = it.next();
			if ( aClass.isAssignableFrom( o.getClass() ) )
			{
				return (EOObserving) o;	
			}
		}
		return null;
	}

	/**
	* Returns the number of times that notifications
	* have been suppressed.  This is also the number
	* of times that enableObserverNotification must
	* be called to allow notifications to take place.
	*/
	public static int observerNotificationSuppressCount()
	{	
		return suppressions;
	}

	/**
	* Returns a List of observers for the 
	* specified object.  Returns an empty List
	* if no observer has registered for that
	* object.
	*/
	public static NSArray observersForObject(
		Object anObject )
	{
        synchronized ( instance() )
        {
            // optimization: this is called very frequently
            // from the same object calling willChange() a
            // number of times in a row as it is updating.
            if ( lastRequest == anObject )
            {
                return lastResult;
            }
            
            NSArray result;
            
            List references = observerListForObject( anObject );
            if ( references == null ) 
            {
                result = NSArray.EmptyArray;
            }
            else
            {
                result = new NSMutableArray();
                Object observer;
                Iterator it = references.iterator();
                while ( it.hasNext() )
                {
                    observer = ((Reference)it.next()).get();
                    if ( observer != null )
                    { 
                        result.add( observer );
                    }
                    else // reference has expired
                    {
                        processQueue();
                        it.remove(); // remove from list
                        // if last observer, unregister observable
                        if ( references.size() == 0 )
                        {
                            observableToObservers.remove( new ReferenceKey( anObject ) );
                        }
                    }
                }
            }
            
            lastRequest = anObject;
            lastResult = result;
            
            return result;
        }
        
	}
	
	/**
	* Returns a reference to the actual list of 
	* observers for the given object, or null if it
	* doesn't exist.
	*/ 
	private static List observerListForObject( Object anObject )
	{
		return (List) observableToObservers.get( new ReferenceKey( anObject ) );
	}

	/**
	* Unregisters the specified observer for
	* notifications from the specified object.
	*/
	public static void removeObserver( 
		EOObserving anObserver, Object anObject )
	{
		// atomic operation
		synchronized ( instance() )
		{
            lastRequest = null;
            lastResult = null;
            
			List result = observerListForObject( anObject );
			if ( result == null ) return;
			int index = indexOf( result, anObserver );
			if ( index == -1 ) return;
			
			// remove observer from list
			result.remove( index );
			
			// if last observer, unregister observable
			if ( result.size() == 0 )
			{
                processQueue();
				observableToObservers.remove( new ReferenceKey( anObject ) );
			}
		}
	}

	/**
	* Unregisters the specified omniscient observer.
	*/
	public static void removeOmniscientObserver(
		EOObserving anObserver )
	{
		int index = indexOf( omniscients, anObserver );
		if ( index != -1 )
		{
			omniscients.remove( index );	
		}
	}

	/**
	* Enables notifications after they have been
	* suppressed by suppressObserverNotification.
	* If notifications have been suppressed 
	* multiple times, this method must be called
	* an equal number of times to resume notifications.
	* If notifications are not currently suppressed,
	* this method does nothing.
	*/
	public static void enableObserverNotification()
	{
		if ( suppressions > 0 ) suppressions--;
	}

	/**
	* Causes notifications to be suppressed until
	* the next matching call to enableObserverNotification.
	* If this method is called more than once, 
	* enableObserverNotification must be called an
	* equal number of times for notifications to resume.
	* This method always causes notifications to cease 
	* immediately.
	*/
	public static void suppressObserverNotification()
	{
		suppressions++;
	}
	
	/**
	* Because we're comparing by reference, we need to 
	* test for the existence of the object directly.
	* @return the index or -1 if not found.
	*/
	private static int indexOf( List aList, Object anObject )
	{
        if ( anObject == null ) return -1;
        
		synchronized ( aList )
		{
			int len = aList.size();
			for ( int i = 0; i < len; i++ )
			{
				// compare by reference
				if ( anObject == ((Reference)aList.get(i)).get() )
				{
					return i;
				}
			}
		}
		return -1;
	}
	
	/**
	* Private singleton instance, so we can be an observer.
	*/
	private static EOObserverCenter instance() 
	{
		if ( instance == null )
		{
			instance = new EOObserverCenter();
		}
		return instance;
	}
	
	/**
	* Interface Observer
	*/	
	public void update( Observable o, Object arg )
	{
		notifyObserversObjectWillChange( o );
	}
    
    /* Reference queue for cleared WeakKeys */
    private static ReferenceQueue queue = new ReferenceQueue();

    /* Remove all invalidated entries from the map, that is, remove all entries
       whose keys have been discarded.  This method should be invoked once by
       each public mutator in this class.  We don't invoke this method in
       public accessors because that can lead to surprising
       ConcurrentModificationExceptions. */
    private static void processQueue() 
    {
        synchronized ( instance() )
        {
            ReferenceKey rk;
            while ((rk = (ReferenceKey)queue.poll()) != null) 
            {
                //System.out.println( "EOObserverCenter.processQueue: removing object" );
                observableToObservers.remove(rk);
            }
        }
    }

    /**
    * Private class used to force a hashmap to
    * perform key comparisons by reference.
    * Retains a weak reference just like WeakHashMap.
    */
    static private class ReferenceKey extends WeakReference
    {
        private int hashCode;
        
        /**
        * Called to create a disposable reference key,
        * used for retrieving values from the hashtable.
        */
        public ReferenceKey( Object anObject )
        {
            super( anObject );
            hashCode = anObject.hashCode();
        }
        
        /**
        * Called to create a reference key that will be 
        * used as a key in the hashtable, so we need the
        * reference queue to later remove the key from the
        * table when referred object is no longer in use.
        */
        public ReferenceKey( Object anObject, ReferenceQueue aQueue )
        {
            super( anObject, aQueue );
            hashCode = anObject.hashCode();
        }
        
        /**
        * Passes through to actual key's hash code.
        */
        public int hashCode()
        {
            return hashCode;   
        }
        
        /**
        * Compares by reference.
        */ 
        public boolean equals( Object anObject )
        {
            if ( ! ( anObject instanceof ReferenceKey ) ) return false;
            Object key = get();
            if ( key == null ) return false;
            return ( key == ((ReferenceKey)anObject).get() );
        }
    }
    
    private static String debugString()
    {
        String result = "";
        int count = 0;
		synchronized ( instance() )
		{
            Object anObject;
            Iterator it = observableToObservers.keySet().iterator();
            while ( it.hasNext() )
            {
                            result += ((Reference)it.next()).get() + " : ";    
                            count++;
                /*
                Iterator values = ((List)it.next()).iterator();
                while ( values.hasNext() )
                {
                    anObject = ((Reference)values.next()).get();
                    if ( anObject != null )
                    {
//                        if ( anObject instanceof net.wotonomy.ui.MasterDetailAssociation )
                            result += anObject.getClass().toString() + " : ";    
                            count++;
                    }
                }
                */
            }
            result += "["+count+"]";
		}
        return result;
    }
	
}

/*
 * $Log$
 * Revision 1.2  2006/02/16 16:47:14  cgruber
 * Move some classes in to "internal" packages and re-work imports, etc.
 *
 * Also use UnsupportedOperationExceptions where appropriate, instead of WotonomyExceptions.
 *
 * Revision 1.1  2006/02/16 13:19:57  cgruber
 * Check in all sources in eclipse-friendly maven-enabled packages.
 *
 * Revision 1.9  2002/10/24 18:18:12  mpowers
 * NSArray's are now considered read-only, so we can return our internal
 * representation to reduce unnecessary object allocation.
 *
 * Revision 1.8  2001/02/21 21:17:32  mpowers
 * Now retaining a reference to the recent changes observer.
 * Better documented need to retain reference.
 * Started implementing notifications.
 *
 * Revision 1.7  2001/02/17 16:52:05  mpowers
 * Changes in imports to support building with jdk1.1 collections.
 *
 * Revision 1.6  2001/02/05 18:45:45  mpowers
 * Reduced access back to private for utility methods.
 *
 * Revision 1.5  2001/02/05 18:42:32  mpowers
 * Updated documentation throughout project.
 *
 * Revision 1.4  2001/01/18 16:57:47  mpowers
 * Added debug facility.
 *
 * Revision 1.3  2001/01/10 16:28:53  mpowers
 * Implemented a compare-by-reference weak hashtable
 * because WeakHashMap compared by value and we can't
 * assume that display groups won't contain objects
 * whose values are equivalent.
 *
 * Revision 1.2  2001/01/09 20:10:19  mpowers
 * Now using weak references to track observables and their observers.
 *
 * Revision 1.1.1.1  2000/12/21 15:46:44  mpowers
 * Contributing wotonomy.
 *
 * Revision 1.8  2000/12/20 16:25:35  michael
 * Added log to all files.
 *
 *
 */