org.lsst.ccs.services

Class AgentCommandDictionaryService

java.lang.Object

org.lsst.ccs.services.AgentCommandDictionaryService

All Implemented Interfaces:

BusMessagePreProcessor, ServiceLifecycle, AgentService

public class AgentCommandDictionaryService
extends Object
implements ServiceLifecycle, AgentService, BusMessagePreProcessor

A service to manage the Command Dictionary of a given agent. It has two components to it: - command dictionary management: it builds a command dictionary for all components on the lookup tree that have methods annotated with the Command annotation. It also provides an API that can be used to add commands to a given path from objects that are not on the lookup tree. - client side command dictionary record keeping: for Consoles only. It listens to the buses for the presence of Agents and it keeps an online snapshot of the currently available dictionaries on the buses. Rules to add command dictionaries: - dictionaries can only be added in the HasLifecycle:init phase. All other attempts will fail with a RuntimeException. Dictionary publication on the status bus: this service is responsible for publishing an Agent's command dictionary: - every time a CONSOLE is connected to the buses - upon startup as soon as the full dictionary is ready the dictionary is published in a StatusCommandDicionary status message.

Author:

LSST CCS Team

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	AgentCommandDictionaryService.AgentCommandDictionaryCommands
static class	AgentCommandDictionaryService.AgentCommandDictionaryEvent An event fired to AgentCommandDictionaryListeners when an agent command dictionary has changed.
static interface	AgentCommandDictionaryService.AgentCommandDictionaryListener A Listener to receive notifications of CommandDictionary changes.

Field Summary

Fields

Modifier and Type	Field and Description
static SupportedOption	withLockOption

Constructor Summary

Constructors

Constructor and Description
AgentCommandDictionaryService()

Method Summary

Modifier and Type	Method and Description
void	addAgentCommandDictionaryListener(AgentCommandDictionaryService.AgentCommandDictionaryListener listener)
void	addCommandSetToObject(Object obj, Object objectToAddTo) Adds a CommandSet to extend the set of commands recognized by this Agent.
void	afterBuild()
void	afterInit()
HashMap<String,Dictionary>	getAgentCommandDictionary()
HashMap<String,Dictionary>	getAgentCommandDictionaryWithoutAgentName()
AgentDictionaryCommand	getAgentDictionaryCommand(String destination, String commandName, int nArgs) Deprecated. This method is unused and is being removed.
String	getAgentServiceName() Get the name of this service.
Bus	getBus() The Bus this BusMessagePreProcessor applies to.
CommandSet	getCommandSet(String name)
long	getDictionaryChecksum()
void	preBuild()
BusMessage	preProcessMessage(BusMessage msg) Pre-process the incoming BusMessage and return the message to be forwarded to the bus message listeners.
void	removeAgentCommandDictionaryListener(AgentCommandDictionaryService.AgentCommandDictionaryListener listener)
boolean	startForAgent(AgentInfo agentInfo) This method is invoked after an agent service is created to see if this service is to be started for the tiven Agent.

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.lsst.ccs.ServiceLifecycle

afterStart, preInit, preShutdown, preStart

Field Detail

withLockOption

public static final SupportedOption withLockOption

Constructor Detail

AgentCommandDictionaryService

public AgentCommandDictionaryService()

Method Detail

getAgentServiceName

public String getAgentServiceName()

Description copied from interface: AgentService

Get the name of this service. This name will be used to add the given service to the lookup tree.

Specified by:

getAgentServiceName in interface AgentService

Returns:

the AgentService name.

startForAgent

public boolean startForAgent(AgentInfo agentInfo)

Description copied from interface: AgentService

This method is invoked after an agent service is created to see if this service is to be started for the tiven Agent.

Specified by:

startForAgent in interface AgentService

Returns:

true if the service is to be added to the given agent.

preBuild

public void preBuild()

Specified by:

preBuild in interface ServiceLifecycle

afterBuild

public void afterBuild()

Specified by:

afterBuild in interface ServiceLifecycle

afterInit

public void afterInit()

Specified by:

afterInit in interface ServiceLifecycle

getDictionaryChecksum

public long getDictionaryChecksum()

getCommandSet

public CommandSet getCommandSet(String name)

addCommandSetToObject

public void addCommandSetToObject(Object obj,
                                  Object objectToAddTo)

Adds a CommandSet to extend the set of commands recognized by this Agent.

Parameters:

obj - The object with the commands

objectToAddTo - the object to add the commands to.

getAgentCommandDictionary

public HashMap<String,Dictionary> getAgentCommandDictionary()

getAgentCommandDictionaryWithoutAgentName

public HashMap<String,Dictionary> getAgentCommandDictionaryWithoutAgentName()

getAgentDictionaryCommand

@Deprecated
public AgentDictionaryCommand getAgentDictionaryCommand(String destination,
                                                                    String commandName,
                                                                    int nArgs)

Deprecated. This method is unused and is being removed.

Look up dictionary command for the specified target by name and number of arguments. If this method is called while the dictionary for the specified subsystem is not yet available, it will block and wait for up to 15 seconds.

Parameters:

destination - Target component, including the subsystem name.

commandName - Command name.

nArgs - Number of arguments the command takes.

Returns:

Newly created instance of AgentDictionaryCommand.

Throws:

RuntimeException - If the dictionary is not available, or a matching command is not found.

addAgentCommandDictionaryListener

public void addAgentCommandDictionaryListener(AgentCommandDictionaryService.AgentCommandDictionaryListener listener)

removeAgentCommandDictionaryListener

public void removeAgentCommandDictionaryListener(AgentCommandDictionaryService.AgentCommandDictionaryListener listener)

getBus

public Bus getBus()

Description copied from interface: BusMessagePreProcessor

The Bus this BusMessagePreProcessor applies to.

Specified by:

getBus in interface BusMessagePreProcessor

Returns:

The Bus.

preProcessMessage

public BusMessage preProcessMessage(BusMessage msg)

Description copied from interface: BusMessagePreProcessor

Pre-process the incoming BusMessage and return the message to be forwarded to the bus message listeners. The returned message can either be a modified version of the original message or a brand new message. The Class of the returned message can be different than the incoming message. If null is returned the message will not be sent to the BusMessage listeners, but it will still be passed to other BusMessagePreProcessors This method can be invoked by separate threads, but it's invoked by one thread at a time; there is no concurrent invocation of the method.

Specified by:

preProcessMessage in interface BusMessagePreProcessor

Parameters:

msg - The incoming BusMessage

Returns:

The modified BusMessage to be forwarded to the BusMessageListeners