org.openbp.jaspira.plugin
Interface Plugin

All Known Subinterfaces:

DrawingEditorPlugin, VisiblePlugin

All Known Implementing Classes:

AboutBoxPlugin, AbstractPlugin, AbstractVisiblePlugin, ApplicationBase, AssociationPlugin, ClipboardPlugin, Cockpit, CockpitAboutBox, ColorChooserPlugin, CommandLinePlugin, DebuggerPlugin, DisplayObjectPlugin, ErrorDialogPlugin, ExternalAssociationPlugin, FinderPlugin, FinderResultPlugin, GeneratorPlugin, InfoPanelPlugin, InspectorPlugin, ItemBrowserPlugin, ItemOpenDispatcherPlugin, JaspiraPage, JaspiraPageContainer, MiniViewPlugin, Modeler, ModelerOptionPlugin, ModelerPage, ModelerUndoPlugin, NodeEditorItemBrowserPlugin, NodeItemEditorPage, NodeItemEditorPlugin, OptionMgr, PluginMgrPlugin, PropertyBrowserPlugin, ServerConnectionPlugin, SkinPlugin, SocketToolBoxPlugin, StackTracePlugin, StandardToolBoxPlugin, StatusBarPlugin, ToolBoxPlugin, UserToolBoxPlugin, VariablesPlugin

public interface Plugin

Generic interface for plugins. A plugin is an encapsulation for a group of actions, options, and event handling modules.

Author:

Stephan Moritz

Field Summary

static java.lang.String	ID_DELIMETER Delimeter for the unique id of a plugin
static int	LEVEL_APPLICATION Plugin level: application
static int	LEVEL_FRAME Plugin level: frame
static int	LEVEL_PAGE Plugin level: page
static int	LEVEL_PLUGIN Plugin level: regular plugin

Method Summary

void	addPlugin(Plugin child) Adds a plugin as child plugin of this plugin.
void	addToPeerGroup(java.lang.String name, 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.
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 plugins) 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.
MultiIcon	getIcon() Gets the icon.
int	getLevel() Returns the level of this plugin in the plugin tree.
java.lang.String	getName() Returns the name of the plugin.
Plugin	getParentPlugin() Returns the parent plugin of this plugin.
java.lang.Object	getPeerGroup(java.lang.String name) 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.
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.
boolean	inheritEvent(JaspiraEvent je) Receives an event incoming from a parent.
void	initializePlugin() Initializes the plugin.
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.
boolean	matchesPeerGroup(java.lang.String name, 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.
boolean	receiveEvent(JaspiraEvent je) Handles an incoming event that is received from a child plugin.
void	removeFromPeerGroup(java.lang.String name) Removes the plugin from a peer group.
void	removePlugin(Plugin child) Removes a child plugin from this plugin.
boolean	requestClose() Request the plugin to be closed.
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	stackEvent(JaspiraEvent je) Adds a stackable event to the event stack.
void	uninstallLastPlugin() This is called after uninstall for the last instance has been uninstalled.
void	uninstallPlugin() Uninstalls the plugin and all of its modules.

Field Detail

LEVEL_APPLICATION

static final int LEVEL_APPLICATION

Plugin level: application

See Also:

Constant Field Values

LEVEL_FRAME

static final int LEVEL_FRAME

Plugin level: frame

See Also:

Constant Field Values

LEVEL_PAGE

static final int LEVEL_PAGE

Plugin level: page

See Also:

Constant Field Values

LEVEL_PLUGIN

static final int LEVEL_PLUGIN

Plugin level: regular plugin

See Also:

Constant Field Values

ID_DELIMETER

static final java.lang.String ID_DELIMETER

Delimeter for the unique id of a plugin

See Also:

Constant Field Values

Method Detail

getName

java.lang.String getName()

Returns the name of the plugin.

Returns:

By default, this is the fully qualified class name (see getClassName())

getClassName

java.lang.String getClassName()

Returns the class name of the plugin.

Returns:

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

getUniqueId

java.lang.String getUniqueId()

Returns the unique id of this plugin.

getPluginResourceCollection

ResourceCollection getPluginResourceCollection()

Gets the plugin resource.

getTitle

java.lang.String getTitle()

Gets the title.

getSubTitle

java.lang.String getSubTitle()

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

getDescription

java.lang.String getDescription()

Gets the description.

getIcon

MultiIcon getIcon()

Gets the icon.

getVendor

java.lang.String getVendor()

Gets the plugin vendor.

getVersion

java.lang.String getVersion()

Gets the plugin version.

getCondition

java.lang.String getCondition()

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

getEventActionNames

java.util.List getEventActionNames()

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

Returns:

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

getAction

JaspiraAction getAction(java.lang.String actionName)

This convenience method retrieves an action from the action manager.

Parameters:

actionName - Action name

Returns:

The action or null if no such action exists

initializePlugin

void initializePlugin()

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

installPlugin

void installPlugin()

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

installFirstPlugin

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.
Should only be called by the plugin manager.

uninstallPlugin

void uninstallPlugin()

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

uninstallLastPlugin

void uninstallLastPlugin()

This is called after uninstall for the last instance has been uninstalled. Should only be called by the plugin manager.

fireEvent

boolean fireEvent(JaspiraEvent je)

Fires the given event using the event queue.

Parameters:

je - Event to fire

Returns:

true If the event was consumed by a plugin
false Otherwise

fireEvent

boolean fireEvent(java.lang.String eventName)

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

Parameters:

eventName - Name of the event

Returns:

true If the event was consumed by a plugin
false Otherwise

fireEvent

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.

Parameters:

eventName - Name of the event

data - Event object

Returns:

true If the event was consumed by a plugin
false Otherwise

handleEvent

boolean handleEvent(JaspiraEvent je)

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

Parameters:

je - The event to handle

Returns:

true If the event was consumed by the plugin
false Otherwise

receiveEvent

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

Parameters:

je - The event to handle

Returns:

true If the event was consumed by the plugin
false Otherwise

inheritEvent

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.

Parameters:

je - The event to handle

Returns:

true If the event was consumed by the plugin
false Otherwise

stackEvent

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.

Parameters:

je - The event to stack

containsStackedEvent

boolean containsStackedEvent(java.lang.String eventName)

Checks if the event stack contains a particular event.

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.

getChildPlugins

java.util.List getChildPlugins()

Returns a list of all children of this plugin.

Returns:

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

getDescendantPlugins

java.util.List getDescendantPlugins(java.util.List plugins)

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

Parameters:

plugins - 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

Plugin getParentPlugin()

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

Returns:

Parent of this plugin or null in case of ApplicationBase

setParentPlugin

void setParentPlugin(Plugin newParent)

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

Parameters:

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

addPlugin

void addPlugin(Plugin child)

Adds a plugin as child plugin of this plugin.

Parameters:

child - Child plugin to add

removePlugin

void removePlugin(Plugin child)

Removes a child plugin from this plugin.

Parameters:

child - Child plugin to remove

getLevel

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.

Returns:

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

getPeerGroups

java.util.Set getPeerGroups()

Returns the peer groups this plugin has been added to.

Returns:

A set of objects denoting the peer groups

getPeerGroupNames

java.util.Set getPeerGroupNames()

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

Returns:

A set of strings (peer group names)

addToPeerGroup

void addToPeerGroup(java.lang.String name,
                    java.lang.Object group)

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

Parameters:

name - Peer group name

group - Peer group object

getPeerGroup

java.lang.Object getPeerGroup(java.lang.String name)

Gets the peer group for the given group name.

Parameters:

name - Name of the peer group

Returns:

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

removeFromPeerGroup

void removeFromPeerGroup(java.lang.String name)

Removes the plugin from a peer group.

Parameters:

name - Peer group name

matchesPeerGroup

boolean matchesPeerGroup(java.lang.String name,
                         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.

Parameters:

name - 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

boolean matchesPeerGroups(Plugin plugin,
                          boolean strict)

Matches all peer groups of one plugin against another.

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

getPluginState

PluginState getPluginState()

Returns the state of this plugin.

setPluginState

void setPluginState(PluginState state)

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

canClose

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 ().

Returns:

True if this plugin can be closed right now

requestClose

boolean requestClose()

Request the plugin to be closed. The plugin should check whether this is currently possible an if so do it.

Returns:

true If the plugin has been closed
false Otherwise