Event Listening and Event Bubbling

Event Listening and Event Bubbling
An Introduction with Examples in Java

Prof. David Bernstein
James Madison University

Computer Science Department

bernstdh@jmu.edu

Event Queue

Role:
- Central repository for all events
Variants:
- Event listening
- Event bubbling

Using an Event Queue

Variants

Event Listening

Event Bubbling

Implementation: Event

One Simple Implementation

javaexamples/eventbased/Event.java

        /**
 * An encapsulation of an Event
 *
 * This implementation is generic so that the two
 * variants, event listening and event bubbling, can
 * have their own type of Event.
 *
 * The type parameter, S, is used to bind the type of the 
 * source.  It can be either EventGenerator  (for event 
 * listening) or EventHandler (for event bubbling).
 *
 * This class has package visibility to prevent it
 * from being typed inappropriately in classes
 * outside of this package.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
class Event<S>
{
    private S          source;
    private String     name, value;
    

    /**
     * Explicit Value Constructor
     *
     * @param source   The source of this Event
     * @param name     The name of this Event
     * @param value    The value of this Event
     */
    public Event(S source, String name, String value)
    {
       this.source = source;
       this.name   = name;
       this.value  = value;       
    }


    /**
     * Get the source of this Event
     *
     * @return    The source
     */
    protected S getSource()
    {
       return source;       
    }


    /**
     * Get the name of this Event
     *
     * @return    The name
     */
    public String getName()
    {
       return name;       
    }


    /**
     * Get the value of this Event
     *
     * @return    The value
     */
    public String getValue()
    {
       return value;       
    }
}

Implementation: Event Queue

javaexamples/eventbased/EventQueue.java

(Fragment: skeleton)

        import java.util.*;

/**
 * The core functionality of all event queues
 *
 * This implementation is generic so that the two
 * variants, ListenerEventQueue and BubblingEventQueue,
 * can used different types of Event objects (ListenerEvent 
 * and BubblingEvent objects, respectively).
 *
 * The type parameter, E, is used to bind the type of the 
 * Event.
 *
 * This class has package visibility to prevent it
 * from being typed inappropriately in classes
 * outside of this package.
 *
 * Note: Concrete implementations of this class 
 *       need to implement the fireEvent method.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
abstract class EventQueue<E> implements Runnable
{
    private   volatile boolean         keepRunning;
    protected          LinkedList<E>   events;
    private            Thread          controlThread;
    private   final    Object          lock = new Object();



    /**
     * Default Constructor
     */
    protected EventQueue()
    {
       events     = new LinkedList<E>();
    }

    /**
     * Start the event queue
     */
    public void start()
    {
       if (controlThread == null)
       {
          keepRunning   = true;
          controlThread = new Thread(this);
          
          controlThread.start();
       }
    }


    /**
     * Stop the event queue (after all events have 
     * been processed)
     */
    public void stopEventQueue()
    {
       synchronized(lock)
       {
          keepRunning   = false;
          controlThread.interrupt();          
       }
    }
}

javaexamples/eventbased/EventQueue.java

(Fragment: fire)

        
    /**
     * Fire an event
     *
     * Note: The code in this method does not need to be
     * synchronized because it is protected and is only
     * called by firePendingEvents() which is called by
     * a synchronized block in run()
     *
     * @param event   The event to fire
     */
    protected abstract void fireEvent(E event);

    /**
     * Fire all pending events
     *
     * Note: The code in this method does not need to be
     * synchronized because it is private and is only
     * called by a synchronized block in run()
     */
    private void firePendingEvents()
    {
       E    event;
   
       while (events.size() > 0)
       {
          event = events.removeFirst();
          fireEvent(event);
       }
    }

javaexamples/eventbased/EventQueue.java

(Fragment: run)

        
    /**
     * The code to execute in the control thread
     */
    public void run()
    {
       Event     event;

       while (keepRunning) 
       {
          synchronized(lock)
          {
             firePendingEvents();
              
             try
             {
                lock.wait();
             }
             catch (InterruptedException ie)
             {
                // stop() was called
             }
          }
       }
       controlThread = null;        
    }

javaexamples/eventbased/EventQueue.java

(Fragment: postEvent)

        
    /**
     * Push an event onto the queue
     *
     * @param event   The event to post
     */
    protected void postEvent(E event)
    {
       synchronized(lock)
       {
          // Add an event to the queue
          events.addLast(event);

          // Start the processing
          lock.notifyAll();
       }
    }

Event Listening

Overview

Event Listenening (cont.)

ListenerEvent

javaexamples/eventbased/ListenerEvent.java

        /**
 * A simple encapsulation of an Event in an event 
 * listener system
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class ListenerEvent extends Event<EventGenerator>
{
    /**
     * Explicit Value Constructor
     *
     * @param source   The source of this Event
     * @param name     The name of this Event
     * @param value    The value of this Event
     */
    public ListenerEvent(EventGenerator source, 
                         String name, 
                         String value)
    {
       super(source, name, value);
    }
}

Event Listenening (cont.)

EventListener

javaexamples/eventbased/EventListener.java

        /**
 * Requirements of an EventListener in an
 * event listener system
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public interface EventListener extends EventReceiver
{
    /**
     * Handle an event
     *
     * @param event   The Event to handle
     * @return        true if the Event was handled
     */
    public abstract boolean handleEvent(ListenerEvent event);

}

Event Listenening (cont.)

ListenerEventQueue