org.rhq.enterprise.server.agent
Interface EmbeddedAgentBootstrapServiceMBean

All Known Implementing Classes:

EmbeddedAgentBootstrapService

public interface EmbeddedAgentBootstrapServiceMBean

The interface to the MBean that embeds a JON Agent in the JON Server.

Author:

John Mazzitelli

Field Summary

static javax.management.ObjectName

OBJECT_NAME The object name that the MBean service will be registered under.

Method Summary

void	cleanDataDirectory() This will clean out the embedded agent's data directory.
void	executeAgentPromptCommand(java.lang.String command) Passes the given prompt command to the agent so it can be executed.
java.lang.String[]	getAgentArguments() Returns the arguments that are passed to the agent's main startup method.
java.util.Properties	getAgentConfiguration() Returns the configuration preferencese the agent is or will be using.
java.lang.String	getAgentEnabled() If true, this indicates that the agent should be started when the JON Server is started.
java.lang.String	getConfigurationFile() Returns the location of the configuration file where all agent preferences are defined.
java.util.Properties	getConfigurationOverrides() Returns a set of properties that will override the configuration preferences.
java.io.File	getEmbeddedAgentDirectory() Indicates the location where the embedded agent and all its resources will be found.
java.lang.String	getPreferencesNodeName() Returns the preferences node name used to identify the configuration set to use.
java.lang.String	getResetConfiguration() Returns true if the embedded agent should reset its configuration at startup.
boolean	isAgentStarted() true indicates that the agent has been started.
void	reloadAgentConfiguration() This will clear any and all current configuration preferences and then reload the configuration file.
void	setAgentArguments(java.lang.String[] args) Sets the arguments that will be passed to the agent's main startup method.
void	setAgentEnabled(java.lang.String enabled) If true, this indicates that the agent should be started when the JON Server is started.
void	setConfigurationFile(java.lang.String location) Defines the location of the configuration file where all agent preferences are defined.
void	setConfigurationOverrides(java.util.Properties overrides) This allows you to explicitly override configuration preferences found in the configuration file.
void	setEmbeddedAgentDirectory(java.io.File directory) Indicates the location where the embedded agent and all its resources will be found.
void	setPreferencesNodeName(java.lang.String node) Defines the preferences node name used to identify the configuration set to use.
void	setResetConfiguration(java.lang.String reset) Sets the flag to determine if the agent should reset its configuration to its original configuration as defined in the configuration file, or if it should retain its configuration from when it last ran.
void	startAgent() Starts the agent.
void	stop() Stops this service - if the agent has been started, it will also be stopped.
void	stopAgent() Stops the agent.

Field Detail

OBJECT_NAME

static final javax.management.ObjectName OBJECT_NAME

The object name that the MBean service will be registered under.

Method Detail

getAgentEnabled

java.lang.String getAgentEnabled()

If true, this indicates that the agent should be started when the JON Server is started. This service is will not start the agent at its own startup, regardless of the value of this attribute. Instead, this attribute is examined by the JON Server itself - if the JON Server sees that the embedded agent should be started at startup, the JON Server will call startAgent().

Returns:

enabled flag, boolean string

setAgentEnabled

void setAgentEnabled(java.lang.String enabled)

If true, this indicates that the agent should be started when the JON Server is started. This service is will not start the agent at its own startup, regardless of the value of this attribute. Instead, this attribute is examined by the JON Server itself - if the JON Server sees that the embedded agent should be started at startup, the JON Server will call startAgent().

Parameters:

enabled - (a boolean string)

getResetConfiguration

java.lang.String getResetConfiguration()

Returns true if the embedded agent should reset its configuration at startup. Resetting the configuration means to clear out any configuration settings currently persisted in the preferences store and reload the configuration from its configuration file. If false, the embedded agent will retain the configuration it had when it last was running - which may be different from its original configuration if a user changed its configuration settings from the UI.

Returns:

reset configuration flag, as a String

setResetConfiguration

void setResetConfiguration(java.lang.String reset)

Sets the flag to determine if the agent should reset its configuration to its original configuration as defined in the configuration file, or if it should retain its configuration from when it last ran. See getResetConfiguration() for more information.

Parameters:

reset -

getEmbeddedAgentDirectory

java.io.File getEmbeddedAgentDirectory()

Indicates the location where the embedded agent and all its resources will be found. There must be a lib subdirectory under this directory which will include all jar files that are to be included in the embedded agent's classloader.

Returns:

location of the embedded agent and its resources

setEmbeddedAgentDirectory

void setEmbeddedAgentDirectory(java.io.File directory)

Indicates the location where the embedded agent and all its resources will be found. There must be a lib subdirectory under this directory which will include all jar files that are to be included in the embedded agent's classloader.

Parameters:

directory - location of the embedded agent and its resources

getConfigurationFile

java.lang.String getConfigurationFile()

Returns the location of the configuration file where all agent preferences are defined. The file location can be either a URL, a local file system path or a path within this service's classloader.

Returns:

configuration file location

setConfigurationFile

void setConfigurationFile(java.lang.String location)

Defines the location of the configuration file where all agent preferences are defined.

Parameters:

location -

getPreferencesNodeName

java.lang.String getPreferencesNodeName()

Returns the preferences node name used to identify the configuration set to use. See the Java Preferences API for the definition of a preference node name.

Returns:

the name of the Java Preferences node where the agent's configuration lives

setPreferencesNodeName

void setPreferencesNodeName(java.lang.String node)

Defines the preferences node name used to identify the configuration set to use. See the Java Preferences API for the definition of a preference node name.

If this isn't specified, a suitable default will be used.

Parameters:

node - the name of the Java Preferences node where the agent's configuration will or already lives

getConfigurationOverrides

java.util.Properties getConfigurationOverrides()

Returns a set of properties that will override the configuration preferences. If this returns null, then the configuration preferences takes effect as-is.

Returns:

configuration setting overrides (may be null)

setConfigurationOverrides

void setConfigurationOverrides(java.util.Properties overrides)

This allows you to explicitly override configuration preferences found in the configuration file. If this isn't set, then the settings specified by the configuration preferences file take effect as-is. These overrides can be set in the bootstrap deployment file (and thus allow you to be able to use any app-server specific settings, like ${jboss.server.data.dir}, in the configuration preference values).

Parameters:

overrides - configuration settings that override the configuration preferences (may benull)

getAgentArguments

java.lang.String[] getAgentArguments()

Returns the arguments that are passed to the agent's main startup method.

Returns:

agent arguments

setAgentArguments

void setAgentArguments(java.lang.String[] args)

Sets the arguments that will be passed to the agent's main startup method.

Parameters:

args -

reloadAgentConfiguration

void reloadAgentConfiguration()
                              throws java.lang.Exception

This will clear any and all current configuration preferences and then reload the configuration file. The agent will need to be restarted for the configuration to take effect.

Throws:

java.lang.Exception - if failed to clear and reload the configuration

cleanDataDirectory

void cleanDataDirectory()

This will clean out the embedded agent's data directory. You usually invoke if you want to start the agent in a clean state (i.e. use this in conjunction with reloadAgentConfiguration()).

getAgentConfiguration

java.util.Properties getAgentConfiguration()

Returns the configuration preferencese the agent is or will be using.

Returns:

the server configuration, as a set of properties

executeAgentPromptCommand

void executeAgentPromptCommand(java.lang.String command)

Passes the given prompt command to the agent so it can be executed. Note that if the command requires additional input, the embedded agent must have a valid input stream (System.in) or the command will fail. This means the JON Server must be running in a console that can have keyboard input in order to execute those prompt commands that ask for additional input from the user.

Parameters:

command - the agent prompt command to execute

isAgentStarted

boolean isAgentStarted()

true indicates that the agent has been started. false means the agent has not been started yet, or it was started but has since been stopped.

Returns:

state of the agent

startAgent

void startAgent()
                throws java.lang.Exception

Starts the agent. Note that this will not start the agent if the agent is not enabled.

Throws:

java.lang.Exception - if failed to start the agent successfully

stopAgent

void stopAgent()
               throws java.lang.Exception

Stops the agent. Note that this will do nothing if the agent is not enabled or was never started.

Throws:

java.lang.Exception - if failed to stop the agent successfully

stop

void stop()
          throws java.lang.Exception

Stops this service - if the agent has been started, it will also be stopped.

Throws:

java.lang.Exception - if failed to stop the agent