uk.ac.soton.simulation.jsit.core

Class EventManager

java.lang.Object

uk.ac.soton.simulation.jsit.core.EventManager

public class EventManager
extends java.lang.Object

Simple manager for publish/subscribe events (a flavour of the Observer design pattern). Published events can also optionally be logged to a special events logger which allows, for example, a 'narrative' type file of real-world-domain- meaningful events to be kept. This allows for two alternative architectures to be used (which can be freely mixed if desired):

Marker-Based Events

The receivers just receive a 'marker' that an event has occurred (with useful human-readable detail in a log message), and then query the event source object to get the information they need (requiring those objects/agents to have the relevant information available, and the caller to know about these model classes). The markers are implemented as the event sources providing an source-class-specific enum and a method returning the enum that indicates the event alternative that just occurred. (A given model class may generate any number of alternative events.)

Message-Class Events

Have messages (objects of event-source-specific message classes) sent to receivers which may contain either all required information (this isolating receivers from anything other than the message classes), and/or contain references to model classes (or informational interfaces for them) to obtain further information.

Since:

0.1

Author:

Stuart Rossiter

Constructor Summary

Constructors

Constructor and Description
EventManager() Deprecated.
EventManager(ModelInitialiser modelInitialiser) Constructor.

Method Summary

Modifier and Type	Method and Description
void	deregister(java.lang.Class<?> sourceClass, EventReceiver receiver) Deregister receiver for marker-based events from a source class.
void	deregister(EventSource<?> source, EventReceiver receiver) Deregister receiver for marker-based events from a source object.
void	publish(EventSource<?> source, java.lang.String eventsLogMsg) Publish a marker-based event from an EventSource.
void	publish(java.lang.Object msg, EventMessageSource source, boolean logMessage) Publish a particular event message object (which will be passed on to any subscribers via their EventMessageReceiver interface).
void	register(java.lang.Class<?> messageClass, EventMessageReceiver<?> receiver) Register (subscribe) to receive all event message objects for a particular source class.
void	register(java.lang.Class<?> messageClass, EventMessageSource specificSource, EventMessageReceiver<?> receiver) Register (subscribe) to receive all event message objects for a particular source class and a particular source object.
void	register(java.lang.Class<?> sourceClass, EventReceiver receiver) Register (subscribe) a receiver for marker-based events from a given source class (i.e., from all instances of that class).
void	register(EventSource<?> eventSource, EventReceiver receiver) Register (subscribe) a receiver for marker-based events from a given source object.

Methods inherited from class java.lang.Object

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

Constructor Detail

EventManager

@Deprecated
public EventManager()

Deprecated.

EventManager

public EventManager(ModelInitialiser modelInitialiser)

Constructor.

Parameters:

modelInitialiser - The model initialiser.

Since:

0.2

Method Detail

register

public void register(java.lang.Class<?> sourceClass,
                     EventReceiver receiver)

Register (subscribe) a receiver for marker-based events from a given source class (i.e., from all instances of that class).

Parameters:

sourceClass - The source class.

receiver - The receiver for the events.

Since:

0.1

register

public void register(EventSource<?> eventSource,
                     EventReceiver receiver)

Register (subscribe) a receiver for marker-based events from a given source object.

Parameters:

eventSource - The source object.

receiver - The receiver for the events.

Since:

0.1

publish

public void publish(EventSource<?> source,
                    java.lang.String eventsLogMsg)

Publish a marker-based event from an EventSource. We call source-instance-specific handlers first (in order of registration) and then source-class-specific ones. (It makes sense that more 'targeted' handlers run first.)

Parameters:

source - The source object.

eventsLogMsg - Log message for the events log. (Nothing will be logged if null.)

Since:

0.1

deregister

public void deregister(java.lang.Class<?> sourceClass,
                       EventReceiver receiver)

Deregister receiver for marker-based events from a source class. Warning if not currently registered.

Parameters:

sourceClass - The source class.

receiver - The receiver to deregister.

Since:

0.1

deregister

public void deregister(EventSource<?> source,
                       EventReceiver receiver)

Deregister receiver for marker-based events from a source object. Warning if not currently registered.

Parameters:

source - The source object.

receiver - The receiver to deregister.

Since:

0.1

register

public void register(java.lang.Class<?> messageClass,
                     EventMessageReceiver<?> receiver)

Register (subscribe) to receive all event message objects for a particular source class.

Parameters:

messageClass - The class of the message.

receiver - The receiver for the messages. This will override any previous source-specific subscriptions.

Since:

0.2

register

public void register(java.lang.Class<?> messageClass,
                     EventMessageSource specificSource,
                     EventMessageReceiver<?> receiver)

Register (subscribe) to receive all event message objects for a particular source class and a particular source object.

Parameters:

messageClass - The class of the message.

specificSource - The specific source object.

receiver - The receiver for the messages. This will override any previous subscription for this receiver to receive event message objects from all source class instances.

Since:

0.2

publish

public void publish(java.lang.Object msg,
                    EventMessageSource source,
                    boolean logMessage)

Publish a particular event message object (which will be passed on to any subscribers via their EventMessageReceiver interface).

Parameters:

msg - The message.

source - The message source.

logMessage - Whether to log the message as well. (The message's toString() method provides the logged version of the message.)

Since:

0.2