Name: dm26566 Date: 10/15/98


from the javadocs for JDK 1.2 beta 4:
-------------------------------------------------

public class AWTEventMulticaster
extends Object
implements ComponentListener, ContainerListener, FocusListener, KeyListener, MouseListener, MouseMotionListener,
WindowListener, ActionListener, ItemListener, AdjustmentListener, TextListener, InputMethodListener

A class which implements efficient and thread-safe multi-cast event dispatching for the AWT events defined in the java.awt.event
package. This class will manage an immutable structure consisting of a chain of event listeners and will dispatch events to those
listeners. Because the structure is immutable, it is safe to use this API to add/remove listeners during the process of an event
dispatch operation. An example of how this class could be used to implement a new component which fires "action" events:


 public myComponent extends Component {
     ActionListener actionListener = null;

     public void addActionListener(ActionListener l) {
           actionListener = AWTEventMulticaster.add(actionListener, l);
     }
     public void removeActionListener(ActionListener l) {
           actionListener = AWTEventMulticaster.remove(actionListener, l);
     }
     public void processEvent(AWTEvent e) {
         // when event occurs which causes "action" semantic
         if (actionListener != null) {
             actionListener.actionPerformed(new ActionEvent());
         }
 }

-------------------------------------------------

The processEvent method will always use a single,
valid version of the AWTEventMulticaster, but if
you look at the above example, you will see that
if two separate threads MODIFY the object with
concurrent addActionListener or
removeActionListener method calls, one of the
modifications may be lost. Consider the following
sequence:

THREAD1: Read the actionListener variable.
THREAD1: Call addActionListener; begin processing.
THREAD2: Read the actionListener variable.
THREAD2: Call addActionListener; begin processing.
THREAD1: Return from addActionListener.
THREAD1: Replace actionListener variable value.
THREAD2: Return from addActionListener.
THREAD2: Replace actionListener variable value.

The modification attempted by THREAD1 will be
silently ignored. If the myComponent class makes
the addActionListener and removeActionListener
methods synchronized, multithreaded updates to
the myComponent action listener list will be
safe.

The listeners defined in the Component.java file
properly synchronize modifications, for example:

-------------------------------------------------

    public synchronized void addComponentListener(ComponentListener l) {
        componentListener = AWTEventMulticaster.add(componentListener, l);
        newEventsOnly = true;
    }

-------------------------------------------------

Because of the thread-safe features mentioned in
the JDK documentation, it is not necessary to make
the processEvent method synchronized, which should
help performance quite a bit, but the modification
methods must be synchronized, contrary to what is
implied by the above documentation and the example
provided with it.

Users who program according to the current
documentation will experience intermittent
failures in their attempts to register and
de-register listeners.
(Review ID: 39215)
======================================================================