org.lsst.ccs.bus
Class BusApplicationLayer

java.lang.Object
  org.lsst.ccs.bus.BusApplicationLayer

public class BusApplicationLayer
extends Object

Calls a BusMessagingLayer and adds all that is necessary to handle messages following application layer concerns.

Each is bound to a subsystem.

This class is meant to be subclassed if there is a need to setup complex correlations between messages (or more generally for "application layer" concerns)

beware ThreadLocal objects may be changed in future releases: they may be moved to Context objects carried through thread creations.

Nested Class Summary

protected class	BusApplicationLayer.ForwarderToCommand instances of this class will forward commands coming from the transport layer to the registered CommandListener.
protected class	BusApplicationLayer.ForwarderToLog instances of this class will forward directly log messages to a log listener
protected class	BusApplicationLayer.ForwarderToStatus instances of this class will forward directly status messages to statuslistener

Field Summary

protected BusMessagingLayer	busMessagingLayer
protected ThreadLocal<org.lsst.ccs.bus.Command>	localCommand
protected ThreadLocal<String>	localCorrelID
protected ThreadLocal<String>	localOrigin
protected static org.apache.log4j.Logger	log
protected String	subsystemName

Constructor Summary

BusApplicationLayer(String subsystemName, BusMessagingLayer busMessagingLayer)
creates an entry point to communication for the subsystem.

Method Summary

void	addCommandListener(CommandListener l) registers a CommandListener (in fact a ForwarderToCommand to the underlying transport)
void	addLogListener(LogListener l) registers a LogListener (in fact a ForwarderToLog to the underlying transport)
void	addStatusListener(StatusListener l) registers a StatusListener (in fact a ForwarderToStatus to the underlying transport)
void	close() closes the underlying transport layer, stops the listening threads, after this call all other sending calls will fail.
String	getToken()
protected String[]	parseDestination(String destination) utility method: parse the destination string in Commands.
void	registerToCommand() registers current subsystem to the Command bus
void	registerToLog() registers current subsystem to the logging bus
void	registerToStatus() registers current subsystem to the Status bus
void	removeCommandListener(CommandListener l) removes a CommandListener: since this command is based on strict identity the listener should be exactly the same as the one registered.
void	removeLogListener(LogListener l)
void	removeStatusListener(StatusListener l)
void	reply(org.lsst.ccs.bus.CommandAckOrReply cmd) sends a reply or an ack responding to a command.
void	sendCommand(org.lsst.ccs.bus.Command cmd) sends a command message to all destinations.
void	sendLogEvent(org.lsst.ccs.bus.LogEvent evt) broadcasts a log message.
void	sendStatus(org.lsst.ccs.bus.Status status) broadcasts a status message.

Methods inherited from class java.lang.Object

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

Field Detail

subsystemName

protected final String subsystemName

busMessagingLayer

protected final BusMessagingLayer busMessagingLayer

log

protected static org.apache.log4j.Logger log

localCorrelID

protected ThreadLocal<String> localCorrelID

localOrigin

protected ThreadLocal<String> localOrigin

localCommand

protected ThreadLocal<org.lsst.ccs.bus.Command> localCommand

Constructor Detail

BusApplicationLayer

public BusApplicationLayer(String subsystemName,
                           BusMessagingLayer busMessagingLayer)

creates an entry point to communication for the subsystem. One is not supposed to interact directly with the BusMessagingLayer afterwards except for administrative purposes (example: MembershipListeners).

Parameters:

subsystemName - rules of naming apply

busMessagingLayer - transport layer

Throws:

NullPointerException - if busMessagingLayer is null

Method Detail

getToken

public String getToken()

registerToCommand

public void registerToCommand()
                       throws IOException

registers current subsystem to the Command bus

Throws:

IOException

registerToStatus

public void registerToStatus()
                      throws IOException

registers current subsystem to the Status bus

Throws:

IOException

registerToLog

public void registerToLog()
                   throws IOException

registers current subsystem to the logging bus

Throws:

IOException

parseDestination

protected String[] parseDestination(String destination)

utility method: parse the destination string in Commands. destination is a list of comma separated list of names(beware of spaces!). rules: if there is a "*" in the destination list then the message is broadcast; if there is a slash in a name only the first part of the name (before the slash) is used for transport destination (so for instance "sft/carrousel" is sent to "sft").

Parameters:

destination -

Returns:

an array of agent names or an empty array if broadcasting is requested

sendCommand

public void sendCommand(org.lsst.ccs.bus.Command cmd)
                 throws IOException

sends a command message to all destinations. If origin of message is not set then sets it using the current subsystem name. If a Correlation Id is not set then creates one.

Parameters:

cmd -

Throws:

IOException

DestinationsException - may be thrown if the transport layer is unable to find some of the destination and has no broadcast policy in this case.

See Also:

for another way to signal destinations exceptions

sendStatus

public void sendStatus(org.lsst.ccs.bus.Status status)
                throws IOException

broadcasts a status message. If origin is not set then sets it with the current subsystem name.

Parameters:

status -

Throws:

IOException

sendLogEvent

public void sendLogEvent(org.lsst.ccs.bus.LogEvent evt)
                  throws IOException

broadcasts a log message. If origin is not set then sets it with the current subsystem name.

Parameters:

evt -

Throws:

IOException

reply

public void reply(org.lsst.ccs.bus.CommandAckOrReply cmd)
           throws IOException

sends a reply or an ack responding to a command. Beware : if originalCommand or CorrelID or destination are not set in the parameter this code will try to populate these fields with informations coming from ThreadLocal data so if the initial Thread that received the command spawn children (or more generally if replies or ack are generated in different Threads) then this facility will be defeated.

Parameters:

cmd -

Throws:

IOException

DestinationsException - may be thrown if the transport layer is unable to find some of the destination and has no broadcast policy in this case.

See Also:

for another way to signal destinations exceptions

addCommandListener

public void addCommandListener(CommandListener l)

registers a CommandListener (in fact a ForwarderToCommand to the underlying transport)

Parameters:

l -

removeCommandListener

public void removeCommandListener(CommandListener l)

removes a CommandListener: since this command is based on strict identity the listener should be exactly the same as the one registered.

Parameters:

l -

addStatusListener

public void addStatusListener(StatusListener l)

registers a StatusListener (in fact a ForwarderToStatus to the underlying transport)

Parameters:

l -

removeStatusListener

public void removeStatusListener(StatusListener l)

addLogListener

public void addLogListener(LogListener l)

registers a LogListener (in fact a ForwarderToLog to the underlying transport)

Parameters:

l -

removeLogListener

public void removeLogListener(LogListener l)

close

public void close()

closes the underlying transport layer, stops the listening threads, after this call all other sending calls will fail.