org.rhq.enterprise.server.agent
Class EmbeddedAgentBootstrapService

java.lang.Object
  org.rhq.enterprise.server.agent.EmbeddedAgentBootstrapService

All Implemented Interfaces:

EmbeddedAgentBootstrapServiceMBean

public class EmbeddedAgentBootstrapService
extends java.lang.Object
implements EmbeddedAgentBootstrapServiceMBean

This is an MBean service that can be used to bootstrap a RHQ Agent that is embedded in a RHQ Server. This will create a standalone classloader that will completely isolate the agent from any RHQ Server classloader (other than the top-level system classloader). Note that this service MBean interface does not expose any agent-specific classes to clients and it does not have direct access to any class outside of a select few classes found in the agent jar that is in this service's classpath.

Note that because this service is deployed with the agent jars in it, you must deploy it in exploded form.

Author:

John Mazzitelli

Field Summary

Fields inherited from interface org.rhq.enterprise.server.agent.EmbeddedAgentBootstrapServiceMBean

OBJECT_NAME

Constructor Summary

EmbeddedAgentBootstrapService()

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 flag) 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 flag) 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() This starts the agent in a completely isolated classloader in a completely isolated thread.
void	stop() Stops this service - if the agent has been started, it will also be stopped.
void	stopAgent() Stops the agent.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EmbeddedAgentBootstrapService

public EmbeddedAgentBootstrapService()

Method Detail

startAgent

public void startAgent()
                throws java.lang.Exception

This starts the agent in a completely isolated classloader in a completely isolated thread.

Specified by:

startAgent in interface EmbeddedAgentBootstrapServiceMBean

Throws:

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

See Also:

EmbeddedAgentBootstrapServiceMBean.startAgent()

stopAgent

public void stopAgent()
               throws java.lang.Exception

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

stopAgent in interface EmbeddedAgentBootstrapServiceMBean

Throws:

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

stop

public void stop()
          throws java.lang.Exception

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

stop in interface EmbeddedAgentBootstrapServiceMBean

Throws:

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

isAgentStarted

public boolean isAgentStarted()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

isAgentStarted in interface EmbeddedAgentBootstrapServiceMBean

Returns:

state of the agent

getAgentEnabled

public java.lang.String getAgentEnabled()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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 EmbeddedAgentBootstrapServiceMBean.startAgent().

Specified by:

getAgentEnabled in interface EmbeddedAgentBootstrapServiceMBean

Returns:

enabled flag, boolean string

setAgentEnabled

public void setAgentEnabled(java.lang.String flag)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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 EmbeddedAgentBootstrapServiceMBean.startAgent().

Specified by:

setAgentEnabled in interface EmbeddedAgentBootstrapServiceMBean

Parameters:

flag - (a boolean string)

getResetConfiguration

public java.lang.String getResetConfiguration()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

getResetConfiguration in interface EmbeddedAgentBootstrapServiceMBean

Returns:

reset configuration flag, as a String

setResetConfiguration

public void setResetConfiguration(java.lang.String flag)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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 EmbeddedAgentBootstrapServiceMBean.getResetConfiguration() for more information.

Specified by:

setResetConfiguration in interface EmbeddedAgentBootstrapServiceMBean

getEmbeddedAgentDirectory

public java.io.File getEmbeddedAgentDirectory()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

getEmbeddedAgentDirectory in interface EmbeddedAgentBootstrapServiceMBean

Returns:

location of the embedded agent and its resources

setEmbeddedAgentDirectory

public void setEmbeddedAgentDirectory(java.io.File directory)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

setEmbeddedAgentDirectory in interface EmbeddedAgentBootstrapServiceMBean

Parameters:

directory - location of the embedded agent and its resources

getConfigurationFile

public java.lang.String getConfigurationFile()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

getConfigurationFile in interface EmbeddedAgentBootstrapServiceMBean

Returns:

configuration file location

setConfigurationFile

public void setConfigurationFile(java.lang.String location)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

setConfigurationFile in interface EmbeddedAgentBootstrapServiceMBean

getPreferencesNodeName

public java.lang.String getPreferencesNodeName()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

getPreferencesNodeName in interface EmbeddedAgentBootstrapServiceMBean

Returns:

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

setPreferencesNodeName

public void setPreferencesNodeName(java.lang.String node)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

setPreferencesNodeName in interface EmbeddedAgentBootstrapServiceMBean

Parameters:

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

getConfigurationOverrides

public java.util.Properties getConfigurationOverrides()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

getConfigurationOverrides in interface EmbeddedAgentBootstrapServiceMBean

Returns:

configuration setting overrides (may be null)

setConfigurationOverrides

public void setConfigurationOverrides(java.util.Properties overrides)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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).

Specified by:

setConfigurationOverrides in interface EmbeddedAgentBootstrapServiceMBean

Parameters:

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

getAgentArguments

public java.lang.String[] getAgentArguments()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

getAgentArguments in interface EmbeddedAgentBootstrapServiceMBean

Returns:

agent arguments

setAgentArguments

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

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

setAgentArguments in interface EmbeddedAgentBootstrapServiceMBean

reloadAgentConfiguration

public void reloadAgentConfiguration()
                              throws java.lang.Exception

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

reloadAgentConfiguration in interface EmbeddedAgentBootstrapServiceMBean

Throws:

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

cleanDataDirectory

public void cleanDataDirectory()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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 EmbeddedAgentBootstrapServiceMBean.reloadAgentConfiguration()).

Specified by:

cleanDataDirectory in interface EmbeddedAgentBootstrapServiceMBean

getAgentConfiguration

public java.util.Properties getAgentConfiguration()

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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

Specified by:

getAgentConfiguration in interface EmbeddedAgentBootstrapServiceMBean

Returns:

the server configuration, as a set of properties

executeAgentPromptCommand

public void executeAgentPromptCommand(java.lang.String command)

Description copied from interface: EmbeddedAgentBootstrapServiceMBean

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.

Specified by:

executeAgentPromptCommand in interface EmbeddedAgentBootstrapServiceMBean

Parameters:

command - the agent prompt command to execute