de.fhg.igd.event
Class TrustedListener

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

All Implemented Interfaces:

Listener, Runnable

public class TrustedListener
extends AsyncListener
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 and Trojan Horse objects. Events are serialised in the caller's thread, and deserialised in the receiver's thread.

Objects are serialized only if they are loaded by a class loader other than the system class loader. Hence, local classes are trusted.

All non-local event classes sent to this listener must be serializable. If an error occurs during serialization or deserialization then the corresponding event is silently dropped.

There are two ways to stop the trusted 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

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

TrustedListener(Listener o)
Creates an instance with the given target.

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

TrustedListener(String name, Listener o)
Creates an instance with the given name and target.

TrustedListener(ThreadGroup parent, Listener o)
Creates an instance in the given thread group with the given target listener.

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

Method Summary

void	notifiedOf(byte[] b, boolean serialize) Pushes the given byte array 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.

Methods inherited from class de.fhg.igd.event.AsyncListener

isEmpty, isRunning, notifiedOf, run, setHighwater, trim

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

Methods inherited from interface de.fhg.igd.util.Listener

notifiedOf

Constructor Detail

TrustedListener

public TrustedListener(ThreadGroup parent,
                       Listener o)

Creates an instance in the given thread group with the 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.

TrustedListener

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

Creates an instance 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.

TrustedListener

public TrustedListener(Listener o)

Creates an instance with the given target. 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.

TrustedListener

public TrustedListener(String name,
                       Listener o)

Creates an instance with the given name and target. The target object is the one to notify when events are detected in the input queue.

Parameters:

o - The listener to notify of updates.

name - The name of this thread.

Throws:

NullPointerException - iff the given listener is null.

TrustedListener

public TrustedListener(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

push

protected void push(Object o)

Pushes an object into the event queue and notifies any thread waiting on a change of the queue. Before the object is pushed into the queue, it is serialized. Hence, the given object must be serializable. If it is not then it is silently discarded and no notification is done.

As an optimization, this method only serializes objects that were loaded by a classloader other than the system class loader. This is checked by means of method getClassLoader() which is called on the class object of the given object.

In other words, local classes are piped through the listener untouched while agents' classes are serialized before they are passed on to the receiving agent's domain. This is OK because local classes have precedence over agent classes anyway. So the same class would be used for deserialization.

Overrides:

push in class AsyncListener

Parameters:

event - The object to be inserted.

notifiedOf

public void notifiedOf(byte[] b,
                       boolean serialize)

Pushes the given byte array into the queue. If serialize is true then the given byte array is serialised and the resulting byte array is pushed instead of the original one. This flag should be used in case an ordinary byte array is pushed into the queue.

If serialize is false then the given byte array is interpreted as the encoding of an pre-serialized object. The byte array is then pushed into the queue directly without further processing.

This is a convenience method for objects that distribute serialized objects to multiple listeners. In this way, the object to be distributed must be serialized only once, and the resulting byte array can be copied or cloned for each listener. In this case false should be passed to this method.

If the given byte array cannot be serialized or cannot be deserialized later on then it is silently dropped.

Parameters:

b - The bytes of a serialized object.

pull

protected Object pull()
               throws InterruptedException

Pulls an object from the queue and returns it.

Overrides:

pull in class AsyncListener

Returns:

The next object.

Throws:

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

InterruptedException