org.lsst.ccs.messaging.util

Interface Dispatcher

All Known Implementing Classes:

AbstractDispatcher, LegacyDispatcher, MultiQueueDispatcher

public interface Dispatcher

Task dispatcher that decouples MessagingLayer implementation (currently, JGroups) from CCS messaging framework. MessagingLayer submits executable tasks (either message processing or disconnection notifications) through the in(...) method. CCS framework submits message sending tasks through the out(...) method.

All implementations should provide public constructor that takes String[] parameter. This is a way to supply configuration parameters through the protocol string passed to TransportManager. Implementations should be thread-safe, methods of this interface can be called on any thread.

Dispatcher collects statistics on task processing that can be retrieved thorough its getters. Some implementations might not provide all types of statistics. In that case, corresponding getters will return 0.

Author:

onoprien

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
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 class	Dispatcher.Stat Enumeration of statistics.
static interface	Dispatcher.Status
static interface	Dispatcher.StatusListener Interface to be implemented by classes that should by notified of status changes.
static interface	Dispatcher.Task

Method Summary

Modifier and Type	Method and Description
void	addStatusListener(Dispatcher.StatusListener listener) Registers status listener.
Dispatcher.Status	getStatus() Returns statistics and diagnostic data on the current state of this Dispatcher.
void	in(Runnable task, Bus bus, String... agents) Submits a task to process an incoming message or disconnection notification.
default void	initialize() Initializes this dispatcher.
void	out(Runnable task, Bus bus, Dispatcher.Order order) Submits a task to process an outgoing message.
void	removeStatusListener(Dispatcher.StatusListener listener) Removes status listener.
default void	shutdown() Orderly shuts down this dispatcher.

Method Detail

initialize

default void initialize()

Initializes this dispatcher.

shutdown

default void shutdown()

Orderly shuts down this dispatcher. 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 service. 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, typically either because it has not been initialized or because it has been shut down.

getStatus

Dispatcher.Status getStatus()

Returns statistics and diagnostic data on the current state of this Dispatcher. Implementations of Status returned by specific implementations of Dispatcher may provide additional data. The object returned by this method should be treated as immutable. It reflects the latest recorded state and will not be updated.

Returns:

Dispatcher status, or null if not available.

addStatusListener

void addStatusListener(Dispatcher.StatusListener listener)

Registers status listener. The listener will be notified whenever an updated status becomes available.

Parameters:

listener - Listener to add.

removeStatusListener

void removeStatusListener(Dispatcher.StatusListener listener)

Removes status listener.

Parameters:

listener - Listener to remove.