ewe.util
Class EventDispatcher

java.lang.Object
  ewe.sys.TaskObject
      ewe.util.EventDispatcher

All Implemented Interfaces:

Runnable, Task

public class EventDispatcher

extends TaskObject

An EventDispatcher is a utility class that can be used to keep track of a set of ewe.ui.EventListener objects that wish to listen to some kind of event via their onEvent(Event ev) method.

The EventDispatcher can be configured to dispatch events in the current thread or via one or more background threads.

Listeners can also be added weakly, where a reference to them is kept only as long as they are referenced by other objects other than the EventDispatcher. So when they are garbage collected they will automatically be removed from the EventDispatcher.

Field Summary

boolean

dontUseSeparateThread If this is set true then events are not delivered via a separate thread, but within the same thread that called dispatch().

Fields inherited from class ewe.sys.TaskObject

handle, interruptThreadToStop, myThread, napIterations, napTime, shouldStop

Constructor Summary

EventDispatcher()

EventDispatcher(int maxParallelDeliveries)
Create an EventDispatcher specifying the number of threads used to deliver events.

Method Summary

void	addListener(EventListener listener) Add an event listener.
void	addListener(EventListener listener, boolean addToWeakSet) Add an event listener.
void	close() Close the EventDispatcher.
void	dispatch(Event ev) Send off the event to the listeners.
protected void	doRun() Override this method if you want to use an mThread to run your Task.
void	finalize() This method (when overriden), will be called when the VM determines that the Object can be garbage collected.
Vector	getCurrentListeners(Vector destination) Get all current listeners.
boolean	isEmpty() Check if there are any listeners in the Dispatcher.
void	removeListener(EventListener listener) Remove an event listener.

Methods inherited from class ewe.sys.TaskObject

checkAbortFail, checkFailure, doStart, doStop, exec, getHandle, nap, run, setNapTime, show, sleep, start, startTask, stopTask, waitOn, waitOnAny, waitOnSuccess, yield, yield

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, toString

Field Detail

dontUseSeparateThread

public boolean dontUseSeparateThread

If this is set true then events are not delivered via a separate thread, but within the same thread that called dispatch().

Constructor Detail

EventDispatcher

public EventDispatcher()

EventDispatcher

public EventDispatcher(int maxParallelDeliveries)

Create an EventDispatcher specifying the number of threads used to deliver events.

Parameters:

maxParallelDeliveries - the maximum number of threads used to deliver evetns simultaneously.

Method Detail

doRun

protected final void doRun()

Description copied from class: TaskObject

Override this method if you want to use an mThread to run your Task. Otherwise if you are using timers or callbacks, override the doStart() method.

Overrides:

doRun in class TaskObject

addListener

public void addListener(EventListener listener,
                        boolean addToWeakSet)

Add an event listener.

Parameters:

listener - The listener to add.

addToWeakSet - If this is true the listener will be added to an internal WeakSet. This means that if no other object is referring to that listener it will eventually be garbage collected and removed from the list.

addListener

public void addListener(EventListener listener)

Add an event listener.

Parameters:

listener - The listener to add.

removeListener

public void removeListener(EventListener listener)

Remove an event listener.

Parameters:

listener - The listener to remove.

getCurrentListeners

public Vector getCurrentListeners(Vector destination)

Get all current listeners.

Parameters:

destination - A destination Vector, which will be cleared first, to hold the listeners. This can be null in which case a new one will be created.

Returns:

The destination or new Vector containing all active listeners.

dispatch

public void dispatch(Event ev)

Send off the event to the listeners. This is done via a separate thread unless dontUseSeparateThread is true, in which case the onEvent() method of each listener is called directly.

Parameters:

ev - the event to send.

isEmpty

public boolean isEmpty()

Check if there are any listeners in the Dispatcher. If this returns true it indicates that there are definitely no listeners. If it returns false it indicates that there may be some listeners.

close

public void close()

Close the EventDispatcher.

finalize

public void finalize()

Description copied from class: Object

This method (when overriden), will be called when the VM determines that the Object can be garbage collected. Any action can be taken by the finalize() method, including making the Object available to other Threads (which would stop the garbage collection of the Object).

The finalize() method of a Class is only called if it overrides finalize() - the finalize() method java.lang.Object is never called by the Ewe VM.

Note that under a native Ewe VM, the call to finalize() will be synchronized with the Ewe library, but under a Java VM, the finalize() method may be called by a separate Thread that is not synchronized with the Ewe library. To ensure that the execution of the finalize() method is sychronized with the Ewe library your finalize() method should look like this:

 protected void finalize()
 {
   synchronized(ewe.sys.Vm.getSyncObject()){
   //
   // Put your finalize() code here.
   //
   }
 }
 

Under Ewe the synchronized keyword is silently ignored.

Overrides:

finalize in class Object