de.fhg.igd.event
Class AsyncListener

java.lang.Object
  java.lang.Thread
      de.fhg.igd.event.AsyncListener

All Implemented Interfaces:

Listener, Runnable

Direct Known Subclasses:

TrustedListener

public class AsyncListener
extends Thread
implements Listener

Listens on notifier objects. The received events are sent to the listener specified in the constructors. This listener is trusted with respect to thread blocking. This class defines methods for pushing objects in a queue which is read by this thread. If the target listener engages in an infinite loop, it may only harm itself but delivery of notification to other listeners is unaffected.

In other words, calls to notifiedOf return immediately. The target of instances of this class are notified by the listener thread.

A maximum queue length can be specified by means of a highwater mark. If the highwater mark is reached then older events are discarded in favour of newer ones.

There are two ways to stop the asynchronous listener

• Send a null event.
• Interrupt its thread.

Version:

"$Id"

Author:

Volker Roth

Nested Class Summary

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

private int	highwater_ The maximum number of events being buffered before events are silently discarded.
private Listener	listener_ The actual listener which is notified of events in the standard implementation.
private LinkedList	queue_ The FIFO buffer used to queue events.
private boolean	running_ A flag that signals whether this listener is already running.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

AsyncListener(Listener o)
Creates a notifier slave.

AsyncListener(Listener o, int highwater)
Creates a notifier slave with the highwater mark given as argument.

AsyncListener(String name, Listener o)
Creates a listener with the given name and target.

AsyncListener(ThreadGroup parent, Listener o)
Creates a AsyncListener in the given thread group and given target listener.

AsyncListener(ThreadGroup parent, String name, Listener o)
Creates a AsyncListener in the given thread group with the given name and given target listener.

Method Summary

boolean	isEmpty() Checks whether the event queue is empty.
boolean	isRunning() This method returns true iff the trusted listener is running.
void	notifiedOf(Object o) This method pushes the received object into the queue.
protected Object	pull() Pulls an object from the queue and returns it.
protected void	push(Object o) Pushes an object into the event queue and notifies any thread waiting on a change of the queue.
void	run() Runs the notifier thread which handles asynchronous notification of the listeners.
void	setHighwater(int highwater) Sets the highwater mark.
void	trim(int size) Trims the event queue down to the given size.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

running_

private volatile boolean running_

A flag that signals whether this listener is already running.

queue_

private LinkedList queue_

The FIFO buffer used to queue events.

highwater_

private int highwater_

The maximum number of events being buffered before events are silently discarded.

listener_

private Listener listener_

The actual listener which is notified of events in the standard implementation.

Constructor Detail

AsyncListener

public AsyncListener(ThreadGroup parent,
                     Listener o)

Creates a AsyncListener in the given thread group and given target listener.

Parameters:

parent - The thread group in which this thread shall be placed.

o - The listener which is notified of updates.

Throws:

NullPointerException - iff the given listener is null.

AsyncListener

public AsyncListener(ThreadGroup parent,
                     String name,
                     Listener o)

Creates a AsyncListener in the given thread group with the given name and given target listener.

Parameters:

parent - The thread group in which this thread shall be placed.

name - The name of the thread.

o - The listener which is notified of updates.

Throws:

NullPointerException - iff the given listener is null.

AsyncListener

public AsyncListener(Listener o)

Creates a notifier slave. The target object is the one to notify when events are detected in the input queue.

Parameters:

o - The listener to notify of updates.

Throws:

NullPointerException - iff the given listener is null.

AsyncListener

public AsyncListener(String name,
                     Listener o)

Creates a listener with the given name and target. The target object is notified whenever an event is detected in the input queue.

Parameters:

o - The listener to notify of updates.

Throws:

NullPointerException - iff the given listener is null.

AsyncListener

public AsyncListener(Listener o,
                     int highwater)

Creates a notifier slave with the highwater mark given as argument.

Parameters:

highwater - The highwatermark. If it is zero then no upper limit exists on the size of the event queue.

o - The listener to notify of updates

Throws:

NullPointerException - iff the given listener is null.

IllegalArgumentException - if the given highwater mark is negative.

Method Detail

setHighwater

public final void setHighwater(int highwater)
                        throws IllegalArgumentException

Sets the highwater mark. A zero means no upper limit exists.

Parameters:

highwater - The highwater mark.

Throws:

IllegalArgumentException - if the given highwater mark is negative.

trim

public final void trim(int size)

Trims the event queue down to the given size. Negative values are ignored (nothing happens).

Parameters:

size - The size to which the queue is trimmed.

push

protected void push(Object o)

Pushes an object into the event queue and notifies any thread waiting on a change of the queue. If a highwater mark is set then the queue is trimmed down to the highwater mark from the end of the queue. In other words, older events are discarded in favour of newer ones.

Parameters:

event - The object to be inserted.

pull

protected Object pull()
               throws InterruptedException

Pulls an object from the queue and returns it.

Returns:

The next object.

Throws:

NoSuchElementException - if no object is enqueued and the wait was interrupted.

InterruptedException

isEmpty

public final boolean isEmpty()

Checks whether the event queue is empty.

Returns:

true iff the queue is empty.

run

public final void run()

Runs the notifier thread which handles asynchronous notification of the listeners. The thread returns if either a null is received from the queue or the thread is interrupted.

Specified by:

run in interface Runnable

Overrides:

run in class Thread

notifiedOf

public void notifiedOf(Object o)

This method pushes the received object into the queue. Sending a null object terminates the listener thread.

Specified by:

notifiedOf in interface Listener

Parameters:

sender - The origin of the update message.

o - The object which is sent.

isRunning

public boolean isRunning()

This method returns true iff the trusted listener is running.

Returns:

true if running, false if not.