org.openbp.jaspira.plugin
Class AbstractPlugin

java.lang.Object
  org.openbp.jaspira.plugin.AbstractPlugin

All Implemented Interfaces:

Plugin

Direct Known Subclasses:

AbstractVisiblePlugin, ApplicationBase, AssociationPlugin, ClipboardPlugin, CommandLinePlugin, DebuggerPlugin, DisplayObjectPlugin, ErrorDialogPlugin, ExternalAssociationPlugin, FinderPlugin, GeneratorPlugin, ItemOpenDispatcherPlugin, ModelerOptionPlugin, ModelerUndoPlugin, OptionMgr, ServerConnectionPlugin, SkinPlugin

public abstract class AbstractPlugin
extends java.lang.Object
implements Plugin

Abstract superclass for plugins.

Author:

Stephan Moritz

Nested Class Summary

class

AbstractPlugin.StandardPluginEvents Event module.

Field Summary

static java.lang.String	PROPERTY_CONDITION Conditional expression resource key
static java.lang.String	PROPERTY_DESCRIPTION Description resource key
static java.lang.String	PROPERTY_ICON Icon resource key
static java.lang.String	PROPERTY_NAME Plugin name resource key
static java.lang.String	PROPERTY_SEQUENCE Key sequence to show the plugin
static java.lang.String	PROPERTY_TITLE Title resource key
static java.lang.String	PROPERTY_VENDOR Vendor resource key
static java.lang.String	PROPERTY_VERSION Version resource key

Fields inherited from interface org.openbp.jaspira.plugin.Plugin

ID_DELIMETER, LEVEL_APPLICATION, LEVEL_FRAME, LEVEL_PAGE, LEVEL_PLUGIN

Constructor Summary

AbstractPlugin()
Standard constructor.

Method Summary

protected void	addActionKeySequence(KeySequence sequence, JaspiraAction action) Adds a key sequence that triggers the given action.
void	addPlugin(Plugin child) Adds a plugin as child plugin of this plugin.
void	addToPeerGroup(java.lang.String peerName, java.lang.Object group) Adds the plugin to a peer group given by key and object.
boolean	canClose() Checks, whether this plugin can be closed.
protected void	closeCanceled() This method is called when the closing has been vetoed by a plugin.
boolean	containsStackedEvent(java.lang.String eventName) Checks if the event stack contains a particular event.
boolean	fireEvent(JaspiraEvent je) Fires the given event using the event queue.
boolean	fireEvent(java.lang.String eventName) Creates a new client event using the given event name and fires it.
boolean	fireEvent(java.lang.String eventName, java.lang.Object data) Creates a new client event using the given event name and event object and fires it.
JaspiraAction	getAction(java.lang.String actionName) This convenience method retrieves an action from the action manager.
java.util.List	getChildPlugins() Returns a list of all children of this plugin.
java.lang.String	getClassName() Returns the class name of the plugin.
java.lang.String	getCondition() Gets the conditional expression that determines if the plugin should be active.
java.util.List	getDescendantPlugins(java.util.List result) Returns a list of all children and further descendants of this plugin.
java.lang.String	getDescription() Gets the description.
java.util.List	getEventActionNames() Gets a list of the action names of the event actions of this plugin.
protected java.util.List	getEventModules() Returns a list of the event modules of this plugin.
protected java.util.Collection	getExternalActions() Returns a collection of the external actions of this plugin.
protected java.lang.Class[]	getExternalEventModuleClasses() Returns the list of external event module classes.
protected java.lang.Class[]	getExternalOptionModuleClasses() Returns a list of external option module classes of this plugin.
MultiIcon	getIcon() Gets the icon.
MultiIcon	getIcon(java.lang.String iconName) Convenience method for retrieving an icon from the resourcepackage.
int	getLevel() Returns the level of this plugin in the plugin tree.
java.lang.String	getName() Returns the name of the plugin.
protected java.util.List	getOptionModules() Returns a list of all option modules of this plugin.
Plugin	getParentPlugin() Returns the parent plugin of this plugin.
java.lang.Object	getPeerGroup(java.lang.String peerName) Gets the peer group for the given group name.
java.util.Set	getPeerGroupNames() Returns the names of all peergroups that this plugin has been added to.
java.util.Set	getPeerGroups() Returns the peer groups this plugin has been added to.
ResourceCollection	getPluginResourceCollection() Gets the plugin resource.
PluginState	getPluginState() Returns the state of this plugin.
abstract java.lang.String	getResourceCollectionContainerName() Gets the name of the resource component the default resource of the plugin belongs to.
java.util.List	getSubClients() Gets the Dnd sub clients of this plugin.
java.lang.String	getSubTitle() Returns the sub title of this plugin.
java.lang.String	getTitle() Gets the title.
java.lang.String	getUniqueId() Returns the unique id of this plugin.
java.lang.String	getVendor() Gets the plugin vendor.
java.lang.String	getVersion() Gets the plugin version.
boolean	handleEvent(JaspiraEvent je) Tries to handles the event for this plugin without passing it on.
protected boolean	handleKeySequence(KeySequence ks) Invokes the action associated with the given key sequence if applicable.
boolean	inheritEvent(JaspiraEvent je) Receives an event incoming from a parent.
protected void	initializeFromPluginProfile(PluginProfile profile) Initializes some properties from the given plugin profile.
void	initializePlugin() Initializes the plugin.
protected void	initializeResources() Loads the plugin resources.
void	installFirstPlugin() This template method is called before the first plugin instance of this kind is installed.
void	installPlugin() Installs the plugin and all its modules.
protected void	installPluginContent() Installs the contents of the plugin.
boolean	matchesPeerGroup(java.lang.String peerName, java.lang.Object group, boolean strict) Check if the plugin is a member of the given peer group.
boolean	matchesPeerGroups(Plugin plugin, boolean strict) Matches all peer groups of one plugin against another.
protected boolean	passDown(JaspiraEvent je) Passes an event down to the child plugins.
protected void	pluginInstalled() This template method is called after the plugin has been installed.
protected void	pluginUninstalled() This template method is called before the plugin is uninstalled.
protected void	preClose() This method is called when actual closing is performed.
boolean	receiveEvent(JaspiraEvent je) Handles an incoming event that is received from a child plugin.
void	removeFromPeerGroup(java.lang.String peerName) Removes the plugin from a peer group.
void	removePlugin(Plugin child) Removes a child plugin from this plugin.
void	removeStackedEvent(java.lang.String eventName) Removes any events with the given name from the event stack.
boolean	requestClose() Request the plugin to be closed.
void	setDescription(java.lang.String description) Sets the description.
void	setIcon(MultiIcon icon) Sets the icon.
void	setName(java.lang.String name) Sets the plugin name (can be null).
void	setParentPlugin(Plugin newParent) Sets the parent plugin of this plugin.
void	setPluginState(PluginState state) Rebuilds the state of the plugin using the given state object.
void	setResourceCollection(ResourceCollection resourceCollection) Sets the plugin resource.
void	setTitle(java.lang.String title) Sets the title.
void	stackEvent(JaspiraEvent je) Adds a stackable event to the event stack.
java.lang.String	toString() Returns a string representation of this plugin
void	uninstallLastPlugin() This is called after uninstall for the last instance has been uninstalled.
void	uninstallPlugin() Uninstalls the plugin and all of its modules.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_DESCRIPTION

public static final java.lang.String PROPERTY_DESCRIPTION

Description resource key

See Also:

Constant Field Values

PROPERTY_NAME

public static final java.lang.String PROPERTY_NAME

Plugin name resource key

See Also:

Constant Field Values

PROPERTY_TITLE

public static final java.lang.String PROPERTY_TITLE

Title resource key

See Also:

Constant Field Values

PROPERTY_ICON

public static final java.lang.String PROPERTY_ICON

Icon resource key

See Also:

Constant Field Values

PROPERTY_VERSION

public static final java.lang.String PROPERTY_VERSION

Version resource key

See Also:

Constant Field Values

PROPERTY_VENDOR

public static final java.lang.String PROPERTY_VENDOR

Vendor resource key

See Also:

Constant Field Values

PROPERTY_SEQUENCE

public static final java.lang.String PROPERTY_SEQUENCE

Key sequence to show the plugin

See Also:

Constant Field Values

PROPERTY_CONDITION

public static final java.lang.String PROPERTY_CONDITION

Conditional expression resource key

See Also:

Constant Field Values

Constructor Detail

AbstractPlugin

public AbstractPlugin()

Standard constructor. Note that all plugins should provide an empty constructor and that they are usually instantiated via the plugin manager as opposed to this constructor.

Method Detail

initializePlugin

public void initializePlugin()

Initializes the plugin. Should only be called by the plugin manager.

Specified by:

initializePlugin in interface Plugin

installPlugin

public void installPlugin()

Installs the plugin and all its modules. Should only be called by the plugin manager.

Specified by:

installPlugin in interface Plugin

installPluginContent

protected void installPluginContent()

Installs the contents of the plugin.

uninstallPlugin

public void uninstallPlugin()

Uninstalls the plugin and all of its modules. Never call this method directly, use PluginMgr.removeInstance(Plugin) instead.

Specified by:

uninstallPlugin in interface Plugin

installFirstPlugin

public void installFirstPlugin()

This template method is called before the first plugin instance of this kind is installed. Can be used to implement peer group behaviour.
Called by the plugin manager before the initializePlugin() method has been called.
If you override this method, make sure to call super.installFirst().

Specified by:

installFirstPlugin in interface Plugin

uninstallLastPlugin

public void uninstallLastPlugin()

This is called after uninstall for the last instance has been uninstalled. Called by the plugin manager after the uninstallLastPlugin() method has been called.
If you override this method, make sure to call super.uninstallLast().

Specified by:

uninstallLastPlugin in interface Plugin

initializeResources

protected void initializeResources()

Loads the plugin resources.

initializeFromPluginProfile

protected void initializeFromPluginProfile(PluginProfile profile)

Initializes some properties from the given plugin profile.

Parameters:

profile - Profile

addActionKeySequence

protected void addActionKeySequence(KeySequence sequence,
                                    JaspiraAction action)

Adds a key sequence that triggers the given action.

Parameters:

sequence - Sequence to add

action - Action to execute if the sequence is recognized

toString

public java.lang.String toString()

Returns a string representation of this plugin

Overrides:

toString in class java.lang.Object

Returns:

tile (uniqueId) [child plugins, ...]

pluginInstalled

protected void pluginInstalled()

This template method is called after the plugin has been installed.

pluginUninstalled

protected void pluginUninstalled()

This template method is called before the plugin is uninstalled.

getExternalOptionModuleClasses

protected java.lang.Class[] getExternalOptionModuleClasses()

Returns a list of external option module classes of this plugin. Override this method to customize the plugin.

Returns:

An array of classes or null (the default) if the plugin doesn't declare external option modules. The returned classes need to subclass OptionModule .

getExternalEventModuleClasses

protected java.lang.Class[] getExternalEventModuleClasses()

Returns the list of external event module classes. Override this method to customize the plugin.

Returns:

An array of classes or null (the default) if the plugin doesn't declare external event modules. The returned classes need to subclass ExternalEventModule

getExternalActions

protected java.util.Collection getExternalActions()

Returns a collection of the external actions of this plugin. Override this method to customize the plugin.

Returns:

A collection of JaspiraAction objects or null

getSubClients

public java.util.List getSubClients()

Gets the Dnd sub clients of this plugin.

Returns:

A list containing this object if it is a InteractionClient or null otherwise

fireEvent

public boolean fireEvent(JaspiraEvent je)

Fires the given event using the event queue.

Specified by:

fireEvent in interface Plugin

Parameters:

je - Event to fire

Returns:

true If the event was consumed by a plugin
false Otherwise

fireEvent

public boolean fireEvent(java.lang.String eventName)

Creates a new client event using the given event name and fires it.

Specified by:

fireEvent in interface Plugin

Parameters:

eventName - Name of the event

Returns:

true If the event was consumed by a plugin
false Otherwise

fireEvent

public boolean fireEvent(java.lang.String eventName,
                         java.lang.Object data)

Creates a new client event using the given event name and event object and fires it.

Specified by:

fireEvent in interface Plugin

Parameters:

eventName - Name of the event

data - Event object

Returns:

true If the event was consumed by a plugin
false Otherwise

passDown

protected boolean passDown(JaspiraEvent je)

Passes an event down to the child plugins.

Parameters:

je - Event to pass

Returns:

true If the event was consumed by a child plugin
false Otherwise

handleEvent

public boolean handleEvent(JaspiraEvent je)

Tries to handles the event for this plugin without passing it on. Stackable events will be stacked.

Specified by:

handleEvent in interface Plugin

Parameters:

je - The event to handle

Returns:

true If the event was consumed by the plugin
false Otherwise

receiveEvent

public boolean receiveEvent(JaspiraEvent je)

Handles an incoming event that is received from a child plugin. Passes this event to all other children if necessary (flood events).

Specified by:

receiveEvent in interface Plugin

Parameters:

je - The event to handle

Returns:

true If the event was consumed by the plugin
false Otherwise

inheritEvent

public boolean inheritEvent(JaspiraEvent je)

Receives an event incoming from a parent. This event is first passed down to the children, than handeled by the plugin itself. It is not passed upwards.

Specified by:

inheritEvent in interface Plugin

Parameters:

je - The event to handle

Returns:

true If the event was consumed by the plugin
false Otherwise

stackEvent

public void stackEvent(JaspiraEvent je)

Adds a stackable event to the event stack. If the event is already part of the stack, moves it to the end.

Specified by:

stackEvent in interface Plugin

Parameters:

je - The event to stack

containsStackedEvent

public boolean containsStackedEvent(java.lang.String eventName)

Checks if the event stack contains a particular event.

Specified by:

containsStackedEvent in interface Plugin

Parameters:

eventName - Event to look for

Returns:

true The event stack contains an event of this type.
false The event stack does not contain such an event.

removeStackedEvent

public void removeStackedEvent(java.lang.String eventName)

Removes any events with the given name from the event stack.

Parameters:

eventName - Event to remove

getChildPlugins

public java.util.List getChildPlugins()

Returns a list of all children of this plugin.

Specified by:

getChildPlugins in interface Plugin

Returns:

The child plugin list or null if there are no child plugins

getDescendantPlugins

public java.util.List getDescendantPlugins(java.util.List result)

Returns a list of all children and further descendants of this plugin.

Specified by:

getDescendantPlugins in interface Plugin

Parameters:

result - The children of this plugin will be added to this list, if given

Returns:

The list argument or a new linked list if null

getParentPlugin

public Plugin getParentPlugin()

Returns the parent plugin of this plugin. Each plugin except ApplicationBase must have a parent.

Specified by:

getParentPlugin in interface Plugin

Returns:

Parent of this plugin or null in case of ApplicationBase

setParentPlugin

public void setParentPlugin(Plugin newParent)

Sets the parent plugin of this plugin. Each plugin except ApplicationBase must have a parent.

Specified by:

setParentPlugin in interface Plugin

Parameters:

newParent - New parent of this plugin or null in case of ApplicationBase

addPlugin

public void addPlugin(Plugin child)

Adds a plugin as child plugin of this plugin.

Specified by:

addPlugin in interface Plugin

Parameters:

child - Child plugin to add

removePlugin

public void removePlugin(Plugin child)

Removes a child plugin from this plugin.

Specified by:

removePlugin in interface Plugin

Parameters:

child - Child plugin to remove

getLevel

public int getLevel()

Returns the level of this plugin in the plugin tree. The level corresponds to the hierarchy level in the plugin tree. The level of a child plugin is always 1 higher as the level of its parent.

Specified by:

getLevel in interface Plugin

Returns:

The level with Plugin.LEVEL_APPLICATION being the lowest. Defaults to Plugin.LEVEL_PLUGIN.

handleKeySequence

protected boolean handleKeySequence(KeySequence ks)

Invokes the action associated with the given key sequence if applicable.

Parameters:

ks - Key sequence to handle

Returns:

True if this sequence has been handeled, false otherwise

getResourceCollectionContainerName

public abstract java.lang.String getResourceCollectionContainerName()

Gets the name of the resource component the default resource of the plugin belongs to.

Returns:

The container name

getPluginResourceCollection

public ResourceCollection getPluginResourceCollection()

Gets the plugin resource.

Specified by:

getPluginResourceCollection in interface Plugin

setResourceCollection

public void setResourceCollection(ResourceCollection resourceCollection)

Sets the plugin resource.

getTitle

public java.lang.String getTitle()

Gets the title.

Specified by:

getTitle in interface Plugin

setTitle

public void setTitle(java.lang.String title)

Sets the title.

getSubTitle

public java.lang.String getSubTitle()

Returns the sub title of this plugin. This defaults to the title itself.

Specified by:

getSubTitle in interface Plugin

getDescription

public java.lang.String getDescription()

Gets the description.

Specified by:

getDescription in interface Plugin

setDescription

public void setDescription(java.lang.String description)

Sets the description.

getIcon

public MultiIcon getIcon()

Gets the icon.

Specified by:

getIcon in interface Plugin

setIcon

public void setIcon(MultiIcon icon)

Sets the icon.

getVendor

public java.lang.String getVendor()

Gets the plugin vendor.

Specified by:

getVendor in interface Plugin

getVersion

public java.lang.String getVersion()

Gets the plugin version.

Specified by:

getVersion in interface Plugin

getCondition

public java.lang.String getCondition()

Gets the conditional expression that determines if the plugin should be active.

Specified by:

getCondition in interface Plugin

getPluginState

public PluginState getPluginState()

Returns the state of this plugin.

Specified by:

getPluginState in interface Plugin

setPluginState

public void setPluginState(PluginState state)

Rebuilds the state of the plugin using the given state object.

Specified by:

setPluginState in interface Plugin

getName

public final java.lang.String getName()

Returns the name of the plugin.

Specified by:

getName in interface Plugin

Returns:

By default, this is the fully qualified class name (see getClassName()) unless not otherwise set or specified in the resource file.

setName

public void setName(java.lang.String name)

Sets the plugin name (can be null).

getClassName

public java.lang.String getClassName()

Returns the class name of the plugin.

Specified by:

getClassName in interface Plugin

Returns:

The name of the plugin class (the class that implements this interface)

getUniqueId

public final java.lang.String getUniqueId()

Returns the unique id of this plugin.

Specified by:

getUniqueId in interface Plugin

getEventModules

protected final java.util.List getEventModules()

Returns a list of the event modules of this plugin.

Returns:

A list of EventModule objects or null if the plugin does not define event modules as inner classes

getOptionModules

protected final java.util.List getOptionModules()

Returns a list of all option modules of this plugin.

Returns:

A list of OptionModule objects or null

getEventActionNames

public java.util.List getEventActionNames()

Gets a list of the action names of the event actions of this plugin.

Specified by:

getEventActionNames in interface Plugin

Returns:

A list of strings or null if this module does not contain action event handlers

getAction

public JaspiraAction getAction(java.lang.String actionName)

This convenience method retrieves an action from the action manager.

Specified by:

getAction in interface Plugin

Parameters:

actionName - Action name

Returns:

The action or null if no such action exists

getIcon

public MultiIcon getIcon(java.lang.String iconName)

Convenience method for retrieving an icon from the resourcepackage.

Parameters:

iconName - Icon resource name

Returns:

The icon

getPeerGroups

public java.util.Set getPeerGroups()

Returns the peer groups this plugin has been added to.

Specified by:

getPeerGroups in interface Plugin

Returns:

A set of objects denoting the peer groups or null if this plugin does not belong to any peer group

getPeerGroupNames

public java.util.Set getPeerGroupNames()

Returns the names of all peergroups that this plugin has been added to.

Specified by:

getPeerGroupNames in interface Plugin

Returns:

A set of strings (peer group names) or null if this plugin does not belong to any peer group

addToPeerGroup

public void addToPeerGroup(java.lang.String peerName,
                           java.lang.Object group)

Adds the plugin to a peer group given by key and object.

Specified by:

addToPeerGroup in interface Plugin

Parameters:

peerName - Peer group name

group - Peer group object

getPeerGroup

public java.lang.Object getPeerGroup(java.lang.String peerName)

Gets the peer group for the given group name.

Specified by:

getPeerGroup in interface Plugin

Parameters:

peerName - Name of the peer group

Returns:

The peer group or null if this group is not defined for the plugin

removeFromPeerGroup

public void removeFromPeerGroup(java.lang.String peerName)

Removes the plugin from a peer group.

Specified by:

removeFromPeerGroup in interface Plugin

Parameters:

peerName - Peer group name

matchesPeerGroup

public boolean matchesPeerGroup(java.lang.String peerName,
                                java.lang.Object group,
                                boolean strict)

Check if the plugin is a member of the given peer group. Eithe the group or the group name must be given.

Specified by:

matchesPeerGroup in interface Plugin

Parameters:

peerName - Name of the peer group to check

group - Peer group to check

strict - true The peergroups must be exactly met.
false null as group on one side is sufficient.

Returns:

true If the peer group matches.
false Otherwise

matchesPeerGroups

public boolean matchesPeerGroups(Plugin plugin,
                                 boolean strict)

Matches all peer groups of one plugin against another.

Specified by:

matchesPeerGroups in interface Plugin

Parameters:

plugin - Plugin to match agains this plugin

strict - true All peer groups must match.
false A single peer group must match.

Returns:

true If both plugins contain at least one common peergroup.
If the strict parameter is true, there may not be any different groups.
Plugins with empty peergroups ALWAYS match! false Otherwise

canClose

public boolean canClose()

Checks, whether this plugin can be closed. Note that this method does not necessarily mean that the plugin WILL be closed. Overwrite this method to handle unsafe states or user interaction. Calling of this method is always followed by either preClose() or closeCanceled().

Specified by:

canClose in interface Plugin

Returns:

True if this plugin can be closed right now

requestClose

public boolean requestClose()

Request the plugin to be closed. The plugin should check whether this is currently possible an if so do it. The default implementation will issue a global.askclose veto event to all its child plugins and itself.
If this event has been vetoed, it will broadcast a global.closecanceled event to itself and the childs. Otherwise, it will bradcast a global.doclose event, which in turn will call preClose() and then remove the plugin instance. So if a plugin is being closed, all its children will be closed, too.

Specified by:

requestClose in interface Plugin

Returns:

true If the plugin has been closed
false Otherwise

preClose

protected void preClose()

This method is called when actual closing is performed.

closeCanceled

protected void closeCanceled()

This method is called when the closing has been vetoed by a plugin.