path: root/projects/net.wotonomy.foundation/src/main/java/net/wotonomy/foundation/NSNotificationCenter.java

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

import java.lang.ref.ReferenceQueue;
import java.lang.ref.WeakReference;
import java.util.Hashtable;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import java.util.Map;
import java.util.Vector;

import net.wotonomy.foundation.internal.WotonomyException;

/**
* NSNotificationCenter broadcasts NSNotifications to
* registered observers.  Observers can register for all
* notifications of a specific type, or all notifications
* about a specific object, or both.  Observers specify 
* the method that will be called when they are notified.
* A global notification center can be accessed with 
* defaultCenter(), but other centers can be created and
* used independently of the default center. <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: 893 $
*/
public class NSNotificationCenter
{
    /** 
    * Null marker class simplifies equals() logic
    * for CompoundKey class below.  
    */
    public static final Object NullMarker = new Object();    
  
    private static NSNotificationCenter defaultCenter = null;
    
    /**
    * A Map of (name,object) pairs to a List 
    * of (observer,selector) pairs.
    */
    private Hashtable observers; // thread-safe
    
    /**
    * Default constructor creates a new notification center.
    */
    public NSNotificationCenter()
    {
        observers = new Hashtable();
    }
    
    /**
    * Returns the system default center, creating one
    * if it has not yet been created.
    */
    static public NSNotificationCenter defaultCenter()
    {
        if ( defaultCenter == null )
        {
            defaultCenter = new NSNotificationCenter();   
        }
        return defaultCenter;
    }
	
	/**
	* Addes the specified observer to the notification queue for
	* notifications with the specified name or the specified 
	* object or both.
	* @param anObserver The observer that wishes to be notified.
	* @param aSelector The selector that will be invoked.  
	* Must have exactly one argument, to which a notification
	* will be passed.
	* @param notificationName The name of the notifications for
	* which the observer will be notified.  If null, will notify
	* only based on matching anObject.
	* @param anObject The object of the notifications for which
	* the observer will be notified.  If null, will notify 
	* only based on matching notificationName.
	*/
	public void addObserver(
		Object anObserver, NSSelector aSelector,
		String notificationName, Object anObject )
    {
        // remove freed objects
        processKeyQueue();
        
        Object name = notificationName;
        if ( name == null )
        {
            name = NullMarker;
        }
        if ( anObject == null )
        {
            anObject = NullMarker;
        }
        Object key = new CompoundKey( name, anObject );
        Object value = new CompoundValue( anObserver, aSelector );
        List list = (List) observers.get( key );
        if ( list == null )
        {
            // create new list with value and put it in map
            list = new Vector(); // thread-safe
            list.add( value );
            observers.put( new CompoundKey( 
                name, anObject, keyQueue ), list );
        }
        else
        {
            // add only if not already in list
            if ( ! list.contains( value ) )
            {
                list.add( value );   
            }
        }
    }
	
	/**
	* Posts the specified notification.  Notifies all registered
	* observers that match either the notification name or 
	* the notification object, or both.
	* @param aNotification The notification that will be passed
	* to the observers selector.
	*/
	public void postNotification(
		NSNotification aNotification )
    {
        List mergedList = new LinkedList();
        Object key, observerList;
        
        Object name = aNotification.name();
        Object object = aNotification.object();
        
        if ( name != null ) 
        {
            if ( object != null ) 
            { // both are specified
                observerList = observers.get( new CompoundKey( name, object ) );
                if ( observerList != null )
                {
                    mergedList.addAll( (List) observerList );
                }
                observerList = observers.get( new CompoundKey( name, NullMarker ) );
                if ( observerList != null )
                {
                    mergedList.addAll( (List) observerList );
                }
                observerList = observers.get( new CompoundKey( NullMarker, object ) );
                if ( observerList != null )
                {
                    mergedList.addAll( (List) observerList );
                }
            }
            else 
            { // object is null
                observerList = observers.get( new CompoundKey( name, NullMarker ) );
                if ( observerList != null )
                {
                    mergedList.addAll( (List) observerList );
                }
            }
        }
        else
        if ( object != null ) 
        { // name is null
            observerList = observers.get( new CompoundKey( NullMarker, object ) );
            if ( observerList != null )
            {
                mergedList.addAll( (List) observerList );
            }
        }

        key = new CompoundKey(
            NullMarker, NullMarker );
        observerList = observers.get( key );
        if ( observerList != null )
        {
            mergedList.addAll( (List) observerList );
        }

        CompoundValue value;
        Iterator it = mergedList.iterator();
        while ( it.hasNext() )
        {
            value = (CompoundValue) it.next();
            if ( value.get() == null )
            {
                it.remove();
            }
            else
            {
                try
                {
                    value.selector().invoke( 
                        value.get(), 
                        new Object[] { aNotification } );
                }
                catch ( Exception exc )
                {
                    WotonomyException w = new WotonomyException(
                        "Error notifying object: " + value.get() + " : " + aNotification, exc );
//                    throw w;
                    w.printStackTrace();
postNotification( "Error notifying object", this, new NSDictionary( "exception", w ) );
                }
            }
        }
        
    }
	
	/**
	* Posts a notification created from the specified name
	* and object.  Calls postNotification( NSNotification ).
	* @param notificationName a String key to distinguish
	* this notification.
	* @param anObject any object, by convention this is 
	* the originator of the notification.
	*/
	public void postNotification(
		String notificationName, Object anObject )
    {
        postNotification( new NSNotification( 
            notificationName, anObject ) );
    }
	
	/**
	* Posts a notification created from the specified name,
	* object, and info.  Calls postNotification( NSNotification ).
	* @param notificationName a String key to distinguish
	* this notification.
	* @param anObject any object, by convention this is 
	* the originator of the notification.
	* @param userInfo a Map containing information specific
	* to the originator of the notification and that may
	* be of interest to a knowledgable observer.
	*/
	public void postNotification(
		String notificationName, Object anObject, Map userInfo )
    {
        postNotification( new NSNotification( 
            notificationName, anObject, userInfo ) );
    }
	
	/**
	* Unregisters the specified observer from all notification
	* queues for which it is registered. 
	* @param anObserver The observer to be unregistered.
	*/
	public void removeObserver(
		 Object anObserver )
    {
        // remove freed objects
        processKeyQueue();
        
        Iterator it = new LinkedList( observers.keySet() ).iterator();
        while ( it.hasNext() )
        {
            removeObserver( anObserver, it.next() );
        }
    }
	
	/**
	* Unregisters the specified observer from all notifications
	* queues associated with the specified name or object or both.
	* @param anObserver The observer to be unregistered, if null
	* will unregister all observers for the specified notification
	* name and object.
	* @param notificationName The name of the notification for which
	* the observer will be unregistered, if null will unregister
	* the specified observer for all notifications with the 
	* specified object.
	* @param anObject The object for the notification for which
	* the observer will be unregistered, if null will unregister 
	* the specified observer for all objects with the specified
	* notification.
	*/
	public void removeObserver(
		Object anObserver, String notificationName, Object anObject )
    {
        // remove freed objects
        processKeyQueue();
        
        // get key matches
        List keys = matchingKeys( notificationName, anObject );
        
        // remove specified observer from each matching key
        Iterator it = keys.iterator();
        while ( it.hasNext() )
        {
            removeObserver( anObserver, it.next() );               
        }
    }
    
    /**
    * Returns all keys that match the specified name and object,
    * but in this case null parameters are considered wildcards.
    * Pass NullMarkers if you want to explicitly match nulls.
    */
    private List matchingKeys( String name, Object object )
    {
        List result = new LinkedList();

        boolean willAdd;
        CompoundKey key;
        Iterator it = observers.keySet().iterator();
        while ( it.hasNext() )
        {
            key = (CompoundKey) it.next();
            willAdd = false;
            if ( ( name == null ) || ( name == key.name() ) )
            {
                if ( ( object == null ) || ( object == key.get() ) )
                {
                    willAdd = true;   
                }
            }
            if ( willAdd )
            {
                result.add( key );   
            }
        }
        return result;
    }
    
    /**
    * Removes the specified observer from the list referenced
    * by the specified key in the observer map.
    */
    private void removeObserver( 
        Object anObserver, Object key )
    {
        // if observer null, remove all observers for key
        if ( anObserver == null )
        {
            observers.remove( key );
            return;
        }
        
        List list = (List) observers.get( key );
        if ( list == null ) return;

        // remove specified observer from list
        Object observer;
        Iterator it = list.iterator();
        while ( it.hasNext() )
        {
            observer = ((CompoundValue)it.next()).get();
            if ( ( observer == null ) || ( anObserver == observer ) )
            {
                // remove if match or freed object
                it.remove();   

                // do not return; process entire list
            }
        }
        if ( list.size() == 0 )
        {
            observers.remove( key );       
        }
    }

    /* Reference queues for cleared WeakKeys */
    private ReferenceQueue keyQueue = new ReferenceQueue();
       
    /**
    * Removes any keys whose object has been garbage collected.
    * (Garbage collected values are removed as they are encountered.)
    */       
    private void processKeyQueue() 
    {
        CompoundKey ck;
        while ((ck = (CompoundKey)keyQueue.poll()) != null) 
        {
            //System.out.println( "EOObserverCenter.processQueue: removing object" );
            observers.remove(ck);
        }
    }
   
    /**
    * Key combining a name with an object.
    * The object is weakly referenced, and keys
    * are deallocated by reference queue.
    * equals() compares by reference.
    */ 
    private static class CompoundKey extends WeakReference
    {
        private Object name;
        private int hashCode;
        
        /**
        * Creates compound key.  
        * Neither name nor object may be null.
        * Use NullMarker to represent null
        * in either name or object.
        */
        public CompoundKey ( 
            Object aName, Object anObject )
        {
            super( anObject );
            name = aName;
            hashCode = aName.hashCode() + anObject.hashCode();
        }
        
        /**
        * Creates compound key with queue.
        * Neither name nor object may be null.
        * Use NullMarker to represent null
        * in either name or object.
        */
        public CompoundKey ( 
            Object aName, Object anObject, ReferenceQueue aQueue )
        {
            super( anObject, aQueue );
            name = aName;
            hashCode = aName.hashCode() + anObject.hashCode();
        }
        
        public Object name()
        {
            return name;
        }
        
        public int hashCode()
        {
            return hashCode;
        }
        
        public boolean equals( Object anObject )
        {
            if ( this == anObject ) return true;
            // assumes only used with other compound keys
            CompoundKey key = (CompoundKey) anObject;
            if ( name == key.name || ( name != null && name.equals( key.name ) ) )
            {
                Object object = get();
                if ( object != null )
                {
                    // compares by reference
                    if ( object == ( key.get() ) )
                    {
                        return true;   
                    }
                }
            }
            return false;
        }
        
        public String toString()
        {
            return "[CompoundKey:"+name()+":"+get()+"]";   
        }
    }
	
    /**
    * Value combining an object with a selector.
    * The object is weakly referenced, and null
    * values are not allowed.
    */ 
    private static class CompoundValue extends WeakReference
    {
        private NSSelector selector;
        private int hashCode;
        
        public CompoundValue( Object anObject, NSSelector aSelector )
        {
            super( anObject );
            hashCode = anObject.hashCode();
            selector = aSelector;
        }
        
        public NSSelector selector()
        {
            return selector;
        }
        
        public int hashCode()
        {
            return hashCode;
        }
        
        public boolean equals( Object anObject )
        {
            if ( this == anObject ) return true;
            // assumes only used with other compound values
            CompoundValue value = (CompoundValue) anObject;
            if ( selector == value.selector || 
               ( selector != null && selector.equals( value.selector ) ) )
            {
                Object object = get();
                if ( object != null )
                {
                    if ( object == value.get() )
                    {
                        return true;   
                    }
                }
            }
            return false;
        }

        public String toString()
        {
            return "[CompoundValue:"+get()+":"+selector().name()+"]";   
        }
    }
/*
    public static void main( String[] argv )
    {
        Object aSource = "aSource";
        Object bSource = "bSource";
        
        Object oneTest = new OneTest();
        Object twoTest = new TwoTest();
        NSSelector notifyMeOnce = 
            new NSSelector( "notifyMeOnce", 
            new Class[] { NSNotification.class } );
        NSSelector notifyMeTwice = 
            new NSSelector( "notifyMeTwice", 
            new Class[] { NSNotification.class } );
            
        NSNotificationCenter.defaultCenter().addObserver(
            oneTest, notifyMeOnce, "aMessage", null );
            
        NSNotificationCenter.defaultCenter().addObserver(
            oneTest, notifyMeOnce, null, aSource );
            
        NSNotificationCenter.defaultCenter().addObserver(
            twoTest, notifyMeOnce, "aMessage", aSource );
            
        NSNotificationCenter.defaultCenter().addObserver(
            twoTest, notifyMeTwice, null, null );
            
        NSNotificationCenter.defaultCenter().postNotification(
            "aMessage", aSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "aMessage", bSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "bMessage", aSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "bMessage", bSource );
        System.out.println( "---" );
        
        NSNotificationCenter.defaultCenter().removeObserver( 
            oneTest, null, aSource );

        NSNotificationCenter.defaultCenter().postNotification(
            "aMessage", aSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "aMessage", bSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "bMessage", aSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "bMessage", bSource );
        System.out.println( "---" );

        NSNotificationCenter.defaultCenter().removeObserver( 
            null );

        NSNotificationCenter.defaultCenter().postNotification(
            "aMessage", aSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "aMessage", bSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "bMessage", aSource );
        System.out.println();
        NSNotificationCenter.defaultCenter().postNotification(
            "bMessage", bSource );
        System.out.println( "---" );
    }
    
    static private class OneTest
    {
        public void notifyMeOnce( NSNotification aNotification )
        {
            System.out.println( "OneTest.notifyMeOnce: " + aNotification );   
        }
    }

    static private class TwoTest
    {
        public void notifyMeOnce( NSNotification aNotification )
        {
            System.out.println( "TwoTest.notifyMeOnce: " + aNotification );   
        }
        public void notifyMeTwice( NSNotification aNotification )
        {
            System.out.println( "TwoTest.notifyMeTwice: " + aNotification );   
        }
    }
*/
}



/*
 * $Log$
 * Revision 1.2  2006/02/16 13:15:00  cgruber
 * Check in all sources in eclipse-friendly maven-enabled packages.
 *
 * Revision 1.11  2003/06/03 14:51:15  mpowers
 * Added commented-out println for debugging.
 *
 * Revision 1.10  2003/03/27 21:46:00  mpowers
 * Better handling for null parameters on subscribe.
 * Better handling for null parameters on post.
 *
 * Revision 1.9  2003/01/28 19:44:38  mpowers
 * Now comparing strings by value not reference.
 *
 * Revision 1.8  2001/06/29 16:14:23  mpowers
 * Fixed a javac compiler error that jikes allowed: shoe's on the other foot!
 *
 * Revision 1.7  2001/06/07 22:09:03  mpowers
 * Exceptions during a notification are no longer being thrown
 * so we can assure that all notifications get handled.
 * Instead, we're printing stack traces...
 *
 * Revision 1.6  2001/04/09 21:41:50  mpowers
 * Better debugging.
 *
 * Revision 1.5  2001/03/15 21:09:06  mpowers
 * Fixed notifications with null objects.
 *
 * Revision 1.4  2001/02/21 21:18:34  mpowers
 * Clarified need to retain references.
 *
 * Revision 1.3  2001/02/21 18:31:07  mpowers
 * Finished and tested implementation of NSNotificationCenter.
 *
 * Revision 1.1.1.1  2000/12/21 15:47:39  mpowers
 * Contributing wotonomy.
 *
 * Revision 1.3  2000/12/20 16:25:38  michael
 * Added log to all files.
 *
 *
 */