Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class ncsa.horizon.util.EventMulticaster

java.lang.Object
  |
  +--ncsa.horizon.util.EventMulticaster

Subclasses:

EngageDatasetMulticaster, EngageSliceMulticaster

public abstract class EventMulticaster

extends java.lang.Object

implements java.util.EventListener, java.lang.Cloneable

an abstract class for delivering a specific event to a collection of listeners.

This class provides the basic accounting infrastructure for managing group of listeners efficiently as a linked list in a manner similar to the java.awt.AWTEventMulticaster. It provides methods for adding and removing listeners as well as a simple, efficient framework for distributing the events to those listeners via a single method call.

An EventMulticaster works by keeping a reference to a single listener (the mine field) and a reference to another EventMulticaster represending a chain of the remaining listeners (the next field. Distribution is done by implementing the relevent listener interface methods so as to send the event first to the mine listener and then to the next via the same methods. An example is given below.

Suppose that you have created a new event called MyEvent and a listener interface called MyEventListener. Suppose further that MyGUI will generate these events; typically in this class, you would provide addMyEventListener() and removeMyEventListener() methods to allow other objects to listen for these events. This EventMulticaster can make managing the listeners and sending them events easy and efficient.

1. Make sure your MyEventListener interface extends the java.util.EventListener interface.

    public interface MyEventListener extends java.util.EventListener {
        public abstract handleMyEvent(MyEvent e);
    }
    

2. Extend the EventMulticaster class and have it implement your MyEventListener interface. For this example, suppose that you call the new class MyEventMulticaster; thus:

    public class MyEventMulticaster extends EventMulticaster
        implements EngageSliceListener
    {
        // Duplicate the superclass's constructors
        public MyEventMulticaster() { }
        public MyEventMulticaster(MyEventListener mel) { super(mel); }
        protected EngageSliceMulticaster(EngageSliceListener esl, Object lock) {
            super(esl, lock);
        } 
   
   
        // Duplicate the add/removeListener methods
        public void addListener(MyEventListener esl) { 
            super.addListener(esl); 
        }
        public void removeListener(MyEventListener esl) { 
   	   super.removeListener(esl); 
        } 
   
    
        // Implement the newInstance() method via the protected constructor
        protected EventMulticaster newInstance(EventListener vl, Object lock) {
            return new MyEventMulticaster((MyEventListener) vl, lock);
        }  
   
    
        // Implement your listener interface's methods.  
        public void handleMyEvent(MyEvent e) {
            if (mine != null) {
                ((MyEventListener) mine).handleMyEvent(event);
                if (next != null) 
                    ((MyEventListener) next).handleMyEvent(event);
            }
        }
    }
    

3. In your class that generates events, delegate the management of listeners to your new multicaster class:

    public class MyGUI extends Panel { 
   
   
        protected listeners = null; 
   
        
        public void addMyEventListener(MyEventListener mel) {
            if (listeners == null) 
                listeners = new MyEventMulticaster(mel);
            else 
                listeners.addListener(mel);
        } 
   
   
        public void removeMyEventListener(MyEventListener mel) {
            if (listeners != null) listeners.removeListener(mel);
        } 
   
   
        ...
    }
    

4. When you need to alert your listeners with an event, pass it through the multicaster:

            if (listeners != null) 
                listeners.handleMyEvent(new MyEvent(...));
    

See Also:

EngageSliceMulticaster, EngageSliceAction, EngageSliceListener, java.awt.AWTEventMulticaster

Field Summary

EventMulticaster	last the last link in this chain.
java.lang.Object	lock an object to use as a lock for methods requiring synchronization.
java.util.EventListener	mine the listener held in this link of the chain
EventMulticaster	next the handle to the next link in the chain

Constructor Summary

EventMulticaster()
create an empty chain of EventListeners

EventMulticaster(java.util.EventListener vl)
create a single link chain of EventListeners.

EventMulticaster(java.util.EventListener vl, java.lang.Object lock)
create a single link chain of EventListeners.

Method Summary

void	addListener(java.util.EventListener vl) add a EventListener of this object.
java.lang.Object	clone() clone this chain (but not the actual listeners)
boolean	contains(java.util.EventListener vl) return true if a given listener is in this chain
EventMulticaster	newInstance(java.util.EventListener vl, java.lang.Object lock) wrap a new instance of this EventListener around a listener.
void	removeAllListeners() remove all listeners from this Multicaster and dissolve the chain.
void	removeListener(java.util.EventListener vl) remove a EventListener of this object

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notifyAll, notify, toString, wait, wait, wait

Field Detail

mine

protected java.util.EventListener mine

the listener held in this link of the chain

next

protected EventMulticaster next

the handle to the next link in the chain

last

protected EventMulticaster last

the last link in this chain. This will only be valid if this is the first link in the chain.

lock

protected java.lang.Object lock

an object to use as a lock for methods requiring synchronization.

Constructor Detail

EventMulticaster

public EventMulticaster()

create an empty chain of EventListeners

EventMulticaster

public EventMulticaster(java.util.EventListener vl)

create a single link chain of EventListeners.

EventMulticaster

protected EventMulticaster(java.util.EventListener vl,
                           java.lang.Object lock)

create a single link chain of EventListeners. This is the wrapper constructor: it wraps a new EventMulticaster around a single listener. An overriden version of this constructor is normally only used by the newInstance() method.

Parameters:

vl - the listener to wrap

lock - an object to use as a lock

Method Detail

newInstance

protected abstract EventMulticaster newInstance(java.util.EventListener vl,
                                                java.lang.Object lock)

wrap a new instance of this EventListener around a listener.

If the implementing subclass is called MyEventMulticaster and supports the MyEventListener interface, it would simply implement this method by calling its wrapper constructor; e.g:

  protected EventMulticaster newInstance(EventListener vl, Object lock) {
      return new MyEventMulticaster((MyEventListener) vl, lock);
  }
 

Parameters:

vl - the event listener to wrap

lock -

addListener

protected void addListener(java.util.EventListener vl)

add a EventListener of this object. This method ensures that no listener is added more than once.

removeListener

protected void removeListener(java.util.EventListener vl)

remove a EventListener of this object

contains

public boolean contains(java.util.EventListener vl)

return true if a given listener is in this chain

removeAllListeners

public void removeAllListeners()

remove all listeners from this Multicaster and dissolve the chain.

clone

public java.lang.Object clone()

clone this chain (but not the actual listeners)

Overrides:

clone in class java.lang.Object