Class Install

java.lang.Object
org.jboss.byteman.agent.install.Install

public class Install extends 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 Details

    • agentJar

      private String agentJar
    • modulePluginJar

      private String modulePluginJar
    • id

      private String id
    • port

      private int port
    • host

      private String host
    • addToBoot

      private boolean addToBoot
    • setPolicy

      private boolean setPolicy
    • useModuleLoader

      private boolean useModuleLoader
    • props

      private String props
    • vm

      private VirtualMachine vm
    • BYTEMAN_PREFIX

      private static final String BYTEMAN_PREFIX
      See Also:
    • BYTEMAN_AGENT_LOADED_PROPERTY

      private static final String BYTEMAN_AGENT_LOADED_PROPERTY
      See Also:
    • BYTEMAN_HOME_SYSTEM_PROP

      private static final String BYTEMAN_HOME_SYSTEM_PROP
      System property used to idenitfy the location of the installed byteman release.
      See Also:
    • BYTEMAN_HOME_ENV_VAR

      private static final String BYTEMAN_HOME_ENV_VAR
      environment variable used to idenitfy the location of the installed byteman release.
      See Also:
    • BYTEMAN_AGENT_BASE_DIR

      private static final String BYTEMAN_AGENT_BASE_DIR
      Base directory to look for agent jar.
      See Also:
    • BYTEMAN_AGENT_NAME

      private static final String BYTEMAN_AGENT_NAME
      Name of agent jar (without extension).
      See Also:
    • BYTEMAN_MODULES_PLUGIN_BASE_DIR

      private static final String BYTEMAN_MODULES_PLUGIN_BASE_DIR
      Base directory to look for JBoss modules plugin jar.
      See Also:
    • BYTEMAN_MODULES_PLUGIN_NAME

      private static final String BYTEMAN_MODULES_PLUGIN_NAME
      Name of JBoss modules plugin jar (without extension).
      See Also:
  • Constructor Details

    • Install

      private Install()
      only this class creates instances
    • Install

      private Install(String pid, boolean addToBoot, String host, int port, String[] properties)
      compatibility mode
    • Install

      private Install(String pid, boolean addToBoot, boolean setPolicy, boolean useModuleLoader, String host, int port, String[] properties)
      only this class creates instances
  • Method Details

    • main

      public static void main(String[] args)
      main routine for use from command line Install [-h host] [-p port] [-b] [-s] [-m] [-Dorg.jboss.Byteman.xxx]* pid see method usage(int) for details of the command syntax
      Parameters:
      args - the command options
    • install

      public static void install(String pid, boolean addToBoot, String host, int port, String[] properties) throws IllegalArgumentException, FileNotFoundException, IOException, AttachNotSupportedException, AgentLoadException, AgentInitializationException
      compatability mode
      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:
      IllegalArgumentException - if any of the arguments is invalid
      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
      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
    • install

      public static void install(String pid, boolean addToBoot, boolean setPolicy, String host, int port, String[] properties) throws IllegalArgumentException, FileNotFoundException, IOException, AttachNotSupportedException, AgentLoadException, AgentInitializationException
      compatability mode
      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
      setPolicy - true if the agent jar should set an access-all-areas securityPolicy
      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:
      IllegalArgumentException - if any of the arguments is invalid
      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
      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
    • install

      public static void install(String pid, boolean addToBoot, boolean setPolicy, boolean useModuleLoader, String host, int port, String[] properties) throws IllegalArgumentException, FileNotFoundException, IOException, AttachNotSupportedException, AgentLoadException, AgentInitializationException
      compatability mode
      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
      setPolicy - true if the agent jar should set an access-all-areas securityPolicy
      useModuleLoader - true if the JBoss module loader mode should be configured
      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:
      IllegalArgumentException - if any of the arguments is invalid
      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
      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 String getSystemProperty(String id, 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
    • isAgentAttached

      public static boolean isAgentAttached(String id)
      attach to the virtual machine identified by id and return true if a Byteman agent has already been attached to it. id must be the id of a virtual machine returned by method availableVMs.
      Parameters:
      id - the id of the machine to attach to
      Returns:
      true if and only if a Byteman agent has already been attached to the virtual machine.
    • getProperty

      private static String getProperty(String id, String property)
    • parseArgs

      private void parseArgs(String[] args)
      check the supplied arguments and stash away the relevant data
      Parameters:
      args - the value supplied to main
    • locateAgent

      private void locateAgent() throws IOException
      Check for system property org.jboss.byteman.home in preference to the environment setting BYTEMAN_HOME and use it to identify the location of the byteman agent jar.
      Throws:
      IOException
    • locateJarFromHomeDir

      public String locateJarFromHomeDir(String bmHome, String baseDir, String libName) throws IOException
      Throws:
      IOException
    • locateJarFromClasspath

      public String locateJarFromClasspath(String libName) throws IOException
      Throws:
      IOException
    • attach

      attach to the Java process identified by the process id supplied on the command line
      Throws:
      AttachNotSupportedException
      IOException
      IllegalArgumentException
    • injectAgent

      private void injectAgent() throws AgentLoadException, AgentInitializationException, 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
      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