JSR-043: JTAPI-1.4

javax.telephony.media.provider
Class Dispatcher

java.lang.Object
  |
  +--javax.telephony.media.provider.Dispatcher
All Implemented Interfaces:
java.lang.Runnable
Direct Known Subclasses:
EventQueue

public class Dispatcher
extends java.lang.Object
implements java.lang.Runnable

Provides a framework for managing Listeners, and building event queues and dispatch threads.

Dispatcher delivers an DispatchableEvent to a all Listeners. The DispatchableEvent decides which method to invoke on which Listeners.

The Dispatcher handles any Exceptions generated by Event dispatching or by the Listeners.

This Dispatcher is very generic, the actual knowledge of which Listener class and which method to invoke is encapsulated in the Events that implement DispatchableEvent.

This class can be extended by implementing: getNextEvent() and providing whatever constructor or initializers are necessary.

An event can be dispatched from any thread that calls notiftyListeners(). The supplied Thread.run() method calls notifyListeners, but this class must be specialized to supply a getNextEvent() method.

Since:
JTAPI-1.4

Inner Class Summary
static interface Dispatcher.DispatchableEvent
          Supplies a method to dispatch an object to its Listener.
static interface Dispatcher.ExceptionHandler
          Supplies a method to handle Exceptions generated while dispatching.
 
Constructor Summary
Dispatcher()
           
 
Method Summary
 void addListener(java.util.EventListener listener)
          Add the given listener to the list.
 void close()
          stop Dispatcher, return to initial state.
 boolean isRunning()
           
 void notifyListeners(Dispatcher.DispatchableEvent event)
          Causes the given DispatchableEvent to be delivered to the Listeners that are expecting it.
static java.lang.String objName(java.lang.Object obj)
          A utility routine to get short name for an object.
static void printDispatcherException(java.lang.String label, Dispatcher disp, java.lang.Exception ex, java.util.EventListener listener, Dispatcher.DispatchableEvent event)
          Print the Exception and other information
 void removeListener(java.util.EventListener listener)
          Remove the given listener from the list.
 void run()
          get a DispatchableEvent and dispatch it to all EventListeners until stop().
 void setExceptionHandler(Dispatcher.ExceptionHandler handler)
          Set a Handler for Exception handling.
 void start()
           
 void start(java.lang.Object obj)
           
 void start(java.lang.String name)
          start a Thread for this Dispatcher.
 void stop()
          Stop the Thread for this Dispatcher.
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Dispatcher

public Dispatcher()
Method Detail

setExceptionHandler

public void setExceptionHandler(Dispatcher.ExceptionHandler handler)
Set a Handler for Exception handling. The default implementation of Dispatcher.onDispatcherException invokes handler.onDispatcherException.

Therefore, there are two ways to override what happens when there is an Exception during dispatch:

  1. setExceptionHandler() on an existing base Dispatcher, providing an object that implements onDispatcherException().
  2. Craete a specialized Dispatcher class that overrides an provides its own implementaiton of onDispatcherException().

Parameters:
handler - a Dispatcher.ExceptionHandler or null to revert to the default behavior: print and stop.

printDispatcherException

public static void printDispatcherException(java.lang.String label,
                                            Dispatcher disp,
                                            java.lang.Exception ex,
                                            java.util.EventListener listener,
                                            Dispatcher.DispatchableEvent event)
Print the Exception and other information

addListener

public void addListener(java.util.EventListener listener)
Add the given listener to the list. If listener already on the list, this has no effect.
Parameters:
listener - an EventListener object.

removeListener

public void removeListener(java.util.EventListener listener)
Remove the given listener from the list. If listener is not on the list, this has no effect.
Parameters:
listener - an EventListener object.

notifyListeners

public void notifyListeners(Dispatcher.DispatchableEvent event)
Causes the given DispatchableEvent to be delivered to the Listeners that are expecting it.

All Listeners are considered, those that implement the Listener interface used by the event are invoked.

This method can be called directly, or if events are being queued, then the Dispatcher Thread's run() method will call then when an event is available from getNextEvent().


toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

run

public void run()
get a DispatchableEvent and dispatch it to all EventListeners until stop().
Specified by:
run in interface java.lang.Runnable

isRunning

public boolean isRunning()

objName

public static java.lang.String objName(java.lang.Object obj)
A utility routine to get short name for an object. Used to set default name of Dispatcher Thread.

start

public void start()

start

public void start(java.lang.Object obj)

start

public void start(java.lang.String name)
start a Thread for this Dispatcher.

stop

public void stop()
Stop the Thread for this Dispatcher. Sets field stopNow, and interrupts the thread.

If you need access to the Thread, specialize the class.


close

public void close()
stop Dispatcher, return to initial state. nullify various pointers to deconstruct this Dispatcher.

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org