org.rhq.enterprise.agent
Interface AgentManagementMBean

All Known Implementing Classes:

AgentManagement

public interface AgentManagementMBean

The agent's management interface. This is the interface used by the agent plugin to manage and monitor the agent itself. This

Author:

John Mazzitelli

Field Summary

static ObjectName	BASE_OBJECT_NAME This is the object name that the agent will register as.
static String	JMX_DOMAIN The domain name where this MBean will be placed.
static String	KEY_NAME All agent management MBeans will have this as a key property whose property value will be the agent name.
static String	PLUGIN_INFO_MD5 Identifies the MD5 of a plugin.
static String	PLUGIN_INFO_NAME Identifies the name of a plugin.
static String	PLUGIN_INFO_PATH Identifies the full path to a plugin.
static String	PLUGIN_INFO_SIZE Identifies the filesize of a plugin.
static String	PLUGIN_INFO_TIMESTAMP Identifies the last modified date of a plugin.

Method Summary

void	downloadLatestFailoverList() Tells the agent to download an updated server failover list.
OperationResult	executeAvailabilityScan(Boolean changesOnly) Asks the agent's plugin container to execute an availability scan and returns the results.
String	executePromptCommand(String command) Executes an agent prompt command.
Properties	getAgentConfiguration() Returns the entire set of agent configuration preferences.
String	getAgentHomeDirectory() Returns the directory that is considered the "agent home" (i.e.
long	getAgentServerClockDifference() Returns the number of milliseconds this agent thinks its clock is ahead or behind from its server's clock.
long	getAverageExecutionTimeReceived()
long	getAverageExecutionTimeSent()
long	getCurrentTime() Returns the current time, as it is known to the agent.
int	getJVMActiveThreads() Returns the number of currently active threads in the agent's JVM.
long	getJVMFreeMemory() Returns the agent JVM's free memory as reported by Runtime.getRuntime().freeMemory().
long	getJVMTotalMemory() Returns the agent JVM's total memory as reported by Runtime.getRuntime().totalMemory().
int	getNumberAgentRestarts() Returns the number of times the agent has been restarted for the entire lifetime of the agent's JVM.
long	getNumberCommandsActiveSent()
long	getNumberCommandsInQueue()
long	getNumberCommandsSpooled()
long	getNumberFailedCommandsReceived()
long	getNumberFailedCommandsSent()
long	getNumberSuccessfulCommandsReceived()
long	getNumberSuccessfulCommandsSent()
long	getNumberTotalCommandsReceived()
long	getNumberTotalCommandsSent() Combines the number of successful and failed commands sent.
String	getReasonForLastRestart() Returns the code that indicates why the agent was last restarted.
long	getUptime() Returns the number of seconds the agent has been started - this resets everytime the agent is shutdown.
String	getVersion() Returns the agent's version string.
boolean	isSending()
void	mergeIntoAgentConfiguration(Properties config) The given set of agent configuration preferences (in the form of name/value pairs in a Properties object) is added to the current set of agent configuration preferences.
void	removeFromAgentConfiguration(List<String> preferenceNames) Given the names of preferences, this will remove those preference settings from the agent configuration.
void	restart() This will perform an agent hot-restart.
void	restartPluginContainer() This will shutdown then immediately restart the agent's internal plugin container.
OperationResult	retrieveAllPluginInfo() Returns information on all currently deployed plugins.
String	retrieveCurrentDateTime(String timeZone) Returns a string of the agent's current date/time, formatted with the given time zone.
OperationResult	retrievePluginInfo(String pluginName) Returns information on the given plugin.
void	setDebugMode(Boolean enabled, Boolean traceMessaging) Turns on or off debug mode, which makes the agent log more verbose with debug messages.
void	shutdown() This will shutdown the agent's communications layer and the plugin container.
void	switchToServer(String server)
void	updatePlugins() This will tell the agent to update its plugins.

Field Detail

JMX_DOMAIN

static final String JMX_DOMAIN

The domain name where this MBean will be placed. This is also the default domain name of the MBeanServer where this MBean is registered.

See Also:

Constant Field Values

KEY_NAME

static final String KEY_NAME

All agent management MBeans will have this as a key property whose property value will be the agent name.

See Also:

Constant Field Values

BASE_OBJECT_NAME

static final ObjectName BASE_OBJECT_NAME

This is the object name that the agent will register as. Its just a base name - an additional key property KEY_NAME will be added to make it unique in the case when you embedded agents in the same VM.

PLUGIN_INFO_NAME

static final String PLUGIN_INFO_NAME

Identifies the name of a plugin.

See Also:

Constant Field Values

PLUGIN_INFO_PATH

static final String PLUGIN_INFO_PATH

Identifies the full path to a plugin.

See Also:

Constant Field Values

PLUGIN_INFO_TIMESTAMP

static final String PLUGIN_INFO_TIMESTAMP

Identifies the last modified date of a plugin.

See Also:

Constant Field Values

PLUGIN_INFO_SIZE

static final String PLUGIN_INFO_SIZE

Identifies the filesize of a plugin.

See Also:

Constant Field Values

PLUGIN_INFO_MD5

static final String PLUGIN_INFO_MD5

Identifies the MD5 of a plugin.

See Also:

Constant Field Values

Method Detail

switchToServer

void switchToServer(String server)

restart

void restart()

This will perform an agent hot-restart. The agent will be shutdown() and then immediately started again. This is usually called after a client has changed some configuration settings.

The actual restart is performed asynchronously. The caller has just a few seconds after this method returns before it takes effect.

shutdown

void shutdown()

This will shutdown the agent's communications layer and the plugin container. If the agent is in daemon mode, the agent's VM will die. Once this method is called, this management interface will no longer be available via JMX and the agent will no longer be able to process incoming commands or send outgoing commands.

The actual shutdown is performed asynchronously. The caller has just a few seconds after this method returns before it takes effect.

downloadLatestFailoverList

void downloadLatestFailoverList()

Tells the agent to download an updated server failover list. This will also check to make sure the agent is pointing to its primary server as found in the new failover list and, if not, will attempt to switch to the primary server now.

updatePlugins

void updatePlugins()

This will tell the agent to update its plugins. If the JON Server is up and the agent has detected it, this will immediately pull down the updated plugins. If the JON Server is down, this will schedule the agent to pull down the plugins as soon as the JON Server comes back up.

After the plugins are updated, the plugin container will immediately be restarted.

The actual PC restart is performed asynchronously. The caller has just a few seconds after this method returns before it takes effect.

retrieveAllPluginInfo

OperationResult retrieveAllPluginInfo()

Returns information on all currently deployed plugins. The configuration will contain one PropertyMap for each plugin. The name of the map will be the plugin name. Each map will have the key/value pairs where the keys are PLUGIN_INFO_xxx.

Returns:

information on all deployed plugins

retrievePluginInfo

OperationResult retrievePluginInfo(String pluginName)

Returns information on the given plugin. The configuration will contain simple properties where the names are defined by PLUGIN_INFO_xxx.

Parameters:

pluginName - the plugin whose information is to be returned

Returns:

the plugin information

restartPluginContainer

void restartPluginContainer()

This will shutdown then immediately restart the agent's internal plugin container. The plugin container manages all plugins and their lifecycles. This is usually called after a client has updated the plugins. Restarting the plugin container forces it to load in newly updated plugins.

The actual restart is performed asynchronously. The caller has just a few seconds after this method returns before it takes effect.

See Also:

updatePlugins()

executeAvailabilityScan

OperationResult executeAvailabilityScan(Boolean changesOnly)

Asks the agent's plugin container to execute an availability scan and returns the results. See DiscoveryAgentService.executeAvailabilityScanImmediately(boolean) for the semantics of this call.

Parameters:

changesOnly - if true, only report those availabilities that have changed

Returns:

the report in an OperationResult object

getVersion

String getVersion()

Returns the agent's version string. This does not necessarily help identify the versions of the plugins, since each plugin may have been updated from the JON Server since the initial installation of the agent.

Returns:

identifies the version of the agent.

getCurrentTime

long getCurrentTime()

Returns the current time, as it is known to the agent. This can be used to determine if the agent's clock is skewed from some other clock (e.g. the JON Server). The returned value is the number of milliseconds since midnight, January 1, 1970 UTC (as per System.currentTimeMillis.

Returns:

current time, as it is known to the agent

retrieveCurrentDateTime

String retrieveCurrentDateTime(String timeZone)

Returns a string of the agent's current date/time, formatted with the given time zone. If the given time zone is null or empty string, the agent's local time zone will be used. If the given time zone is unknown, GMT will be the default. timeZonecan be either an abbreviation such as "PST", a full name such as "America/Los_Angeles", or a custom ID such as "GMT-8:00". Note that the support of abbreviations is for JDK 1.1.x compatibility only and full names should be used.

Parameters:

timeZone - the time zone to display the date/time in

Returns:

the agent's current date/time

See Also:

TimeZone.getTimeZone(String)

setDebugMode

void setDebugMode(Boolean enabled,
                  Boolean traceMessaging)
                  throws ExecutionException

Turns on or off debug mode, which makes the agent log more verbose with debug messages. This will also be able to optionally turn on and off messaging trace, which lets you debug the messaging between server and agent. If the enabled flag is false, traceMessaging is ignored (i.e. all debug will be disabled, including message tracing).

Parameters:

enabled - enable debug mode

traceMessaging - if true, message tracing will be enabled unless enabled is false

Throws:

ExecutionException - if failed to change the debug mode

executePromptCommand

String executePromptCommand(String command)
                            throws ExecutionException

Executes an agent prompt command. The given command is the prompt command plus any additional command arguments, separated by spaces (just as if you typed the command in the console window). The results will be a string that contains the text that you would have seen in the console output had the prompt command been executed from the console.

Parameters:

command - the command to execute along with any command line arguments.

Returns:

the output results of the executed prompt command

Throws:

ExecutionException - if the prompt command threw an exception, this method will throw an exception whose message is the output text that was written by the prompt command up until the error occurred. The cause of the thrown exception will be the actual exception thrown by the prompt command. This way you can see what the prompt command output was as well as the exception that occurred.

getAgentHomeDirectory

String getAgentHomeDirectory()

Returns the directory that is considered the "agent home" (i.e. the directory where the agent is installed).

Returns:

agent home directory

getNumberAgentRestarts

int getNumberAgentRestarts()

Returns the number of times the agent has been restarted for the entire lifetime of the agent's JVM. Reasons for a restart can include the execution of the agent plugin's "restart" operation or the VM Health Check detected a critical problem and restarted the agent automatically. To find out why the agent was last restarted, see getReasonForLastRestart().

Returns:

number of agent restarts that have occured

getReasonForLastRestart

String getReasonForLastRestart()

Returns the code that indicates why the agent was last restarted.

Returns:

restart code

getAgentServerClockDifference

long getAgentServerClockDifference()

Returns the number of milliseconds this agent thinks its clock is ahead or behind from its server's clock. A positive value means the agent clock is ahead.

Returns:

time the agent-server clock difference

getUptime

long getUptime()

Returns the number of seconds the agent has been started - this resets everytime the agent is shutdown. This time does not necessarily mean the total time the agent's VM has been running (since the agent may have been shutdown and restarted without the VM ever coming down).

Returns:

number of seconds since the agent has been started

getNumberSuccessfulCommandsReceived

long getNumberSuccessfulCommandsReceived()

See Also:

ServiceContainerMetricsMBean.getNumberSuccessfulCommandsReceived()

getNumberFailedCommandsReceived

long getNumberFailedCommandsReceived()

See Also:

ServiceContainerMetricsMBean.getNumberFailedCommandsReceived()

getNumberTotalCommandsReceived

long getNumberTotalCommandsReceived()

See Also:

ServiceContainerMetricsMBean.getNumberTotalCommandsReceived()

getAverageExecutionTimeReceived

long getAverageExecutionTimeReceived()

See Also:

ServiceContainerMetricsMBean#getAverageExecutionTime()

getAverageExecutionTimeSent

long getAverageExecutionTimeSent()

See Also:

ClientCommandSenderMetrics.getAverageExecutionTimeSent()

getNumberSuccessfulCommandsSent

long getNumberSuccessfulCommandsSent()

See Also:

ClientCommandSenderMetrics.getNumberSuccessfulCommandsSent()

getNumberFailedCommandsSent

long getNumberFailedCommandsSent()

See Also:

ClientCommandSenderMetrics.getNumberFailedCommandsSent()

getNumberTotalCommandsSent

long getNumberTotalCommandsSent()

Combines the number of successful and failed commands sent.

See Also:

ClientCommandSenderMetrics.getNumberSuccessfulCommandsSent(), ClientCommandSenderMetrics.getNumberFailedCommandsSent()

getNumberCommandsActiveSent

long getNumberCommandsActiveSent()

See Also:

ClientCommandSenderMetrics.getNumberCommandsActive()

getNumberCommandsInQueue

long getNumberCommandsInQueue()

See Also:

ClientCommandSenderMetrics.getNumberCommandsInQueue()

getNumberCommandsSpooled

long getNumberCommandsSpooled()

See Also:

ClientCommandSenderMetrics.getNumberCommandsSpooled()

isSending

boolean isSending()

See Also:

ClientCommandSenderMetrics.isSending()

getJVMFreeMemory

long getJVMFreeMemory()

Returns the agent JVM's free memory as reported by Runtime.getRuntime().freeMemory().

Returns:

free memory in bytes

getJVMTotalMemory

long getJVMTotalMemory()

Returns the agent JVM's total memory as reported by Runtime.getRuntime().totalMemory().

Returns:

total memory in bytes

getJVMActiveThreads

int getJVMActiveThreads()

Returns the number of currently active threads in the agent's JVM.

Returns:

number of all active threads

getAgentConfiguration

Properties getAgentConfiguration()

Returns the entire set of agent configuration preferences.

Returns:

agent configuration preferences

mergeIntoAgentConfiguration

void mergeIntoAgentConfiguration(Properties config)

The given set of agent configuration preferences (in the form of name/value pairs in a Properties object) is added to the current set of agent configuration preferences. Those preferences found in config that already exist in the current agent configuration will override the old values in the current agent configuration. Those preferences found in config but do not exist yet in the current agent configuration are added to the agent configuration. If a preference exists in the current configuration but is not found in config, then that preference is left as-is.

Changing the agent configuration usually requires the agent to be restarted in order for the new settings to be picked up.

Parameters:

config - new agent configuration preferences

removeFromAgentConfiguration

void removeFromAgentConfiguration(List<String> preferenceNames)

Given the names of preferences, this will remove those preference settings from the agent configuration. This will effectively force that preferences to fallback to their built-in defaults.

Parameters:

preferenceNames - the preferences to remove from the agent configuration