org.eidola.kernel.event
Class EventBroadcaster

java.lang.Object
  |
  +--org.eidola.kernel.event.EventBroadcaster

Direct Known Subclasses:

Container

public class EventBroadcaster

extends Object

A source of Eidola Events. Implementors of the EventListener interface can register themselves with an EventBroadcaster via addListener(). When registering, the new listener must specify an EventQueue. When an EventBroadcaster sends out an event (through a call to broadcastEvent()), the registered EventListeners receive it on their respective EventQueues.

Eidola allows associates different listeners with potentially different queues in order to encourage multithreading. Each queue can run on a different thread (or ThreadFlock). So, for example, three threads can compile elements while another thread concurrently updates their display in a UI.

Version:

[Development version]

Author:

Paul Cantrell

See Also:

Event, EventListener, EventQueue

Field Summary

static boolean

debugEvents

Constructor Summary

EventBroadcaster()
Create a new broadcaster with no listeners.

Method Summary

void	addListener(EventListener listener, EventQueue queue) Registers a listener with this broadcaster.
void	broadcastEvent(Event event) Broadcasts an event to all registered listeners on their respective queues.
void	removeListener(EventListener listener) Unregisters a listener with this broadcaster.
static void	updateBroadcasters(EventListener listener, EventQueue eventq, Collection oldBroadcasters, Collection newBroadcasters) A utility method to make a broadcaster's listeners mirror a changing collection.

Methods inherited from class java.lang.Object

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

Field Detail

debugEvents

public static boolean debugEvents

Constructor Detail

EventBroadcaster

public EventBroadcaster()

Create a new broadcaster with no listeners.

Method Detail

addListener

public void addListener(EventListener listener,
                        EventQueue queue)

Registers a listener with this broadcaster. A listener may only be associated with one queue at a time; registering a listener with a new queue unregisters it with the old one.

Parameters:

listener - The listener which wishes to receive events from this broadcaster.

queue - The queue on which the events will appear.

removeListener

public void removeListener(EventListener listener)

Unregisters a listener with this broadcaster.

Parameters:

listener - A listener which no longer wishes to receive events.

broadcastEvent

public void broadcastEvent(Event event)

Broadcasts an event to all registered listeners on their respective queues. Subclasses might override this to track events or impose conditions on which kinds this broadcaster can broadcast.

Parameters:

event - The event to broadcast

updateBroadcasters

public static void updateBroadcasters(EventListener listener,
                                      EventQueue eventq,
                                      Collection oldBroadcasters,
                                      Collection newBroadcasters)

A utility method to make a broadcaster's listeners mirror a changing collection. This method compares an old and a new collection of EventBroadcasters.

• If an element has been added (i.e. it appears in newBroadcasters but not oldBroadcasters), it gets registered with the listener.
• If an element has been removed (i.e. it appears in oldBroadcasters but not newBroadcasters), it gets unregistered from the listener.
• If an element is unchanged (i.e. it appears in both the collections, or in neither), nothing happens. If it was registered before, it remains registered on the same queue; if it wasn't registered before, it doesn't get added.

Parameters:

listener - The listener which will mirror the additions and removals.

eventq - The queue on which newly added broadcasters will get registered.

oldBroadcasters - The collection of EventBroadcasters as it was.

newBroadcasters - The collection of EventBroadcasters as it is now.