swingx-master/swingx-core/src/main/java/org/jdesktop/swingx/event/WeakEventListenerList.java
/*
 * $Id$
 *
 * Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle,
 * Santa Clara, California 95054, U.S.A. All rights reserved.
 *
 * 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, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
package org.jdesktop.swingx.event;

import java.io.Serializable;
import java.lang.ref.WeakReference;
import java.lang.reflect.Array;
import java.util.ArrayList;
import java.util.EventListener;
import java.util.List;

/**
 * A class that holds a list of EventListeners.  A single instance
 * can be used to hold all listeners (of all types) for the instance
 * using the list.  It is the responsibility of the class using the
 * EventListenerList to provide type-safe API (preferably conforming
 * to the JavaBeans spec) and methods which dispatch event notification
 * methods to appropriate Event Listeners on the list.
 * 
 * The main benefit that this class provides is that it releases
 * garbage collected listeners (internally uses weak references). <p>
 * 
 * PENDING: serialization support
 * 
 *
 * Usage example:
 *    Say one is defining a class that sends out FooEvents, and one wants
 * to allow users of the class to register FooListeners and receive 
 * notification when FooEvents occur.  The following should be added
 * to the class definition:
 * <pre>
 * EventListenerList listenerList = new EventListenerList();
 * FooEvent fooEvent = null;
 *
 * public void addFooListener(FooListener l) {
 *     listenerList.add(FooListener.class, l);
 * }
 *
 * public void removeFooListener(FooListener l) {
 *     listenerList.remove(FooListener.class, l);
 * }
 *
 *
 * // Notify all listeners that have registered interest for
 * // notification on this event type.  The event instance 
 * // is lazily created using the parameters passed into 
 * // the fire method.
 *
 * 
 * protected void fireFooXXX() {
 *     // Guaranteed to return a non-null array
 *     FooListener[] listeners = listenerList.getListeners(FooListener.class);
 *     // Process the listeners last to first, notifying
 *     // those that are interested in this event
 *     for (FooListener listener: listeners) {
 *             // Lazily create the event:
 *             if (fooEvent == null)
 *                 fooEvent = new FooEvent(this);
 *             listener.fooXXX(fooEvent);
 *         }
 *     }
 * }
 * </pre>
 * foo should be changed to the appropriate name, and fireFooXxx to the
 * appropriate method name.  One fire method should exist for each
 * notification method in the FooListener interface.
 * <p>
 * <strong>Warning:</strong>
 * Serialized objects of this class will not be compatible with
 * future Swing releases. The current serialization support is
 * appropriate for short term storage or RMI between applications running
 * the same version of Swing.  As of 1.4, support for long term storage
 * of all JavaBeans<sup><font size="-2">TM</font></sup>
 * has been added to the <code>java.beans</code> package.
 * Please see {@link java.beans.XMLEncoder}.
 *
 * @version 1.37 11/17/05
 * @author Georges Saab
 * @author Hans Muller
 * @author James Gosling
 */
public class WeakEventListenerList implements Serializable {

    protected transient List<WeakReference<? extends EventListener>> weakReferences;
    protected transient List<Class<? extends EventListener>> classes;
    
    /**
     * Passes back the event listener list as an array
     * of ListenerType-listener pairs.  
     * As a side-effect, cleans out any 
     * garbage collected listeners before building the array.
     * 
     * @return a array of listenerType-listener pairs.
     */
    public Object[] getListenerList() {
        List<? extends EventListener> listeners = cleanReferences();
        Object[] result = new Object[listeners.size() * 2];
        for (int i = 0; i < listeners.size(); i++) {
            result[2*i + 1] = listeners.get(i);
            result[2*i] = getClasses().get(i);
        }
        return result;
    }

    /**
     * Returns a list of strongly referenced EventListeners. Removes
     * internal weak references to garbage collected listeners.
     * 
     * @return
     */
    @SuppressWarnings("unchecked")
    private synchronized <T extends EventListener> List<T> cleanReferences() {
        List<T> listeners = new ArrayList<T>();
        for (int i = getReferences().size() - 1; i >= 0; i--) {
            
            Object listener = getReferences().get(i).get();
            if (listener == null) {
                getReferences().remove(i);
                getClasses().remove(i);
            } else {
                listeners.add(0, (T) listener);
            }
        }
        return listeners;
    }
    
    private List<WeakReference<? extends EventListener>> getReferences() {
        if (weakReferences == null) {
            weakReferences = new ArrayList<WeakReference<? extends EventListener>>();
        }
        return weakReferences;
    }
    
    private List<Class<? extends EventListener>> getClasses() {
        if (classes == null) {
            classes = new ArrayList<Class<? extends EventListener>>();
            
        }
        return classes;
    }
    /**
     * Return an array of all the listeners of the given type. 
     * As a side-effect, cleans out any 
     * garbage collected listeners before building the array.
     * @return all of the listeners of the specified type. 
     * @exception  ClassCastException if the supplied class
     *          is not assignable to EventListener
     * 
     * @since 1.3
     */
    @SuppressWarnings("unchecked")
    public <T extends EventListener> T[] getListeners(Class<T> t) {
        List<T> liveListeners = cleanReferences();
        List<T> listeners = new ArrayList<T>();
        for (int i = 0; i < liveListeners.size(); i++) {
            if (getClasses().get(i) == t) {
                listeners.add(liveListeners.get(i));
            }
        }
        T[] result = (T[])Array.newInstance(t, listeners.size()); 
        return listeners.toArray(result);
    }

    /**
     * Adds the listener as a listener of the specified type.
      * As a side-effect, cleans out any garbage collected
     * listeners before adding.
    * @param t the type of the listener to be added
     * @param l the listener to be added
     */
    public synchronized <T extends EventListener> void add(Class<T> t, T l) {
        if (l==null) {
            // In an ideal world, we would do an assertion here
            // to help developers know they are probably doing
            // something wrong
            return;
        }
        if (!t.isInstance(l)) {
            throw new IllegalArgumentException("Listener " + l +
                                         " is not of type " + t);
        }
        cleanReferences();
        getReferences().add(new WeakReference<T>(l));
        getClasses().add(t);
    }

    /**
     * Removes the listener as a listener of the specified type.
     * @param t the type of the listener to be removed
     * @param l the listener to be removed
     */
    public synchronized <T extends EventListener> void remove(Class<T> t, T l) {
        if (l ==null) {
            // In an ideal world, we would do an assertion here
            // to help developers know they are probably doing
            // something wrong
            return;
        }
        if (!t.isInstance(l)) {
            throw new IllegalArgumentException("Listener " + l +
                                         " is not of type " + t);
        }
        for (int i = 0; i < getReferences().size(); i++) {
           if (l.equals(getReferences().get(i).get()) && 
                   (t == getClasses().get(i))) {
               getReferences().remove(i);
               getClasses().remove(i);
               break;
           }
        }
    }

//    // Serialization support.  
//    private void writeObject(ObjectOutputStream s) throws IOException {
//        Object[] lList = listenerList;
//        s.defaultWriteObject();
//        
//        // Save the non-null event listeners:
//        for (int i = 0; i < lList.length; i+=2) {
//            Class t = (Class)lList[i];
//            EventListener l = (EventListener)lList[i+1];
//            if ((l!=null) && (l instanceof Serializable)) {
//                s.writeObject(t.getName());
//                s.writeObject(l);
//            }
//        }
//        
//        s.writeObject(null);
//    }
//
//    private void readObject(ObjectInputStream s) 
//        throws IOException, ClassNotFoundException {
//        listenerList = NULL_ARRAY;
//        s.defaultReadObject();
//        Object listenerTypeOrNull;
//        
//        while (null != (listenerTypeOrNull = s.readObject())) {
//            ClassLoader cl = Thread.currentThread().getContextClassLoader();
//            EventListener l = (EventListener)s.readObject();
//            add((Class<EventListener>)Class.forName((String)listenerTypeOrNull, true, cl), l);
//        }           
//    }

//    /**
//     * Returns a string representation of the EventListenerList.
//     */
//    public String toString() {
//        Object[] lList = listenerList;
//        String s = "EventListenerList: ";
//        s += lList.length/2 + " listeners: ";
//        for (int i = 0 ; i <= lList.length-2 ; i+=2) {
//            s += " type " + ((Class)lList[i]).getName();
//            s += " listener " + lList[i+1];
//        }
//        return s;
//    }
}
