org.jboss.byteman.agent.install
Class Install

java.lang.Object
  extended by 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
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
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
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