Package org.jboss.byteman.agent.install

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

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Install()
      only this class creates instances
      private Install​(java.lang.String pid, boolean addToBoot, boolean setPolicy, boolean useModuleLoader, java.lang.String host, int port, java.lang.String[] properties)
      only this class creates instances
      private Install​(java.lang.String pid, boolean addToBoot, java.lang.String host, int port, java.lang.String[] properties)
      compatibility mode

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void attach()
      attach to the Java process identified by the process id supplied on the command line
      static VMInfo[] availableVMs()  
      private static java.lang.String getProperty​(java.lang.String id, java.lang.String property)  
      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, boolean setPolicy, boolean useModuleLoader, java.lang.String host, int port, java.lang.String[] properties)
      compatability mode
      static void install​(java.lang.String pid, boolean addToBoot, boolean setPolicy, java.lang.String host, int port, java.lang.String[] properties)
      compatability mode
      static void install​(java.lang.String pid, boolean addToBoot, java.lang.String host, int port, java.lang.String[] properties)
      compatability mode
      static boolean isAgentAttached​(java.lang.String id)
      attach to the virtual machine identified by id and return true if a Byteman agent has already been attached to it.
      private void locateAgent()
      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.
      java.lang.String locateJarFromClasspath​(java.lang.String libName)  
      java.lang.String locateJarFromHomeDir​(java.lang.String bmHome, java.lang.String baseDir, java.lang.String libName)  
      static void main​(java.lang.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
      private void parseArgs​(java.lang.String[] args)
      check the supplied arguments and stash away the 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

      • modulePluginJar

        private java.lang.String modulePluginJar

      • id

        private java.lang.String id

      • port

        private int port

      • host

        private java.lang.String host

      • addToBoot

        private boolean addToBoot

      • setPolicy

        private boolean setPolicy

      • useModuleLoader

        private boolean useModuleLoader

      • props

        private java.lang.String props

      • vm

        private com.sun.tools.attach.VirtualMachine vm

      • BYTEMAN_AGENT_LOADED_PROPERTY

        private static final java.lang.String BYTEMAN_AGENT_LOADED_PROPERTY
        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

      • BYTEMAN_AGENT_BASE_DIR

        private static final java.lang.String BYTEMAN_AGENT_BASE_DIR
        Base directory to look for agent jar.
        See Also:
        Constant Field Values

      • BYTEMAN_AGENT_NAME

        private static final java.lang.String BYTEMAN_AGENT_NAME
        Name of agent jar (without extension).
        See Also:
        Constant Field Values

      • BYTEMAN_MODULES_PLUGIN_BASE_DIR

        private static final java.lang.String BYTEMAN_MODULES_PLUGIN_BASE_DIR
        Base directory to look for JBoss modules plugin jar.
        See Also:
        Constant Field Values

      • BYTEMAN_MODULES_PLUGIN_NAME

        private static final java.lang.String BYTEMAN_MODULES_PLUGIN_NAME
        Name of JBoss modules plugin jar (without extension).
        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)
        compatibility mode

      • Install

        private Install​(java.lang.String pid,
                boolean addToBoot,
                boolean setPolicy,
                boolean useModuleLoader,
                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] [-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​(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,
                           com.sun.tools.attach.AttachNotSupportedException,
                           com.sun.tools.attach.AgentLoadException,
                           com.sun.tools.attach.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:
        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
        com.sun.tools.attach.AttachNotSupportedException - if the requested JVM cannot be attached to
        com.sun.tools.attach.AgentLoadException - if an error occurs during upload of the agent into the JVM
        com.sun.tools.attach.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​(java.lang.String pid,
                           boolean addToBoot,
                           boolean setPolicy,
                           java.lang.String host,
                           int port,
                           java.lang.String[] properties)
                    throws java.lang.IllegalArgumentException,
                           java.io.FileNotFoundException,
                           java.io.IOException,
                           com.sun.tools.attach.AttachNotSupportedException,
                           com.sun.tools.attach.AgentLoadException,
                           com.sun.tools.attach.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:
        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
        com.sun.tools.attach.AttachNotSupportedException - if the requested JVM cannot be attached to
        com.sun.tools.attach.AgentLoadException - if an error occurs during upload of the agent into the JVM
        com.sun.tools.attach.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​(java.lang.String pid,
                           boolean addToBoot,
                           boolean setPolicy,
                           boolean useModuleLoader,
                           java.lang.String host,
                           int port,
                           java.lang.String[] properties)
                    throws java.lang.IllegalArgumentException,
                           java.io.FileNotFoundException,
                           java.io.IOException,
                           com.sun.tools.attach.AttachNotSupportedException,
                           com.sun.tools.attach.AgentLoadException,
                           com.sun.tools.attach.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:
        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
        com.sun.tools.attach.AttachNotSupportedException - if the requested JVM cannot be attached to
        com.sun.tools.attach.AgentLoadException - if an error occurs during upload of the agent into the JVM
        com.sun.tools.attach.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

      • isAgentAttached

        public static boolean isAgentAttached​(java.lang.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 java.lang.String getProperty​(java.lang.String id,
                                            java.lang.String property)

      • parseArgs

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

      • locateAgent

        private void locateAgent()
                  throws java.io.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:
        java.io.IOException

      • locateJarFromHomeDir

        public java.lang.String locateJarFromHomeDir​(java.lang.String bmHome,
                                             java.lang.String baseDir,
                                             java.lang.String libName)
                                      throws java.io.IOException
        Throws:
        java.io.IOException

      • locateJarFromClasspath

        public java.lang.String locateJarFromClasspath​(java.lang.String libName)
                                        throws java.io.IOException
        Throws:
        java.io.IOException

      • attach

        private void attach()
             throws com.sun.tools.attach.AttachNotSupportedException,
                    java.io.IOException,
                    java.lang.IllegalArgumentException
        attach to the Java process identified by the process id supplied on the command line
        Throws:
        com.sun.tools.attach.AttachNotSupportedException
        java.io.IOException
        java.lang.IllegalArgumentException

      • injectAgent

        private void injectAgent()
                  throws com.sun.tools.attach.AgentLoadException,
                         com.sun.tools.attach.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:
        com.sun.tools.attach.AgentLoadException
        com.sun.tools.attach.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