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

List<org.rhq.core.domain.plugin.PluginKey>	disableServerPlugins(org.rhq.core.domain.auth.Subject subject, List<Integer> pluginIds) Disables the plugins and unschedules their jobs.
List<org.rhq.core.domain.plugin.PluginKey>	enableServerPlugins(org.rhq.core.domain.auth.Subject subject, List<Integer> pluginIds) Enables the plugins and restarts them.
List<org.rhq.core.domain.plugin.ServerPlugin>	getAllServerPlugins() Returns a list of all the installed and deleted server plugins in the database.
List<org.rhq.core.domain.plugin.ServerPlugin>	getAllServerPluginsById(List<Integer> pluginIds) Get a list of both installed and deleted plugins from their IDs.
Map<ServerPluginType,List<org.rhq.core.domain.plugin.PluginKey>>	getInstalledServerPluginsGroupedByType() This will return a map containing all installed plugins that are both enabled and disabled.
long	getLastConfigurationChangeTimestamp(int pluginId) Given a plugin ID, this will return a timestamp (in epoch millis) that indicates the last time when the plugin's configuration changed.
org.rhq.core.domain.plugin.ServerPlugin	getServerPlugin(org.rhq.core.domain.plugin.PluginKey key) Returns a plugin with the given key.
org.rhq.core.domain.configuration.definition.ConfigurationDefinition	getServerPluginConfigurationDefinition(org.rhq.core.domain.plugin.PluginKey pluginKey) Returns the definition for the given plugin's global plugin configuration.
List<ControlDefinition>	getServerPluginControlDefinitions(org.rhq.core.domain.plugin.PluginKey pluginKey) Returns the metadata for all control operations for the given plugin.
ServerPluginDescriptorType	getServerPluginDescriptor(org.rhq.core.domain.plugin.PluginKey pluginKey) Given a plugin key, returns the descriptor for that plugin.
List<org.rhq.core.domain.plugin.PluginKey>	getServerPluginKeysByEnabled(boolean enabled) Returns a list of plugin keys for only those server plugins whose enabled flag is equal to the given parameter.
org.rhq.core.domain.plugin.ServerPlugin	getServerPluginRelationships(org.rhq.core.domain.plugin.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).
List<org.rhq.core.domain.plugin.ServerPlugin>	getServerPlugins() Returns a list of all the installed server plugins in the database
List<org.rhq.core.domain.plugin.ServerPlugin>	getServerPluginsById(List<Integer> pluginIds) Get a list of plugins from their IDs.
org.rhq.core.domain.configuration.definition.ConfigurationDefinition	getServerPluginScheduledJobsDefinition(org.rhq.core.domain.plugin.PluginKey pluginKey) Returns the definition for the given plugin's scheduled jobs configuration.
org.rhq.core.domain.plugin.PluginStatusType	getServerPluginStatus(org.rhq.core.domain.plugin.PluginKey pluginKey) Given the key of a server plugin, this will return the status of that plugin.
ControlResults	invokeServerPluginControl(org.rhq.core.domain.auth.Subject subject, org.rhq.core.domain.plugin.PluginKey pluginKey, String controlName, org.rhq.core.domain.configuration.Configuration params) Invokes a control operation on a given plugin and returns the results.
void	purgeServerPlugin(org.rhq.core.domain.auth.Subject subject, org.rhq.core.domain.plugin.PluginKey pluginKey) Purges the server plugin from the database.
List<org.rhq.core.domain.plugin.PluginKey>	purgeServerPlugins(org.rhq.core.domain.auth.Subject subject, List<Integer> pluginIds) Purges the undeployed plugins from the system so there is no record of them to have ever existed.
org.rhq.core.domain.plugin.ServerPlugin	registerServerPlugin(org.rhq.core.domain.auth.Subject subject, org.rhq.core.domain.plugin.ServerPlugin plugin, File pluginFile) Registers the given plugin to the database.
void	restartMasterPluginContainer(org.rhq.core.domain.auth.Subject subject) Recycles the master plugin container, essentially shutting down all server plugins and then restarting them.
void	setServerPluginEnabledFlag(org.rhq.core.domain.auth.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(org.rhq.core.domain.auth.Subject subject, List<Integer> pluginIds, org.rhq.core.domain.plugin.PluginStatusType status) Sets the status flag in the database but does NOT restart the server plugin container.
List<org.rhq.core.domain.plugin.PluginKey>	undeployServerPlugins(org.rhq.core.domain.auth.Subject subject, List<Integer> pluginIds) Removes the plugins from the system and unschedules their jobs.
org.rhq.core.domain.plugin.ServerPlugin	updateServerPluginExceptContent(org.rhq.core.domain.auth.Subject subject, org.rhq.core.domain.plugin.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(org.rhq.core.domain.auth.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

List<org.rhq.core.domain.plugin.ServerPlugin> getServerPlugins()

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

Returns:

all installed server plugins found in the DB

getAllServerPlugins

List<org.rhq.core.domain.plugin.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

org.rhq.core.domain.plugin.ServerPlugin getServerPlugin(org.rhq.core.domain.plugin.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

org.rhq.core.domain.plugin.ServerPlugin getServerPluginRelationships(org.rhq.core.domain.plugin.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

List<org.rhq.core.domain.plugin.ServerPlugin> getServerPluginsById(List<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

List<org.rhq.core.domain.plugin.ServerPlugin> getAllServerPluginsById(List<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

getLastConfigurationChangeTimestamp

long getLastConfigurationChangeTimestamp(int pluginId)

Given a plugin ID, this will return a timestamp (in epoch millis) that indicates the last time when the plugin's configuration changed. This looks at both plugin configuration and schedule job configuration.

Parameters:

pluginId -

Returns:

time when the plugin's configuration was last updated; will be 0 if the plugin has no configuration to change.

getServerPluginDescriptor

ServerPluginDescriptorType getServerPluginDescriptor(org.rhq.core.domain.plugin.PluginKey pluginKey)
                                                     throws Exception

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

Parameters:

pluginKey -

Returns:

descriptor parsed from the file in the plugin jar

Throws:

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

getServerPluginKeysByEnabled

List<org.rhq.core.domain.plugin.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

List<org.rhq.core.domain.plugin.PluginKey> enableServerPlugins(org.rhq.core.domain.auth.Subject subject,
                                                               List<Integer> pluginIds)
                                                               throws 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:

Exception - if failed to disable a plugin

disableServerPlugins

List<org.rhq.core.domain.plugin.PluginKey> disableServerPlugins(org.rhq.core.domain.auth.Subject subject,
                                                                List<Integer> pluginIds)
                                                                throws 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:

Exception - if failed to disable a plugin

undeployServerPlugins

List<org.rhq.core.domain.plugin.PluginKey> undeployServerPlugins(org.rhq.core.domain.auth.Subject subject,
                                                                 List<Integer> pluginIds)
                                                                 throws 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:

Exception - if failed to undeploy a plugin

purgeServerPlugins

List<org.rhq.core.domain.plugin.PluginKey> purgeServerPlugins(org.rhq.core.domain.auth.Subject subject,
                                                              List<Integer> pluginIds)
                                                              throws 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:

Exception - if failed to purge a plugin

setServerPluginEnabledFlag

void setServerPluginEnabledFlag(org.rhq.core.domain.auth.Subject subject,
                                int pluginId,
                                boolean enabled)
                                throws 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

Exception

setServerPluginStatus

void setServerPluginStatus(org.rhq.core.domain.auth.Subject subject,
                           List<Integer> pluginIds,
                           org.rhq.core.domain.plugin.PluginStatusType status)
                           throws 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

Exception

registerServerPlugin

org.rhq.core.domain.plugin.ServerPlugin registerServerPlugin(org.rhq.core.domain.auth.Subject subject,
                                                             org.rhq.core.domain.plugin.ServerPlugin plugin,
                                                             File pluginFile)
                                                             throws 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:

Exception - if failed to fully register the plugin

updateServerPluginExceptContent

org.rhq.core.domain.plugin.ServerPlugin updateServerPluginExceptContent(org.rhq.core.domain.auth.Subject subject,
                                                                        org.rhq.core.domain.plugin.ServerPlugin plugin)
                                                                        throws 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:

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

purgeServerPlugin

void purgeServerPlugin(org.rhq.core.domain.auth.Subject subject,
                       org.rhq.core.domain.plugin.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

org.rhq.core.domain.plugin.PluginStatusType getServerPluginStatus(org.rhq.core.domain.plugin.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

Map<ServerPluginType,List<org.rhq.core.domain.plugin.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

getServerPluginConfigurationDefinition

org.rhq.core.domain.configuration.definition.ConfigurationDefinition getServerPluginConfigurationDefinition(org.rhq.core.domain.plugin.PluginKey pluginKey)
                                                                                                            throws Exception

Returns the definition for the given plugin's global plugin configuration.

Parameters:

pluginKey -

Returns:

the plugin configuration definition

Throws:

Exception

getServerPluginScheduledJobsDefinition

org.rhq.core.domain.configuration.definition.ConfigurationDefinition getServerPluginScheduledJobsDefinition(org.rhq.core.domain.plugin.PluginKey pluginKey)
                                                                                                            throws Exception

Returns the definition for the given plugin's scheduled jobs configuration.

Parameters:

pluginKey -

Returns:

the scheduled jobs definition

Throws:

Exception

getServerPluginControlDefinitions

List<ControlDefinition> getServerPluginControlDefinitions(org.rhq.core.domain.plugin.PluginKey pluginKey)
                                                          throws Exception

Returns the metadata for all control operations for the given plugin. If there are no control operations, an empty list is returned.

Parameters:

pluginKey -

Returns:

list of control definitions that are defined for the given plugin

Throws:

Exception - if failed to determine a plugin's control definitions

invokeServerPluginControl

ControlResults invokeServerPluginControl(org.rhq.core.domain.auth.Subject subject,
                                         org.rhq.core.domain.plugin.PluginKey pluginKey,
                                         String controlName,
                                         org.rhq.core.domain.configuration.Configuration params)
                                         throws Exception

Invokes a control operation on a given plugin and returns the results. This method blocks until the plugin component completes the invocation.

Parameters:

subject - user making the request, must have the proper permissions

pluginKey - identifies the plugin whose control operation is to be invoked

controlName - identifies the name of the control operation to invoke

params - parameters to pass to the control operation; may be null

Returns:

the results of the invocation

Throws:

if - failed to obtain the plugin component and invoke the control. This usually means an abnormal error occurred - if the control operation merely failed to do what it needed to do, the error will be reported in the returned results, not as a thrown exception.

Exception