org.lsst.ccs.gconsole.agent

Class AgentStatusAggregator

java.lang.Object

org.lsst.ccs.gconsole.agent.AgentStatusAggregator

public class AgentStatusAggregator
extends Object

Collects status data from local and remote agents and notifies clients of relevant changes. A singleton instance of this class is created by the graphical console.

The aggregator maintains a "watch list" that determines what data is being collected. The watch list is empty on the aggregator creation, and is modified when listeners are added or removed. See addListener(AgentStatusListener listener, AgentChannelsFilter filter) and addListener(AgentStatusListener listener, Collection agents, Collection channels) method descriptions for explanations of how filters and explicit lists of agents, channels, templates, and selectors are used to determine what events are delivered to each listener.

When a filter fires a change event, this aggregator watch list is updated if necessary.

The aggregator modifies its state (in response to status messages received on the buses) and notifies listeners on a single dedicated thread. No new messages will be processed, and the aggregator state will not change, until all listeners process the current event. Listeners that need to perform any time consuming or potentially blocking operations should do that on other threads to avoid clogging the aggregator.

Methods that retrieve current status of agents and channels can be called on any thread - they are guaranteed to report consistent information that reflects the aggregator state that existed at some point between processing two consecutive status messages. There is no guarantee, however, that the aggregator will remain in that state by the time these methods return. There is also no guarantee that the state of the aggregator reflects the actual current state of an localAgent, due to the asynchronous nature of message delivery and delays in processing.

Author:

onoprien

Constructor Summary

Constructors

Constructor and Description
AgentStatusAggregator()

Method Summary

Modifier and Type	Method and Description
void	addListener(AgentStatusListener listener, AgentChannelsFilter filter) Adds a listener to be notified of changes in agents and channels specified by the filter.
void	addListener(AgentStatusListener listener, Collection<String> agents, Collection<String> channels) Adds a listener to be notified of changes in specified agents and data channels.
org.lsst.ccs.Agent	getAgent() Returns a reference to the local agent that running this status aggregator.
org.lsst.ccs.bus.data.AgentInfo	getAgent(String agentName) Return AgentInfo instance for the specified Agent.
List<org.lsst.ccs.bus.data.AgentInfo>	getAgents() Lists currently connected agents.
org.lsst.ccs.bus.states.StateBundle	getAgentState(String agentName) Returns the current state of the specified Agent.
AgentChannel	getChannel(String path) Returns the channel specified by the given path.
List<AgentChannel>	getChannels(String... channels) Returns a list of currently watched channels identified by the specified paths, templates, and selectors.
org.lsst.ccs.messaging.ConcurrentMessagingUtils	getMessenger() Returns an instance of ConcurrentMessagingUtils that can be used to send commands to remote agents.
boolean	hasAgent(String agentName) Returns true if the specified localAgent is present on the buses.
void	initialize(org.lsst.ccs.Agent agent) Initializes this status aggregator.
void	removeListener(AgentStatusListener listener) Removes the specified listener.
void	shutdown() Shuts down this status aggregator.

Methods inherited from class java.lang.Object

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

Constructor Detail

AgentStatusAggregator

public AgentStatusAggregator()

Method Detail

initialize

public void initialize(org.lsst.ccs.Agent agent)

Initializes this status aggregator.

Parameters:

agent - Local localAgent associated with this aggregator.

shutdown

public void shutdown()

Shuts down this status aggregator. Once shut down, the aggregator cannot be restarted (this restriction can be removed in future versions if necessary).

getAgent

public org.lsst.ccs.Agent getAgent()

Returns a reference to the local agent that running this status aggregator.

Returns:

Local agent.

getMessenger

public org.lsst.ccs.messaging.ConcurrentMessagingUtils getMessenger()

Returns an instance of ConcurrentMessagingUtils that can be used to send commands to remote agents.

Returns:

Instance of ConcurrentMessagingUtils.

getAgents

public List<org.lsst.ccs.bus.data.AgentInfo> getAgents()

Lists currently connected agents.

Returns:

List of connected agents.

getAgent

public org.lsst.ccs.bus.data.AgentInfo getAgent(String agentName)

Return AgentInfo instance for the specified Agent.

Parameters:

agentName - Name of the localAgent.

Returns:

AgentInfo instance, or null is no localAgent with the specified name is connected to the buses.

hasAgent

public boolean hasAgent(String agentName)

Returns true if the specified localAgent is present on the buses.

Parameters:

agentName - Agent name.

Returns:

true if the localAgent is connected.

getChannels

public List<AgentChannel> getChannels(String... channels)

Returns a list of currently watched channels identified by the specified paths, templates, and selectors. If no names are given, returns a list of all watched channels.

Parameters:

channels - Paths, templates, selectors.

Returns:

List of channels.

getChannel

public AgentChannel getChannel(String path)

Returns the channel specified by the given path.

Parameters:

path - Data channel path.

Returns:

Requested channel, or null if the channel is not being watched by this aggregator.

getAgentState

public org.lsst.ccs.bus.states.StateBundle getAgentState(String agentName)

Returns the current state of the specified Agent.

Parameters:

agentName - Name of the localAgent.

Returns:

State of the specified localAgent.

addListener

public void addListener(AgentStatusListener listener,
                        AgentChannelsFilter filter)

Adds a listener to be notified of changes in agents and channels specified by the filter.

The listener is added with the lists of agents and channels returned by the filter's getAgents() and getOriginChannels() methods, respectively, unless any of those methods returns null and the getDisplayChannels() method does not. In the latter case, the null list is replaced by the list reconstructed by applying getOriginPath(...) to the output of getDisplayChannels().

If the filter fires change event, the lists are re-evaluated, and the listener is notified through a configuration event.

Parameters:

listener - Listener to be added.

filter - Channels filter.

Throws:

NullPointerException - if either argument is null.

addListener

public void addListener(AgentStatusListener listener,
                        Collection<String> agents,
                        Collection<String> channels)

Adds a listener to be notified of changes in specified agents and data channels. Note that calling this method with both agents and channels arguments equal to null forces this aggregator to watch all channels from all agents.

The list of channels passed to this method may contain:

• Complete channel paths.
• Path templates in the "[Agent]/[partial path][/]" format. Templates that omit the Agent name are expanded against all agents whose names are in the agents list (or all agents present on the buses if that list is null). Templates that end with "/" match all channels that start with "Agent/partial path/".
• Selector strings in the "[agent.name=value&][agent.type=value&][agent.key[=value]&…&agent.key[=value]&][key[=value]&…&key[=value]]" format, where key and value are names and values of Agent properties or static channel attributes. If value is omitted, the existence of the attribute is checked. Note that, unlike templates, selectors are only applied to channels and their attributes as listed in the agent channels dictionary. Any channels not appearing in the dictionary are ignored, as are attribute changes.

The listener is notified of agent connection, configuration, and disconnection events if the agent name is in the supplied list of channels, or the list is null, or the Agent name is explicitly contained in any of the templates and selectors.

The listener is notified of value changes in data channels if:

• The channel path is contained in the supplied list of channels.
• The channel path matches any of the supplied templates.
• The channel satisfies any of the supplied selectors.

Unless the agent list is null, templates and selectors that do not explicitly specify agent names are only applied to agents whose names are on the localAgent list.

Parameters:

listener - Listener to be added.

agents - Names of agents the listener is interested in. If null, the listener will be notified of changes in all agents.

channels - Paths, templates, and selectors specifying channels the listener is interested in. If null, the listener is notified of changes in all channels from the specified agents. Supplying an empty list ensures that the listener is only notified of agent connections and disconnections.

Throws:

NullPointerException - if the listener argument is null.

removeListener

public void removeListener(AgentStatusListener listener)

Removes the specified listener. Also stops watching channels that were only watched because of this listener.

Parameters:

listener - Listener to be removed.