org.lsst.ccs.gconsole.base

Class Console

java.lang.Object

org.lsst.ccs.Agent

org.lsst.ccs.Subsystem

org.lsst.ccs.gconsole.base.Console

All Implemented Interfaces:

org.lsst.ccs.messaging.CommandExecutor, org.lsst.ccs.ServiceLifecycle

Direct Known Subclasses:

Jas3Console

public abstract class Console
extends org.lsst.ccs.Subsystem

Graphical Console subsystem. Provides all functionality of a CCS subsystem. Specifies additional services that should be provided by specific console implementations for use by plugins and tools.

Author:

onoprien

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Console.PropertyListener

Nested classes/interfaces inherited from class org.lsst.ccs.Agent

org.lsst.ccs.Agent.RunningCommand, org.lsst.ccs.Agent.ShutdownResult

Field Summary

Fields inherited from class org.lsst.ccs.Agent

AGENT_DESCRIPTION, AGENT_RUNTIMEINFO_TASK, commandExecutorLock, currentAction, currentQueries, currentSignals, jvmShutdown, logBusHandler, stateService, treeComponentInitialized

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Console()

Method Summary

Modifier and Type	Method and Description
abstract void	addMenu(Action action, String owner, String... locations) Adds an item to the graphical console menu bar.
abstract void	addPreference(String[] path, String group, String format) Adds a setter for one or more previously defined properties to the preferences menu.
abstract Object	addProperty(String key, Object defaultValue) Defines a console property with the specified default value.
abstract void	addPropertyListener(Console.PropertyListener listener, String filter) Registers a listener that will be notified of property changes.
void	afterStart()
abstract void	error(String message) Notifies the user of an application error.
abstract void	error(String message, Exception x) Notifies the user of an application error.
static Console	getConsole() Returns the singleton instance of Console.
abstract org.freehep.util.FreeHEPLookup	getConsoleLookup() Returns a lookup instance that can be used objects registered by various components of the graphical console.
abstract Path	getHomeDirectory() Returns the path to the graphical console home directory.
org.lsst.ccs.utilities.logging.Logger	getLoggerUI() Returns the default logger associated with the graphical console.
LsstOptionalPageService	getOptionalPageService()
abstract PanelManager	getPanelManager() Returns the instance of PanelManager that can be used to create and manage GUI panels.
abstract Object	getProperty(String key) Returns the value of the property with the specified key.
<T> T	getSingleton(Class<T> clazz) Returns a singleton instance of the specified type registered with this console.
AgentStatusAggregator	getStatusAggregator() Returns the status aggregator maintained by this console.
abstract Window	getWindow() Returns the root component for the main Graphical Console window.
abstract void	insertStatusBarComponent(JComponent component, int position)
abstract void	insertToolbarAction(Action action, int position) Inserts an action to the LSST CCS tool bar.
void	preShutdown()
void	preStart()
abstract boolean	removeMenu(String... locations) Removes the specified menu item and its descendents.
abstract Object	removeProperty(String key) Removes a console property.
abstract boolean	removePropertyListener(Console.PropertyListener listener) Removes the specified property listener.
abstract void	removeStatusBarComponent(JComponent component)
abstract void	restore() Restores console session from the default location.
abstract void	restoreFrom() Restores console session, prompting the user to specify location.
abstract void	save() Saves current session to the default location.
abstract void	saveAs() Saves current session, prompting the user to specify location.
abstract void	setBlockInput(boolean blocked) Blocks and unblocks mouse and key input to the console.
void	setProperties(Map<String,Object> properties) Sets values of a set of properties.
abstract Object	setProperty(String key, Object value) Sets the value of the specified property.
abstract void	setStatusMessage(String message) Sets the message in the graphical console status bar.
int	setStatusMessage(String message, int id) Sets the message in the graphical console status bar.
abstract void	showInBrowser(String url) Display the specified web site in a browser.

Methods inherited from class org.lsst.ccs.Subsystem

getLogHandler, getNumberCommandThreads, ping, printRunningCommands, setLogFormat, setLogHandlerLevel, setLogLevel, setStackTraceDepth

Methods inherited from class org.lsst.ccs.Agent

createHelper, executeCommandRequest, getAgentInfo, getAgentPersistenceService, getAgentService, getAgentServices, getCommandCount, getComponentConfigurationEnvironment, getComponentConfigurationEnvironmentByName, getComponentLookup, getCurrentAction, getDescription, getEnvironmentLockService, getEnvironmentMessagingAccess, getLogger, getMessagingAccess, getName, getScheduler, helper, initAgent, initLogBusHandler, isInEngineeringMode, populateComponentLookup, preInit, printComponentNodeTree, publishSubsystemDataOnStatusBus, sendAck, sendNack, sendStatusMessage, setAgentName, shutdownAgent, shutdownAgent, startAgent, vetoTransitionToNormalMode

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

afterBuild, afterInit, preBuild

Constructor Detail

Console

protected Console()

Method Detail

preStart

public void preStart()

Specified by:

preStart in interface org.lsst.ccs.ServiceLifecycle

Overrides:

preStart in class org.lsst.ccs.Agent

afterStart

public void afterStart()

preShutdown

public void preShutdown()

getConsole

public static Console getConsole()

Returns the singleton instance of Console.

Implementation note: At the moment, this method returns an instance of Jas3Console created when this class is loaded, breaking abstraction from the Console implementation. This should be fixed once the freehep-application framework initialization have been reworked to make them thread-safe and more flexible, so that Jas3Console can be loaded as a service.

Returns:

Singleton instance of Console.

getSingleton

public <T> T getSingleton(Class<T> clazz)

Returns a singleton instance of the specified type registered with this console.

Type Parameters:

T - Type of the singleton.

Parameters:

clazz - Class instance corresponding to the singleton type.

Returns:

The specified singleton, or null if it does not exist.

getConsoleLookup

public abstract org.freehep.util.FreeHEPLookup getConsoleLookup()

Returns a lookup instance that can be used objects registered by various components of the graphical console.

Returns:

Lookup instance.

getWindow

public abstract Window getWindow()

Returns the root component for the main Graphical Console window.

Returns:

root component for the main Graphical Console window, or null if the root component is not a Window.

getLoggerUI

public org.lsst.ccs.utilities.logging.Logger getLoggerUI()

Returns the default logger associated with the graphical console.

Returns:

The logger associated with the graphical console.

getHomeDirectory

public abstract Path getHomeDirectory()

Returns the path to the graphical console home directory. User preferences, console extensions, and miscellaneous auxiliary files saved by the graphical console are kept in this directory and its subdirectories.

Returns:

The path to the graphical console home directory.

getPanelManager

public abstract PanelManager getPanelManager()

Returns the instance of PanelManager that can be used to create and manage GUI panels.

Returns:

Panel manager used by this graphical console.

getStatusAggregator

public AgentStatusAggregator getStatusAggregator()

Returns the status aggregator maintained by this console.

Returns:

Status aggregator.

error

public abstract void error(String message)

Notifies the user of an application error.

Parameters:

message - Message to be displayed.

error

public abstract void error(String message,
                           Exception x)

Notifies the user of an application error.

Parameters:

message - Message to be displayed.

x - Exception to be reported.

showInBrowser

public abstract void showInBrowser(String url)

Display the specified web site in a browser.

Parameters:

url - URL of the site to be displayed.

setStatusMessage

public abstract void setStatusMessage(String message)

Sets the message in the graphical console status bar. Using this method modifies the text in the status bar without affecting the additional bookkeeping provided by the setStatusMessage(String, int) method.

Parameters:

message - The message to display; if null, the current message is cleared.

setStatusMessage

public int setStatusMessage(String message,
                            int id)

Sets the message in the graphical console status bar. This method provides simple bookkeeping that reduces interference between messages posted by various graphical console components.

If a message is submitted with zero ID, it is displayed immediately, and this method returns its newly assigned ID. If a message is submitted with non-zero ID, it replaces any previous messages with the same ID, but it is only displayed if or when the message it replaces would be displayed. The message keeps the ID of the message it replaces.

Calling this method with message == null clears the set of messages submitted with the same ID. If there is another set with a different ID that has not been cleared, the latest message of that set will be displayed. If this method is called with message == null and zero ID, all message sets are cleared.

Typically, this machinery is used when some graphical console component needs to display a status message temporarily. It first calls this method with zero ID to display the message, and then calls it with the ID returned by the first call and null message to clear the status bar.

Parameters:

message - The message to display, or null to clear the status bar.

id - The ID of the previously posted message this message should replace, or zero if this message is not associated with any of the previous messages.

Returns:

The ID assigned to the posted message.

setBlockInput

public abstract void setBlockInput(boolean blocked)

Blocks and unblocks mouse and key input to the console.

Parameters:

blocked - true if input should be blocked.

getOptionalPageService

public LsstOptionalPageService getOptionalPageService()

addProperty

public abstract Object addProperty(String key,
                                   Object defaultValue)

Defines a console property with the specified default value. Console properties can be later modified by calls to the setProperty(String, Object) method. Properties that have been modified from their default values are saved between the graphical console sessions.

If a property with the specified key already exists:

• if the specified default value is of the same type as the existing one, the call has no effect;
• if the existing default value is of type String but can be converted to the type of the newly specified default value, the existing default value is retained but the type of object returned by subsequent calls to getProperty(String) method is modified;
• if the specified default value is incompatible with the existing one, IllegalArgumentException is thrown;
• if the existing property does not have a default value, its current value is reset to the provided default.

When a property is retrieved with a call to getProperty(String) method, the type of the returned object is determined by the type of the default value supplied when the property was defined.

Parameters:

key - Property key. Can be used to retrieve the property value.

defaultValue - Default value for the property. Must be of type Boolean, Enum, Integer, Long, Double, String, or an array containing objects of these types.

Returns:

Current value of the property.

Throws:

IllegalArgumentException - If the specified key already exists, and its default value is incompatible with defaultValue; if either key or defaultValue is null; if the type of defaultValue is not supported.

removeProperty

public abstract Object removeProperty(String key)

Removes a console property.

Parameters:

key - Property key.

Returns:

Current value of the property, or null if there was no such property.

getProperty

public abstract Object getProperty(String key)

Returns the value of the property with the specified key. The type of the returned object is determined by the type of the default value supplied when the property was defined. If the property with the specified key has never been defined through a call to addProperty(String, Object) but exists in the console storage, it will be returned as a String.

Parameters:

key - Property key.

Returns:

Value of the specified property, or null if the property does not exist.

setProperty

public abstract Object setProperty(String key,
                                   Object value)

Sets the value of the specified property. If the property with the specified key has never been defined through a call to addProperty(String, Object) method, the value will be converted to a String and stored. Such keys cannot be used in setter format strings passed to addPreference(String[], String, String) method.

If the property value is set to null, it is removed from storage, so subsequent calls to getProperty(String) will return the default value, if it has been set.

Parameters:

key - Property key.

value - Property value, or null if the property is being reset to its default value.

Returns:

The previous value of the specified property, or null if the property did not exist.

Throws:

IllegalArgumentException - If the specified value is not type-compatible with the default value for the specified key.

setProperties

public void setProperties(Map<String,Object> properties)

Sets values of a set of properties. See setProperty(String, Object) for details on setting properties.

Parameters:

properties -

addPropertyListener

public abstract void addPropertyListener(Console.PropertyListener listener,
                                         String filter)

Registers a listener that will be notified of property changes.

Parameters:

listener - The listener to be notified.

filter - Regular expression the property key has to match to trigger notification.

removePropertyListener

public abstract boolean removePropertyListener(Console.PropertyListener listener)

Removes the specified property listener.

Parameters:

listener - Listener to be removed.

Returns:

True if the specified listener was registered with this console.

addPreference

public abstract void addPreference(String[] path,
                                   String group,
                                   String format)

Adds a setter for one or more previously defined properties to the preferences menu. The format string contains one or more property references in the ${key#qualifiers} form. Qualifiers are separated by "#". At the moment, the only supported qualifier is "history=N".

Parameters:

path - Path in the preferences tree to the page where the property setter should be displayed.

group - Group inside the preferences page. If null, the property setter is displayed in the default group.

format - Specifies the format of the property setter.

Throws:

IllegalArgumentException - If a property with the specified key already exists, and its value is incompatible with the provided default.

addMenu

public abstract void addMenu(Action action,
                             String owner,
                             String... locations)

Adds an item to the graphical console menu bar.

The location strings specify a hierarchy of menus above the added item. Each string should be in the name[[:group]:position] format, where name is the text label of the menu the item should be added to, group is the ordinal number of the item group inside the menu, and position is the position inside the group. The first location string can also be prefixed with the desired location on the menu bar: [barPosition:]name[[:group]:position]. The menu is divided into groups by separators. If the group number is negative, items added with the same group number but different owners are put into the same group. If the group is not specified or is equal to 0, the item is added to the default group. The default group is shared by all owners. Items added with the same non-zero position to the same group are sorted alphabetically.

Parameters:

action - Action for the menu item to be added.

owner - Owner of the added menu item.

locations - Strings that specifies locations of the added item at all levels in the menu hierarchy.

removeMenu

public abstract boolean removeMenu(String... locations)

Removes the specified menu item and its descendents.

Parameters:

locations - Hierarchy of menu item names, starting from the top level menu.

Returns:

true is some items have been removed.

insertToolbarAction

public abstract void insertToolbarAction(Action action,
                                         int position)

Inserts an action to the LSST CCS tool bar.

Parameters:

action - Action to insert.

position - Buttons are inserted in the increasing position order.

insertStatusBarComponent

public abstract void insertStatusBarComponent(JComponent component,
                                              int position)

removeStatusBarComponent

public abstract void removeStatusBarComponent(JComponent component)

restore

public abstract void restore()

Restores console session from the default location. No user interaction.

restoreFrom

public abstract void restoreFrom()

Restores console session, prompting the user to specify location. No user interaction.

save

public abstract void save()

Saves current session to the default location. No user interaction.

saveAs

public abstract void saveAs()

Saves current session, prompting the user to specify location.