Class Instrumentor


  • public class Instrumentor
    extends Object
    The Instrumentor provides for installing tracing and other rules into a remote JVM.
    Author:
    Jonathan Halliday (jonathan.halliday@redhat.com) 2010-05
    • Method Detail

      • getRedirectedSubmissionsFile

        public File getRedirectedSubmissionsFile()
        Returns the file to which Rule submission is currently redirected
        Returns:
        a file, or null if no redirection is in effect.
      • setRedirectedSubmissionsFile

        public void setRedirectedSubmissionsFile​(File redirectedSubmissionsFile)
        Sets the file to which Rule submissions should be redirected.
        Parameters:
        redirectedSubmissionsFile - a file, or null to cancel any existing redirection.
      • getHelperClass

        public Class<?> getHelperClass()
        Returns a helper class which this Instrumentor instance defines as parameter of HELPER clause.
        Returns:
        the helper class
      • setHelperClass

        public void setHelperClass​(Class<?> helperClass)

        Redefine a helper class which is used as parameter of HELPER clause by this instance of Instrumentor

        When setting you will probably create your own byteman helper class which extends the default one BytemanTestHelper.
        You need to know what you are doing when setting this parameter different from default helper implementation as it provides core functionality for dtest library.

        Parameters:
        helperClass - the new helper class
      • installHelperJar

        public void installHelperJar​(String path)
                              throws Exception
        Add the specified jar to the remote app's system classpath.
        Parameters:
        path - the absolute path to the .jar file.
        Throws:
        Exception - in case of failure.
      • instrumentClass

        public InstrumentedClass instrumentClass​(Class clazz)
                                          throws Exception
        Add method tracing rules to the specified class.
        Parameters:
        clazz - the Class to instrument.
        Returns:
        a local proxy for the instrumentation.
        Throws:
        Exception - in case of failure.
      • instrumentClass

        public InstrumentedClass instrumentClass​(Class clazz,
                                                 Set<String> methodNames)
                                          throws Exception
        Add method tracing rules to the specified class. If a non-null set of method names is supplied, only those methods are instrumented.
        Parameters:
        clazz - the Class to instrument.
        methodNames - the selection of methods to instrument.
        Returns:
        a local proxy for the instrumentation.
        Throws:
        Exception - in case of failure.
      • instrumentClass

        public InstrumentedClass instrumentClass​(String className,
                                                 Set<String> methodNames)
                                          throws Exception
        Add method tracing rules to the specified class name.
        If a null set of method names is supplied, NullPointerException is thrown.
        Parameters:
        className - the class name to instrument.
        methodNames - the selection of methods to instrument.
        Returns:
        a local proxy for the instrumentation.
        Throws:
        NullPointerException - in case of methodNames parameter is null
        Exception - in case of failure.
      • injectOnCall

        public void injectOnCall​(Class clazz,
                                 String methodName,
                                 String action)
                          throws Exception
        Inject an action to take place upon the invocation of the specified class.method
        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        Throws:
        Exception - in case of failure.
      • injectOnCall

        public void injectOnCall​(String className,
                                 String methodName,
                                 String action)
                          throws Exception
        Inject an action to take place upon the invocation of the specified class.method
        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        Throws:
        Exception - in case of failure.
      • injectOnExit

        public void injectOnExit​(Class clazz,
                                 String methodName,
                                 String action)
                          throws Exception
        Inject an action to take place upon exit of the specified class.method
        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        Throws:
        Exception - in case of failure.
      • injectOnExit

        public void injectOnExit​(String className,
                                 String methodName,
                                 String action)
                          throws Exception
        Inject an action to take place upon exit of the specified class.method
        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        Throws:
        Exception - in case of failure.
      • injectOnMethod

        public void injectOnMethod​(Class clazz,
                                   String methodName,
                                   String condition,
                                   String action,
                                   String atInjection)
                            throws Exception
        Inject an action to take place at a given point within the specified class.method
        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        atInjection - the injection point e.g. "ENTRY".
        condition - the rule condition
        Throws:
        Exception - in case of failure.
      • injectOnMethod

        public void injectOnMethod​(String className,
                                   String methodName,
                                   String condition,
                                   String action,
                                   String atInjection)
                            throws Exception
        Inject an action to take place at a given point within the specified class.method
        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        atInjection - the injection point e.g. "ENTRY".
        condition - the rule condition
        Throws:
        Exception - in case of failure.
      • injectOnMethodWhere

        public void injectOnMethodWhere​(Class clazz,
                                        String methodName,
                                        String condition,
                                        String action,
                                        String where)
                                 throws Exception

        Inject an action to take place at a given point within the specified class.method

        Difference to injectOnMethod(Class, String, String, String, String) resides at injection definition. The prior one expects "AT" injection point. This one expects the whole location qualifier.

        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        where - the injection definition e.g. "AT ENTRY" or "AFTER SYNCHRONIZATION".
        condition - the rule condition
        Throws:
        Exception - in case of failure.
      • injectOnMethodWhere

        public void injectOnMethodWhere​(String className,
                                        String methodName,
                                        String condition,
                                        String action,
                                        String where)
                                 throws Exception

        Inject an action to take place at a given point within the specified class.method

        Difference to injectOnMethod(String, String, String, String, String) resides at injection definition. The prior one expects "AT" injection point. This one expects the whole location qualifier.

        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        action - The action that should take place upon invocation of the method.
        where - the injection definition e.g. "AT ENTRY" or "AFTER SYNCHRONIZATION".
        condition - the rule condition
        Throws:
        Exception - in case of failure.
      • injectFault

        public void injectFault​(Class clazz,
                                String methodName,
                                Class<? extends Throwable> fault,
                                Object[] faultArgs)
                         throws Exception
        Inject a fault (i.e. Exception) to be thrown upon the invocation of the specified Class.method()
        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        fault - The type of Exception to be throw. If a checked exception, must be declared thrown by the specified method.
        faultArgs - Optional constructor arguments for the Exception.
        Throws:
        Exception - in case of failure.
      • crashAtMethodExit

        public void crashAtMethodExit​(Class clazz,
                                      String methodName)
                               throws Exception
        Inject a Rule to kill the target JVM upon exit of the specified Class.method()
        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        Throws:
        Exception - in case of failure.
      • crashAtMethodExit

        public void crashAtMethodExit​(String className,
                                      String methodName)
                               throws Exception
        Inject a Rule to kill the target JVM upon exit of the specified Class.method()
        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        Throws:
        Exception - in case of failure.
      • crashAtMethodEntry

        public void crashAtMethodEntry​(Class clazz,
                                       String methodName)
                                throws Exception
        Inject a Rule to kill the target JVM upon entry to the specified Class.method()
        Parameters:
        clazz - The Class in which the injection point resides.
        methodName - The method which should be intercepted.
        Throws:
        Exception - in case of failure.
      • crashAtMethodEntry

        public void crashAtMethodEntry​(String className,
                                       String methodName)
                                throws Exception
        Inject a Rule to kill the target JVM upon entry to the specified Class.method()
        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        Throws:
        Exception - in case of failure.
      • crashAtMethod

        public void crashAtMethod​(String className,
                                  String methodName,
                                  String atInjection)
                           throws Exception
        Inject a Rule to kill the target JVM at a given point within the specified Class.method()
        Parameters:
        className - The name of the Class in which the injection point resides.
        methodName - The method which should be intercepted.
        atInjection - the injection point e.g. "ENTRY".
        Throws:
        Exception - in case of failure.
      • installScript

        public void installScript​(String scriptName,
                                  String scriptString)
                           throws Exception
        Pass the assembled script to the remote JVM, either via. the Submit or, if redirection is in effect, to a file which will then be read at restart of the remote JVM. Keep a local handle on the script, such that it can be removed on request.
        Parameters:
        scriptName - The name of the script. Should be unique.
        scriptString - The text of the script i.e. one or more Rules.
        Throws:
        Exception - in case of failure.
      • installRule

        public String installRule​(RuleConstructor builder)
                           throws Exception
        Installing rule based on definition available by building RuleConstructor.
        Parameters:
        builder - rule builder with a rule definition to be installed as script
        Returns:
        name of script that rule was installed under
        Throws:
        Exception - in case of failure
      • removeScript

        public void removeScript​(String scriptName)
                          throws Exception

        Removing particular script from the remote byteman agent.

        If you submitted a rule directly to remote JVM then the scriptName is the name under the script was installed.

        If you used setRedirectedSubmissionsFile(File) to define a file where the rule will be written then this method won't work and you will get an IllegalStateException.

        Parameters:
        scriptName - name of script that should be removed
        Throws:
        Exception - in case that script can't be removed
      • removeRule

        public void removeRule​(RuleConstructor builder)
                        throws Exception
        Removing particular script installed as a rule by RuleConstructor.
        Parameters:
        builder - a rule defining a script to be removed
        Throws:
        Exception - in case of failure
      • removeLocalState

        public void removeLocalState()
                              throws Exception
        Flush the local cache of scripts and proxies to remote instrumented classes. Useful to reset local state when a remote JVM is crashed and hence reset.
        Throws:
        Exception - in case of failure.
      • removeAllInstrumentation

        public void removeAllInstrumentation()
                                      throws Exception
        Flush any instrumentation for the given class in the remote system and clean up the local cache.
        Throws:
        Exception - in case of failure.