org.lsst.ccs.messaging

Interface BusMessagingLayer

All Superinterfaces:

AutoCloseable, Closeable, MessagingLayer

All Known Implementing Classes:

JGroupsBusMessagingLayer, JMSBusMessagingLayer

public interface BusMessagingLayer
extends Closeable, MessagingLayer

Interface defining the access to the Transport Layer of Buses

Author:

bamade TODO: create an accept URI

Method Summary

Modifier and Type	Method and Description
void	addMessageListener(String agentName, BusMessageForwarder forwarder, Bus... buses) Sets up callback configuration for a topic and subsystem.
void	close() Close the Transport Layer.
void	closeFor(String agentName, Bus... buses) close entry points for a bus for an agent.
default Set<String>	getRegisteredLocalAgents() Get the list of local agents currently connected to all buses.
Set<String>	getRegisteredLocalAgents(Bus... buses) Get the list of local agents currently connected to the buses.
static String	parseDestination(String destination) utility method: parse the destination string in Commands.
void	register(String agentName, Bus... buses) Creates low level communication entry points for a subsystem.
void	removeMessageListener(String agentName, BusMessageForwarder forwarder, Bus... buses) Removes a message listener from the forwarder list.

Methods inherited from interface org.lsst.ccs.messaging.MessagingLayer

connect, disconnect, sendMessage

Method Detail

parseDestination

static String parseDestination(String destination)

utility method: parse the destination string in Commands. extracts the agent name from a complete destination

Parameters:

destination - the complete destination (e.g : "sft/carousel")

Returns:

the agent name (e.g : "sft")

register

void register(String agentName,
              Bus... buses)
       throws IOException,
              DuplicateAgentNameException

Creates low level communication entry points for a subsystem. Abstract vision is that there is a different entry point for each bus/topic.

Parameters:

agentName - name of the sending/receiving point as will be known by transport null or empty string means that the local agent will receive all messages (whatever the destination of the message is : "anonymous agent") if an agent with same name is already locally registered for these buses nothing happens (the call is idempotent), but if another agent has the same name on the network a DuplicateBusNameException may be fired (this is an optional behaviour) but this exception is reported only to the corresponding BusMembershipListener

buses - list of buses we want to connect to, if empty connects to all buses

Throws:

IOException - if connection impossible,

DuplicateAgentNameException

closeFor

void closeFor(String agentName,
              Bus... buses)

close entry points for a bus for an agent. calls should be idempotent.

Parameters:

agentName - (if empty voids the "anonymous" agent capabilities

buses - if empty all registered buses for the agent will be closed

Throws:

IllegalArgumentException - if you do not "own" the agent corresponding to the name.

getRegisteredLocalAgents

Set<String> getRegisteredLocalAgents(Bus... buses)

Get the list of local agents currently connected to the buses.

Parameters:

buses - The buses for which we are seeking the connected agents. If empty it will report agents connected to all buses.

Returns:

The List of registered buses.

Throws:

IOException

getRegisteredLocalAgents

default Set<String> getRegisteredLocalAgents()

Get the list of local agents currently connected to all buses.

Returns:

The List of registered buses.

Throws:

IOException

close

void close()
    throws IOException

Close the Transport Layer. Subsequent method calls will have no effect.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

addMessageListener

void addMessageListener(String agentName,
                        BusMessageForwarder forwarder,
                        Bus... buses)

Sets up callback configuration for a topic and subsystem. There could be multiple Forwarder for a given bus. All callbacks are supposed to be multithreaded

Parameters:

agentName - if empty adds a forwarder to "anonymous" agent that receives all messages

forwarder - code that handles the incoming messages

buses - if empty the forwarder listens to all buses.

Throws:

IllegalArgumentException - if the subsystem is not registered to one of the buses or if forwarder is null

removeMessageListener

void removeMessageListener(String agentName,
                           BusMessageForwarder forwarder,
                           Bus... buses)

Removes a message listener from the forwarder list.

Parameters:

agentName -

forwarder -

buses - if empty forwarder is removed from all buses

Throws:

IllegalArgumentException - if forwarder is null (but no exception if the subsystem is not registered, or forwarder not present)