org.lsst.ccs.messaging.util

Interface Dispatcher

All Known Implementing Classes:

AbstractDispatcher, LegacyDispatcher, MultiQueueDispatcher

public interface Dispatcher

Task dispatcher that connects messaging framework (currently, JGroups) to CCS framework. A singleton Dispatcher is created by CCS MessagingLayer. A single Dispatcher handles all three buses.

MessagingLayer submits executable tasks (incoming message processing or disconnection notifications) through the in(...) method. CCS framework submits message sending tasks through the out(...) method.

Dispatcher also provides API for the messaging system to send events (statistics, alerts, etc.) to other CCS components. Various CCS components can retrieve information about the messaging system and its current state through Dispatcher.

All implementations should provide public constructor that takes String argument. This is a way to supply configuration parameters through the protocol string passed to TransportManager. The string should be in "key[=value]&...&key[=value]" format, where value may be a comma-separated array. Prohibited characters: :?.

Implementations should be thread-safe, methods of this interface can be called on any thread.

Author:

onoprien

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Dispatcher.AlertEvent
static class	Dispatcher.Event Event published by Dispatcher.
static interface	Dispatcher.Listener Interface to be implemented by classes that should be notified of Dispatcher events.
static class	Dispatcher.Order Enumeration of order of execution and capacity control policies.
static class	Dispatcher.Stage Enumeration of task execution stages for which statistical data can be reported.
static interface	Dispatcher.Task Instrumented Runnable for submission to Dispatcher.

Method Summary

Modifier and Type	Method and Description
void	addListener(Dispatcher.Listener listener) Registers a listener.
void	fireEvent(Dispatcher.Event event) Notifies listeners of the given event.
Logger	getLogger() Returns a logger to be used for Dispatcher related messages.
List<Alert>	getRegisteredAlerts() Returns the list of alerts registered with this Dispatcher.
void	in(Runnable task, Bus bus, String... agents) Submits a task to process an incoming message or disconnection notification.
void	initialize() Initializes this dispatcher.
void	out(Runnable task, Bus bus, Dispatcher.Order order) Submits a task to process an outgoing message.
void	raiseAlert(Alert alert, AlertState severity, String cause) Notifies listeners by publishing an AlertEvent.
void	raiseAlert(String id, AlertState severity, String cause) Notifies listeners by publishing an AlertEvent.
void	registerAlert(Alert alert) Registers an alert with this Dispatcher.
void	removeListener(Dispatcher.Listener listener) Removes a listener.
void	shutdown() Orderly shuts down this dispatcher.

Method Detail

initialize

void initialize()

Initializes this dispatcher.

shutdown

void shutdown()

Orderly shuts down this dispatcher. Stops accepting tasks, executes previously submitted tasks, delivers events to listeners, then shuts down. The MessagingLayer will not be closed until this method returns.

in

void in(Runnable task,
        Bus bus,
        String... agents)

Submits a task to process an incoming message or disconnection notification. Depending on the implementation, this method may return immediately or after the task has been executed.

If one or more agent names are given, the task if guaranteed to be executed after any previously submitted tasks for the same bus and agent. If no agents are specified, the task is independent of other tasks, subject to capacity controls imposed by the implementation of this Dispatcher. If the agents argument is null, the task is independent of other tasks, not subject to capacity controls.

Calling this method has no effect if this Dispatcher has not been initialized or it has been shut down. No exceptions are thrown in this case.

Parameters:

task - Task to be executed.

bus - Bus (LOG, STATUS, or COMMAND).

agents - Names of affected agents (source or disconnected).

Throws:

TransportStateException - If this Dispatcher is unable to accept the request for reasons other than being uninitialized or shut down.

out

void out(Runnable task,
         Bus bus,
         Dispatcher.Order order)

Submits a task to process an outgoing message. Depending on the implementation, this method may return immediately or after the task has been executed.

Tasks submitted with outOfBand equal to false for the same bus are guaranteed to be processed in the order of submission. If outOfBand equals true, the task is executed independently of others, subject to capacity controls imposed by the implementation of this service. If outOfBand equals null, the task is independent, not subject to capacity controls.

Parameters:

task - Task to be executed.

bus - Bus (LOG, STATUS, or COMMAND).

order - Order of execution and capacity control policies.

Throws:

TransportStateException - If this Dispatcher is unable to accept the request.

addListener

void addListener(Dispatcher.Listener listener)

Registers a listener.

Parameters:

listener - Listener to add.

removeListener

void removeListener(Dispatcher.Listener listener)

Removes a listener.

Parameters:

listener - Listener to remove.

fireEvent

void fireEvent(Dispatcher.Event event)

Notifies listeners of the given event. This method is public to allow clients publish events through this Dispatcher.

Parameters:

event -

raiseAlert

void raiseAlert(String id,
                AlertState severity,
                String cause)

Notifies listeners by publishing an AlertEvent. If an alert with matching id has not been registered, nothing is published.

Parameters:

id - Alert id.

severity - Alert severity.

cause - Message.

raiseAlert

void raiseAlert(Alert alert,
                AlertState severity,
                String cause)

Notifies listeners by publishing an AlertEvent. An event is published even if an alert with matching id has not been registered.

Parameters:

alert - Alert instance.

severity - Alert severity.

cause - Message.

getRegisteredAlerts

List<Alert> getRegisteredAlerts()

Returns the list of alerts registered with this Dispatcher.

Returns:

Registered alerts.

registerAlert

void registerAlert(Alert alert)

Registers an alert with this Dispatcher.

Parameters:

alert - Alert to add.

getLogger

Logger getLogger()

Returns a logger to be used for Dispatcher related messages.

Returns:

Logger associated with this dispatcher.