org.lsst.ccs.bus

Interface BusMessagingLayer

All Superinterfaces:

AutoCloseable, Closeable

public interface BusMessagingLayer
extends Closeable

Interface defining the access to the Transport Layer of Buses

Author:

bamade TODO: create an accept URI

Field Summary

Fields

Modifier and Type	Field and Description
static String	ANONYMOUS_AGENT

Method Summary

Methods

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.
List<String>	getConnectedNames(Bus bus) Tries to return the name of a list of agents connected to a bus.
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.
<T extends BusPayload> void	sendMessage(String senderAgent, Bus<T> bus, T message, String... destinations) sends a message on a bus: note that BusMessage should have sender and destination information but it is not the role of the communication layer to parse destination information such as "subsystem1, subsystem2" or "subsystem3/module"a.
void	setMembershipListener(BusMembershipListener listener, Bus... buses) optional operation.

Field Detail

ANONYMOUS_AGENT

static final String ANONYMOUS_AGENT

See Also:

Constant Field Values

Method Detail

register

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

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,

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.

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

sendMessage

<T extends BusPayload> void sendMessage(String senderAgent,
                                      Bus<T> bus,
                                      T message,
                                      String... destinations)
                 throws IOException

sends a message on a bus: note that BusMessage should have sender and destination information but it is not the role of the communication layer to parse destination information such as "subsystem1, subsystem2" or "subsystem3/module"a.

The message will be sent to all destinations plus to all the "anonymous" agents

Parameters:

senderAgent - which agent is supposed to be the initiator of the message (anonymous agents are not supposed to send message: that may fire an exception)

bus -

message -

destinations - could be empty (means broadcast) of a single "" or a single"*" (again means broadcast) or a list of destinations (DO NOT use things such as "*", "dest1", "dest2" : this will not work!)

Throws:

IOException - this could have a list of causes if some destinations fail. as much as possible implementers will ensure that all correct destinationa are adressed: if some fail it is not mandatory to report with a special subclass of IOexception that lists all destination that failed.

See Also:

DestinationsException

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)

setMembershipListener

void setMembershipListener(BusMembershipListener listener,
                         Bus... buses)

optional operation. registers a listener for knowing about the agents that connect/disconnect on a bus. This method is more useful if called before any agent registration (for instance duplicate agent names will be reported to these listeners)

Parameters:

buses - if empty register to all buses

listener - can be null if we want to deregister a previous listener

Throws:

UnsupportedOperationException - if not supported

getConnectedNames

List<String> getConnectedNames(Bus bus)

Tries to return the name of a list of agents connected to a bus.

Parameters:

bus -

Returns:

a (possibly empty) list of agent's names connected to a bus if the current calling code is not connected to this bus the list will be empty