org.jboss.byteman.agent.install

Class Install

java.lang.Object

org.jboss.byteman.agent.install.Install

public class Install
extends java.lang.Object

A program which uses the sun.com.tools.attach.VirtualMachine class to install the Byteman agent into a running JVM. This provides an alternative to using the -javaagent option to install the agent.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	addToBoot
private java.lang.String	agentJar
private static java.lang.String	BYTEMAN_HOME_ENV_VAR environment variable used to idenitfy the location of the installed byteman release.
private static java.lang.String	BYTEMAN_HOME_SYSTEM_PROP System property used to idenitfy the location of the installed byteman release.
private static java.lang.String	BYTEMAN_PREFIX
private java.lang.String	host
private java.lang.String	id
private int	port
private java.lang.String	props
private VirtualMachine	vm

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Install() only this class creates instances
private	Install(java.lang.String pid, boolean addToBoot, java.lang.String host, int port, java.lang.String[] properties) only this class creates instances

Method Summary

Methods

Modifier and Type	Method and Description
private void	attach() attach to the Java process identified by the process id supplied on the command line
static VMInfo[]	availableVMs()
static java.lang.String	getSystemProperty(java.lang.String id, java.lang.String property) attach to the virtual machine identified by id and return the value of the named property.
private void	injectAgent() get the attached process to upload and install the agent jar using whatever agent options were configured on the command line
static void	install(java.lang.String pid, boolean addToBoot, java.lang.String host, int port, java.lang.String[] properties)
private void	locateAgent() check for environment setting BYTEMAN_HOME and use it to identify the location of the byteman agent jar.
void	locateAgentFromClasspath()
void	locateAgentFromHomeDir(java.lang.String bmHome)
static void	main(java.lang.String[] args) main routine for use from command line Install [-h host] [-p port] [-b] pid see method usage(int) for details of the command syntax
private void	parseArgs(java.lang.String[] args) check the supplied arguments and stash away te relevant data
private static void	usage(int exitValue) print usage information and exit with a specific exit code

Methods inherited from class java.lang.Object

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

Field Detail

agentJar

private java.lang.String agentJar

id

private java.lang.String id

port

private int port

host

private java.lang.String host

addToBoot

private boolean addToBoot

props

private java.lang.String props

vm

private VirtualMachine vm

BYTEMAN_PREFIX

private static final java.lang.String BYTEMAN_PREFIX

See Also:

Constant Field Values

BYTEMAN_HOME_SYSTEM_PROP

private static final java.lang.String BYTEMAN_HOME_SYSTEM_PROP

System property used to idenitfy the location of the installed byteman release.

See Also:

Constant Field Values

BYTEMAN_HOME_ENV_VAR

private static final java.lang.String BYTEMAN_HOME_ENV_VAR

environment variable used to idenitfy the location of the installed byteman release.

See Also:

Constant Field Values

Constructor Detail

Install

private Install()

only this class creates instances

Install

private Install(java.lang.String pid,
       boolean addToBoot,
       java.lang.String host,
       int port,
       java.lang.String[] properties)

only this class creates instances

Method Detail

main

public static void main(java.lang.String[] args)

main routine for use from command line

Install [-h host] [-p port] [-b] pid

see method usage(int) for details of the command syntax

Parameters:

args - the command options

install

public static void install(java.lang.String pid,
           boolean addToBoot,
           java.lang.String host,
           int port,
           java.lang.String[] properties)
                    throws java.lang.IllegalArgumentException,
                           java.io.FileNotFoundException,
                           java.io.IOException,
                           AttachNotSupportedException,
                           AgentLoadException,
                           AgentInitializationException

Parameters:

pid - the process id of the JVM into which the agent should be installed or 0 for this JVM

addToBoot - true if the agent jar should be installed into the bootstrap classpath

host - the hostname to be used by the agent listener or null for localhost

port - the port to be used by the agent listener or 0 for the default port

properties - an array of System properties to be installed by the agent with optional values e.g. values such as "org.jboss.byteman.verbose" or "org.jboss.byteman.dump.generated.classes.directory=./dump"

Throws:

java.lang.IllegalArgumentException - if any of the arguments is invalid

java.io.FileNotFoundException - if the agent jar cannot be found using the environment variable BYTEMAN_HOME or the System property org.jboss.byteman.home and cannot be located in the current classpath

java.io.IOException - if the byteman jar cannot be opened or uploaded to the requested JVM

AttachNotSupportedException - if the requested JVM cannot be attached to

AgentLoadException - if an error occurs during upload of the agent into the JVM

AgentInitializationException - if the agent fails to initialize after loading. this almost always indicates that the agent is already loaded into the JVM

availableVMs

public static VMInfo[] availableVMs()

getSystemProperty

public static java.lang.String getSystemProperty(java.lang.String id,
                                 java.lang.String property)

attach to the virtual machine identified by id and return the value of the named property. id must be the id of a virtual machine returned by method availableVMs.

Parameters:

id - the id of the machine to attach to

property - the proeprty to be retrieved

Returns:

the value of the property or null if it is not set

parseArgs

private void parseArgs(java.lang.String[] args)

check the supplied arguments and stash away te relevant data

Parameters:

args - the value supplied to main

locateAgent

private void locateAgent()
                  throws java.io.IOException

check for environment setting BYTEMAN_HOME and use it to identify the location of the byteman agent jar.

Throws:

java.io.IOException

locateAgentFromHomeDir

public void locateAgentFromHomeDir(java.lang.String bmHome)
                            throws java.io.IOException

Throws:

java.io.IOException

locateAgentFromClasspath

public void locateAgentFromClasspath()
                              throws java.io.IOException

Throws:

java.io.IOException

attach

private void attach()
             throws AttachNotSupportedException,
                    java.io.IOException,
                    java.lang.IllegalArgumentException

attach to the Java process identified by the process id supplied on the command line

Throws:

AttachNotSupportedException

java.io.IOException

java.lang.IllegalArgumentException

injectAgent

private void injectAgent()
                  throws AgentLoadException,
                         AgentInitializationException,
                         java.io.IOException

get the attached process to upload and install the agent jar using whatever agent options were configured on the command line

Throws:

AgentLoadException

AgentInitializationException

java.io.IOException

usage

private static void usage(int exitValue)

print usage information and exit with a specific exit code

Parameters:

exitValue - the value to be supplied to the exit call