org.lsst.ccs.gconsole.base

Class ConsolePluginServices

java.lang.Object

org.lsst.ccs.gconsole.base.ConsolePluginServices

All Implemented Interfaces:

Console.PropertyListener

public abstract class ConsolePluginServices
extends Object
implements Console.PropertyListener

Access to services provided by the framework to graphical console plugins. Each plugin has an instance of ConsolePluginServices associated with it.

Author:

onoprien

Field Summary

Fields

Modifier and Type	Field and Description
protected String	prefix

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ConsolePluginServices(Console console, ConsolePlugin plugin, ComponentDescriptor descriptor)

Method Summary

Modifier and Type	Method and Description
void	addMenu(Action action, String... locations) Adds an item to the graphical console menu bar.
void	addPreference(String[] path, String group, String format) Adds a setter for one or more previously defined properties to the preferences menu.
Object	addProperty(String key, Object defaultValue) Defines a plugin property with the specified default value.
Console	getConsole() Returns a reference to the graphical console subsystem.
ComponentDescriptor	getDescriptor() Returns the descriptor for the graphical console plugin associated with this ConsolePluginServices instance.
ConsolePlugin	getPlugin() Returns a reference to the graphical console plugin associated with this ConsolePluginServices instance.
Object	getProperty(String key) Returns the value of the property with the specified key.
void	propertiesChanged(Object source, Map<String,Object> changes) Called by the framework when plugin properties are modified.
Object	removeProperty(String key) Removes a plugin property.
void	setProperties(Map<String,Object> properties) Sets values of a set of properties.
Object	setProperty(String key, Object value) Sets the value of the specified plugin property.
void	start()
void	stop()
protected String	translatePropertyKey(String key)

Methods inherited from class java.lang.Object

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

Field Detail

prefix

protected final String prefix

Constructor Detail

ConsolePluginServices

protected ConsolePluginServices(Console console,
                                ConsolePlugin plugin,
                                ComponentDescriptor descriptor)

Method Detail

start

public void start()

stop

public void stop()

getConsole

public Console getConsole()

Returns a reference to the graphical console subsystem.

Returns:

Graphical console subsystem instance.

getPlugin

public ConsolePlugin getPlugin()

Returns a reference to the graphical console plugin associated with this ConsolePluginServices instance.

Returns:

Graphical console plugin.

getDescriptor

public ComponentDescriptor getDescriptor()

Returns the descriptor for the graphical console plugin associated with this ConsolePluginServices instance.

Returns:

Graphical console plugin descriptor.

addMenu

public void addMenu(Action action,
                    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 by different plugins 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 plugins.

Parameters:

action - Action for the menu item to be added.

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

addProperty

public Object addProperty(String key,
                          Object defaultValue)

Defines a plugin 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 Object removeProperty(String key)

Removes a plugin property. If the specified property has been previously defined through a call to addProperty(String, Object) method, the property is removed and its current value is removed from storage; calling this method for a property that has not been defined has no effect.

Parameters:

key - Property key.

Returns:

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

addPreference

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

Adds a setter for one or more previously defined properties to the preferences menu.

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.

getProperty

public 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.

Throws:

IllegalArgumentException - If the stored value is of type incompatible with the property type.

setProperty

public Object setProperty(String key,
                          Object value)

Sets the value of the specified plugin 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.

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 -

translatePropertyKey

protected String translatePropertyKey(String key)

propertiesChanged

public void propertiesChanged(Object source,
                              Map<String,Object> changes)

Description copied from interface: Console.PropertyListener

Called by the framework when plugin properties are modified.

Specified by:

propertiesChanged in interface Console.PropertyListener

Parameters:

source - Source of notification.

changes - For the changed properties, map of keys to their new values.