org.rhq.enterprise.server.plugin

Interface ServerPluginManagerLocal

All Superinterfaces:

ServerPluginManagerRemote

All Known Implementing Classes:

ServerPluginManagerBean

public interface ServerPluginManagerLocal
extends ServerPluginManagerRemote

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

Methods

Modifier and Type	Method and Description
void	acknowledgeDeletedPluginsBy(int serverId) The provided server acknowledges the deletion of all plugins marked as deleted by calling this method.
List<org.rhq.core.domain.plugin.ServerPlugin>	getAllServerPlugins() Deprecated. do not use this as the deleted plugins are essentially ephemeral and will be removed from the database in due time automatically.
List<org.rhq.core.domain.plugin.ServerPlugin>	getAllServerPluginsById(List<Integer> pluginIds) Get a list of both installed and deleted plugins from their IDs.
List<org.rhq.core.domain.plugin.ServerPlugin>	getDeletedPlugins() Returns the plugins that have been marked as deleted.
List<org.rhq.core.domain.plugin.ServerPlugin>	getEnabledServerPluginsByType(String type) Return all the server plugins that match a certain type string.
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.
boolean	isReadyForPurge(int pluginId) A helper method for PurgePluginsJob.
void	purgeServerPlugin(int pluginId) Purges the server plugin from the database.
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	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.
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.

Methods inherited from interface org.rhq.enterprise.server.plugin.ServerPluginManagerRemote

deleteServerPlugins, disableServerPlugins, enableServerPlugins, getServerPlugins, invokeServerPluginControl, restartMasterPluginContainer

Method Detail

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

@Deprecated
List<org.rhq.core.domain.plugin.ServerPlugin> getAllServerPlugins()

Deprecated. do not use this as the deleted plugins are essentially ephemeral and will be removed from the database in due time automatically.

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

getDeletedPlugins

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

Returns the plugins that have been marked as deleted. This is more or less a helper method to PurgePluginsJob which goes ahead and removes such plugins from database once it's safe to do so.

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

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(int pluginId)

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.

Do not invoke this method directly. It is meant as a support for PurgePluginsJob.

Parameters:

pluginId - the id 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

getEnabledServerPluginsByType

List<org.rhq.core.domain.plugin.ServerPlugin> getEnabledServerPluginsByType(String type)

Return all the server plugins that match a certain type string. This type is defined in the XML schema of the plugin descriptor. Example for alert sender plugins: "org.rhq.enterprise.server.xmlschema.generated.serverplugin.alert.AlertPluginDescriptorType" from rhq-serverplugin-alert.xsd.

Parameters:

type - Name of the type

Returns:

List of server plugins matching that type.

isReadyForPurge

boolean isReadyForPurge(int pluginId)

A helper method for PurgePluginsJob. Checks whether given server plugin is safe for purging from the database.

acknowledgeDeletedPluginsBy

void acknowledgeDeletedPluginsBy(int serverId)

The provided server acknowledges the deletion of all plugins marked as deleted by calling this method. Once all the servers in the HA cloud acknowledge the deletion of a plugin and the plugin is made purgable (after its resource types are deleted, etc) it will be automatically purged from the database.

This method is not meant for "public" consumption and is only called from ServerPluginScanner

Parameters:

serverId - the id of the server that wants to acknowledge that it has seen the deleted plugins