org.lsst.ccs.scripting

Class CCS

java.lang.Object

org.lsst.ccs.scripting.CCS

public abstract class CCS
extends Object

Main scripting entry point to CCS. This class is used to create scripting entry points to CCS subsystems through ScriptingSubsystemWrapper, register a ScriptingStatusBusListener to listen to Status messages on the CCS Status Bus and to suspend the script execution until a given Status message meets the criteria of a filter: ScriptingStatusBusMessageFilter.

Author:

The LSST CCS Team

Method Summary

Modifier and Type	Method and Description
static void	addStatusBusListener(ScriptingStatusBusListener listener) Add a Status bus listener.
static void	addStatusBusListener(ScriptingStatusBusListener listener, ScriptingStatusBusMessageFilter filter) Add a Status bus listener with a filter.
static ScriptingSubsystemWrapper	attachSubsystem(String target) Creates and instance of a ScriptingSubsystemWrapper by making sure that the given target corresponds to a CCS subsystem that is currently available, not locked and alive.
static ScriptingSubsystemWrapper	attachSubsystem(String target, boolean lock) Creates and instance of a ScriptingSubsystemWrapper by making sure that the given target corresponds to a CCS subsystem that is currently alive.
static ScriptingSubsystemWrapper	attachSubsystem(String target, int level) Creates and instance of a ScriptingSubsystemWrapper by making sure that the given target corresponds to a CCS subsystem that is currently available, not locked and alive.
static void	cleanUp() Clean up the ThreadLocal stack, (close all subsystems and remove all listeners).
static int	getDefaultTimeout() Get the default timeout to be used when sending commands.
static AgentMessagingLayer	getMessagingAccess()
protected static List<String>	getTargetsForSubsystem(String subsystemName)
static boolean	getThrowExceptions() Returns true if exceptions are thrown, otherwise they are returned as the Object on the invoke methods.
static void	initializeScriptingEnvironment() In a test context, this method has to be called in the first place
static void	removeStatusBusListener(ScriptingStatusBusListener listener) Removes the Status bus listener.
static void	setDefaultTimeout(int timeout) Set the default timeout to be used when sending commands.
static void	setShareLocksAcrossThreads(boolean shareLocks) Indicates whether locks should be shared across threads or made exclusive to the calling thread.
static void	setThrowExceptions(boolean throwExceptions) In the scripting environment, exceptions resulted from method invocation can either be thrown or returned.
static void	shutdownScriptingEnvironment() In a test context, this method has to be called in the first place
static Future<ScriptingStatusBusMessage>	startListeningForStatusBusMessage(ScriptingStatusBusMessageFilter filter, int timeout) Get a Future on a ScriptingStatusBusMessage.

Methods inherited from class java.lang.Object

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

Method Detail

getMessagingAccess

public static AgentMessagingLayer getMessagingAccess()

setDefaultTimeout

public static void setDefaultTimeout(int timeout)

Set the default timeout to be used when sending commands. The default timeout is in seconds and must be greater than zero. The default timeout will be used when: - no timeout is specified when invoking a command - no timeout is returned in the command ack as received from the command invocation over the buses

Parameters:

timeout - The default timeout in seconds.

getDefaultTimeout

public static int getDefaultTimeout()

Get the default timeout to be used when sending commands.

Returns:

The default timeout in seconds.

setShareLocksAcrossThreads

public static void setShareLocksAcrossThreads(boolean shareLocks)

Indicates whether locks should be shared across threads or made exclusive to the calling thread.

Parameters:

shareLocks -

initializeScriptingEnvironment

public static void initializeScriptingEnvironment()

In a test context, this method has to be called in the first place

shutdownScriptingEnvironment

public static void shutdownScriptingEnvironment()
                                         throws Exception

In a test context, this method has to be called in the first place

Throws:

Exception

setThrowExceptions

public static void setThrowExceptions(boolean throwExceptions)

In the scripting environment, exceptions resulted from method invocation can either be thrown or returned. Use this method to toggle between the two options.

Parameters:

throwExceptions - boolean flag. If true exceptions will be thrown.

getThrowExceptions

public static boolean getThrowExceptions()

Returns true if exceptions are thrown, otherwise they are returned as the Object on the invoke methods.

Returns:

true/false to indicate if exceptions are thrown/returned

attachSubsystem

public static ScriptingSubsystemWrapper attachSubsystem(String target)
                                                 throws RuntimeException

Creates and instance of a ScriptingSubsystemWrapper by making sure that the given target corresponds to a CCS subsystem that is currently available, not locked and alive. That method will attempt to acquire a lock on the subsystem. Note : it is equivalent to attachSubsystem(target, true)

Parameters:

target - The name of the CCS subsystem. e.g. ccs-rafts, or one of its inner component, e.g. ccs-rafts/REB1

Returns:

The ScriptingSubsystemWrapper representing the CCS subsystem

Throws:

RuntimeException - if no subsystem corresponding to target can be found on the buses, or if the subsystem could not be locked.

attachSubsystem

public static ScriptingSubsystemWrapper attachSubsystem(String target,
                                                        int level)
                                                 throws Exception

Creates and instance of a ScriptingSubsystemWrapper by making sure that the given target corresponds to a CCS subsystem that is currently available, not locked and alive. That method will attempt to acquire a lock on the subsystem, and to override the obtained lock's level with the given level.

Parameters:

target - The name of the CCS subsystem. e.g. ccs-rafts, or one of its inner component, e.g. ccs-rafts/REB1

level - a level that overrides the acquired lock level.

Returns:

The ScriptingSubsystemWrapper representing the CCS subsystem

Throws:

Exception - if no subsystem corresponding to target can be found on the buses, or if the subsystem could not be locked.

attachSubsystem

public static ScriptingSubsystemWrapper attachSubsystem(String target,
                                                        boolean lock)
                                                 throws Exception

Creates and instance of a ScriptingSubsystemWrapper by making sure that the given target corresponds to a CCS subsystem that is currently alive. That method will attempt to acquire a lock only if lock is set to true.

Parameters:

target - The name of the CCS subsystem. e.g. ccs-rafts, or one of its inner component, e.g. ccs-rafts/REB1

lock - true if the subsystem should be locked, false otherwise.

Returns:

The ScriptingSubsystemWrapper representing the CCS subsystem

Throws:

Exception - if no subsystem corresponding to target can be found on the buses, or if the subsystem could not be locked.

cleanUp

public static void cleanUp()

Clean up the ThreadLocal stack, (close all subsystems and remove all listeners).

addStatusBusListener

public static void addStatusBusListener(ScriptingStatusBusListener listener)

Add a Status bus listener.

Parameters:

listener - The ScriptingStatusListener

addStatusBusListener

public static void addStatusBusListener(ScriptingStatusBusListener listener,
                                        ScriptingStatusBusMessageFilter filter)

Add a Status bus listener with a filter.

Parameters:

listener - The ScriptingStatusListener

filter - The ScriptingStatusBusMessageFilter

removeStatusBusListener

public static void removeStatusBusListener(ScriptingStatusBusListener listener)

Removes the Status bus listener.

Parameters:

listener - The listener to be removed.

startListeningForStatusBusMessage

public static Future<ScriptingStatusBusMessage> startListeningForStatusBusMessage(ScriptingStatusBusMessageFilter filter,
                                                                                  int timeout)

Get a Future on a ScriptingStatusBusMessage. The content of the Future is filled when the first StatusBusMessage that satisfies the ScriptingStatusBusMessageFilter is received. When the Future is exercised it will return the first ScriptingStatusBusMessage or an ExecutionException will be thrown when the timeout is reached.

Parameters:

filter - ScriptingStatusBusMessageFilter The message filter

timeout - Timeout in seconds, after which a ScriptiongTimeoutException is thrown. This timeout is from the time the method is invoked. If this timeout is reached an exception will be thrown if/when the Future is exercised.

Returns:

A Future on a ScriptingStatusBusMessage.

getTargetsForSubsystem

protected static List<String> getTargetsForSubsystem(String subsystemName)