org.rhq.enterprise.server.plugin
Interface ServerPluginsLocal

All Known Implementing Classes:

ServerPluginsBean

public interface ServerPluginsLocal

Interface to the methods that interact with the serve-side plugin infrastructure. Most of these methods will only return information on PluginStatusType.INSTALLED plugins; only when explicitly stated will a method return data on PluginStatusType.DELETED plugins, too.

Author:

John Mazzitelli

Method Summary

java.util.List<PluginKey>	disableServerPlugins(Subject subject, java.util.List<java.lang.Integer> pluginIds) Disables the plugins and unschedules their jobs.
java.util.List<PluginKey>	enableServerPlugins(Subject subject, java.util.List<java.lang.Integer> pluginIds) Enables the plugins and restarts them.
java.util.List<ServerPlugin>	getAllServerPlugins() Returns a list of all the installed and deleted server plugins in the database.
java.util.List<ServerPlugin>	getAllServerPluginsById(java.util.List<java.lang.Integer> pluginIds) Get a list of both installed and deleted plugins from their IDs.
java.util.Map<ServerPluginType,java.util.List<PluginKey>>	getInstalledServerPluginsGroupedByType() This will return a map containing all installed plugins that are both enabled and disabled.
ServerPlugin	getServerPlugin(PluginKey key) Returns a plugin with the given key.
ServerPluginDescriptorType	getServerPluginDescriptor(PluginKey pluginKey) Given a plugin key, returns the descriptor for that plugin.
java.util.List<PluginKey>	getServerPluginKeysByEnabled(boolean enabled) Returns a list of plugin keys for only those server plugins whose enabled flag is equal to the given parameter.
ServerPlugin	getServerPluginRelationships(ServerPlugin plugin) Methods in this object that return plugins normally do not include the data from relationships with the plugin (for example, the plugin configuration and scheduled jobs related to the plugin).
java.util.List<ServerPlugin>	getServerPlugins() Returns a list of all the installed server plugins in the database
java.util.List<ServerPlugin>	getServerPluginsById(java.util.List<java.lang.Integer> pluginIds) Get a list of plugins from their IDs.
PluginStatusType	getServerPluginStatus(PluginKey pluginKey) Given the key of a server plugin, this will return the status of that plugin.
void	purgeServerPlugin(Subject subject, PluginKey pluginKey) Purges the server plugin from the database.
java.util.List<PluginKey>	purgeServerPlugins(Subject subject, java.util.List<java.lang.Integer> pluginIds) Purges the undeployed plugins from the system so there is no record of them to have ever existed.
ServerPlugin	registerServerPlugin(Subject subject, ServerPlugin plugin, java.io.File pluginFile) Registers the given plugin to the database.
void	restartMasterPluginContainer(Subject subject) Recycles the master plugin container, essentially shutting down all server plugins and then restarting them.
void	setServerPluginEnabledFlag(Subject subject, int pluginId, boolean enabled) Turns on or off the enabled flag in the database but does NOT restart the server plugin.
void	setServerPluginStatus(Subject subject, java.util.List<java.lang.Integer> pluginIds, PluginStatusType status) Sets the status flag in the database but does NOT restart the server plugin container.
java.util.List<PluginKey>	undeployServerPlugins(Subject subject, java.util.List<java.lang.Integer> pluginIds) Removes the plugins from the system and unschedules their jobs.
ServerPlugin	updateServerPluginExceptContent(Subject subject, ServerPlugin plugin) Given a plugin that already exists, this will update that plugin's data in the database, except for the content, which is left as-is.

Method Detail

restartMasterPluginContainer

void restartMasterPluginContainer(Subject subject)

Recycles the master plugin container, essentially shutting down all server plugins and then restarting them.

Parameters:

subject - the user asking to restart the master plugin container

getServerPlugins

java.util.List<ServerPlugin> getServerPlugins()

Returns a list of all the installed server plugins in the database

Returns:

all installed server plugins found in the DB

getAllServerPlugins

java.util.List<ServerPlugin> getAllServerPlugins()

Returns a list of all the installed and deleted server plugins in the database. When a plugin is "undeployed", it still exists in the database, but is flagged as "deleted". This method returns those deleted plugins in addition to those plugins that are still installed.

Returns:

all installed and deleted server plugins found in the DB

getServerPlugin

ServerPlugin getServerPlugin(PluginKey key)

Returns a plugin with the given key.

Parameters:

key - identifies the plugin to find

Returns:

the named plugin

Throws:

javax.persistence.NoResultException - when no plugin with that name exists

getServerPluginRelationships

ServerPlugin getServerPluginRelationships(ServerPlugin plugin)

Methods in this object that return plugins normally do not include the data from relationships with the plugin (for example, the plugin configuration and scheduled jobs related to the plugin). Call this method to fill in that data that wasn't originally loaded.

Parameters:

plugin -

Returns:

the same plugin, with the relationship data loaded

Throws:

javax.persistence.NoResultException - when no plugin with that name exists

getServerPluginsById

java.util.List<ServerPlugin> getServerPluginsById(java.util.List<java.lang.Integer> pluginIds)

Get a list of plugins from their IDs.

Parameters:

pluginIds - the IDs of the plugins to load.

Returns:

plugins matching the given IDs

getAllServerPluginsById

java.util.List<ServerPlugin> getAllServerPluginsById(java.util.List<java.lang.Integer> pluginIds)

Get a list of both installed and deleted plugins from their IDs.

Parameters:

pluginIds - the IDs of the plugins to load.

Returns:

plugins matching the given IDs

getServerPluginDescriptor

ServerPluginDescriptorType getServerPluginDescriptor(PluginKey pluginKey)
                                                     throws java.lang.Exception

Given a plugin key, returns the descriptor for that plugin.

Parameters:

pluginKey -

Returns:

descriptor parsed from the file in the plugin jar

Throws:

java.lang.Exception - if the descriptor could not be retrieved or parsed for the given plugin

getServerPluginKeysByEnabled

java.util.List<PluginKey> getServerPluginKeysByEnabled(boolean enabled)

Returns a list of plugin keys for only those server plugins whose enabled flag is equal to the given parameter.

Parameters:

enabled - if true, return only the keys of plugins that are enabled; if false, return only the keys of plugins that are disabled.

Returns:

list of plugin keys that match the enabled criteria

enableServerPlugins

java.util.List<PluginKey> enableServerPlugins(Subject subject,
                                              java.util.List<java.lang.Integer> pluginIds)
                                              throws java.lang.Exception

Enables the plugins and restarts them.

Parameters:

subject - user making the request

pluginIds - the plugins to be enabled

Returns:

the list of keys of the plugins that were enabled

Throws:

java.lang.Exception - if failed to disable a plugin

disableServerPlugins

java.util.List<PluginKey> disableServerPlugins(Subject subject,
                                               java.util.List<java.lang.Integer> pluginIds)
                                               throws java.lang.Exception

Disables the plugins and unschedules their jobs.

Parameters:

subject - user making the request

pluginIds - the plugins to be disabled

Returns:

the list of keys of the plugins that were disabled

Throws:

java.lang.Exception - if failed to disable a plugin

undeployServerPlugins

java.util.List<PluginKey> undeployServerPlugins(Subject subject,
                                                java.util.List<java.lang.Integer> pluginIds)
                                                throws java.lang.Exception

Removes the plugins from the system and unschedules their jobs.

Parameters:

subject - user making the request

pluginIds - the plugins to be undeployed

Returns:

the list of keys of plugins that were undeployed

Throws:

java.lang.Exception - if failed to undeploy a plugin

purgeServerPlugins

java.util.List<PluginKey> purgeServerPlugins(Subject subject,
                                             java.util.List<java.lang.Integer> pluginIds)
                                             throws java.lang.Exception

Purges the undeployed plugins from the system so there is no record of them to have ever existed. This deletes all remnants of the plugin from the database.

Parameters:

subject - user making the request

pluginIds - the plugins to be purged

Returns:

the list of keys of plugins that were purged

Throws:

java.lang.Exception - if failed to purge a plugin

setServerPluginEnabledFlag

void setServerPluginEnabledFlag(Subject subject,
                                int pluginId,
                                boolean enabled)
                                throws java.lang.Exception

Turns on or off the enabled flag in the database but does NOT restart the server plugin. This has "requires new" semantics, so the results are committed immediately upon return.

Parameters:

subject - user making the request

pluginId - the plugin to be enabled

enabled - the value of the enabled flag for the plugin

Throws:

if - failed to update the plugin

java.lang.Exception

setServerPluginStatus

void setServerPluginStatus(Subject subject,
                           java.util.List<java.lang.Integer> pluginIds,
                           PluginStatusType status)
                           throws java.lang.Exception

Sets the status flag in the database but does NOT restart the server plugin container. If the status is PluginStatusType.DELETED, the enabled flag is also flipped to false. This has "requires new" semantics, so the results are committed immediately upon return.

Parameters:

subject - user making the request

pluginIds - the plugins to be enabled

enabled - the value of the enabled flag for the plugins

Throws:

if - failed to update one of the plugins

java.lang.Exception

registerServerPlugin

ServerPlugin registerServerPlugin(Subject subject,
                                  ServerPlugin plugin,
                                  java.io.File pluginFile)
                                  throws java.lang.Exception

Registers the given plugin to the database. This ensures the database is up-to-date with the new plugin details. If the master plugin container is up, it will attempt to restart the plugin so the new changes are picked up.

Parameters:

subject - the user that needs to have permissions to add a plugin to the system

plugin - the plugin definition

pluginFile - the actual plugin file itself

Returns:

the plugin after being persisted

Throws:

java.lang.Exception - if failed to fully register the plugin

updateServerPluginExceptContent

ServerPlugin updateServerPluginExceptContent(Subject subject,
                                             ServerPlugin plugin)
                                             throws java.lang.Exception

Given a plugin that already exists, this will update that plugin's data in the database, except for the content, which is left as-is. If the plugin did not yet exist, an exception is thrown. You can use this to update the plugin's scheduled jobs configuration and plugin configuration.

Parameters:

subject - user making the request

plugin - existing plugin with updated data

Returns:

the updated plugin

Throws:

java.lang.Exception - if the plugin did not already exist or an error occurred that caused the update to fail

purgeServerPlugin

void purgeServerPlugin(Subject subject,
                       PluginKey pluginKey)

Purges the server plugin from the database. This ensures that, after this method returns, the given plugin will be unknown. The plugin can be installed again later. This has "requires new" semantics, so the results are committed immediately upon return. This is really a supporting method for #reRegisterServerPlugin(Subject, ServerPlugin, File) - you'll probably want to use that instead. Do not blindly purge server plugins using this method unless you know what you are doing.

Parameters:

subject - user making the request

pluginKey - the key of the server plugin to delete

getServerPluginStatus

PluginStatusType getServerPluginStatus(PluginKey pluginKey)

Given the key of a server plugin, this will return the status of that plugin. Use this to determine if a plugin has been deleted or not.

Parameters:

pluginKey - the key of the plugin whose status is to be returned.

Returns:

the status of the plugin, to indicate if the plugin has been deleted or is installed. null indicates an unknown plugin.

getInstalledServerPluginsGroupedByType

java.util.Map<ServerPluginType,java.util.List<PluginKey>> getInstalledServerPluginsGroupedByType()

This will return a map containing all installed plugins that are both enabled and disabled.

Returns:

keys of all enabled and disabled plugins, keyed on their types