Package org.jboss.byteman.contrib.dtest

Class Instrumentor

  • public class Instrumentor
extends java.lang.Object
    The Instrumentor provides for installing tracing and other rules into a remote JVM.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void appendToFile​(java.io.File file, java.lang.String rule)
      Write the given text to the end of the file.
      void crashAtMethod​(java.lang.String className, java.lang.String methodName, java.lang.String atInjection)
      Inject a Rule to kill the target JVM at a given point within the specified Class.method()
      void crashAtMethodEntry​(java.lang.Class clazz, java.lang.String methodName)
      Inject a Rule to kill the target JVM upon entry to the specified Class.method()
      void crashAtMethodEntry​(java.lang.String className, java.lang.String methodName)
      Inject a Rule to kill the target JVM upon entry to the specified Class.method()
      void crashAtMethodExit​(java.lang.Class clazz, java.lang.String methodName)
      Inject a Rule to kill the target JVM upon exit of the specified Class.method()
      void crashAtMethodExit​(java.lang.String className, java.lang.String methodName)
      Inject a Rule to kill the target JVM upon exit of the specified Class.method()
      private ScriptText findInstalledScript​(java.lang.String scriptName)
      Looping through installed scripts and checking if scriptName is there.
      java.lang.Class<?> getHelperClass()
      Returns a helper class which this Instrumentor instance defines as parameter of HELPER clause.
      java.io.File getRedirectedSubmissionsFile()
      Returns the file to which Rule submission is currently redirected
      void injectFault​(java.lang.Class clazz, java.lang.String methodName, java.lang.Class<? extends java.lang.Throwable> fault, java.lang.Object[] faultArgs)
      Inject a fault (i.e.
      void injectOnCall​(java.lang.Class clazz, java.lang.String methodName, java.lang.String action)
      Inject an action to take place upon the invocation of the specified class.method
      void injectOnCall​(java.lang.String className, java.lang.String methodName, java.lang.String action)
      Inject an action to take place upon the invocation of the specified class.method
      void injectOnExit​(java.lang.Class clazz, java.lang.String methodName, java.lang.String action)
      Inject an action to take place upon exit of the specified class.method
      void injectOnExit​(java.lang.String className, java.lang.String methodName, java.lang.String action)
      Inject an action to take place upon exit of the specified class.method
      void injectOnMethod​(java.lang.Class clazz, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String atInjection)
      Inject an action to take place at a given point within the specified class.method
      void injectOnMethod​(java.lang.String className, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String atInjection)
      Inject an action to take place at a given point within the specified class.method
      void injectOnMethodWhere​(java.lang.Class clazz, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String where)
      Inject an action to take place at a given point within the specified class.method
      void injectOnMethodWhere​(java.lang.String className, java.lang.String methodName, java.lang.String condition, java.lang.String action, java.lang.String where)
      Inject an action to take place at a given point within the specified class.method
      void installHelperJar​(java.lang.String path)
      Add the specified jar to the remote app's system classpath.
      java.lang.String installRule​(RuleConstructor builder)
      Installing rule based on definition available by building RuleConstructor.
      void installScript​(java.lang.String scriptName, java.lang.String scriptString)
      Pass the assembled script to the remote JVM, either via.
      InstrumentedClass instrumentClass​(java.lang.Class clazz)
      Add method tracing rules to the specified class.
      InstrumentedClass instrumentClass​(java.lang.Class clazz, java.lang.String... methodNames)  
      InstrumentedClass instrumentClass​(java.lang.Class clazz, java.util.Set<java.lang.String> methodNames)
      Add method tracing rules to the specified class.
      InstrumentedClass instrumentClass​(java.lang.String className, java.lang.String... methodNames)
      See instrumentClass(String, Set)
      InstrumentedClass instrumentClass​(java.lang.String className, java.util.Set<java.lang.String> methodNames)
      Add method tracing rules to the specified class name.
      If a null set of method names is supplied, NullPointerException is thrown.
      private boolean isInterface​(java.lang.String className)
      Trying to load a class and if successful then check if class is interface.
      private InstrumentedClass publish​(java.lang.String className)
      Create a local communication endpoint for the the given class.
      void removeAllInstrumentation()
      Flush any instrumentation for the given class in the remote system and clean up the local cache.
      void removeLocalState()
      Flush the local cache of scripts and proxies to remote instrumented classes.
      void removeRule​(RuleConstructor builder)
      Removing particular script installed as a rule by RuleConstructor.
      void removeScript​(java.lang.String scriptName)
      Removing particular script from the remote byteman agent.
      void setHelperClass​(java.lang.Class<?> helperClass)
      Redefine a helper class which is used as parameter of HELPER clause by this instance of Instrumentor
      void setRedirectedSubmissionsFile​(java.io.File redirectedSubmissionsFile)
      Sets the file to which Rule submissions should be redirected.
      private void unpublish​(java.lang.String className)
      Remove the local communication endpoint for the given class.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • submit

        private final Submit submit

      • registry

        private final java.rmi.registry.Registry registry

      • rmiRegistryPort

        private final int rmiRegistryPort

      • instrumentedClasses

        private final java.util.Map<java.lang.String,​InstrumentedClass> instrumentedClasses

      • installedScripts

        private final java.util.List<ScriptText> installedScripts

      • redirectedSubmissionsFile

        private java.io.File redirectedSubmissionsFile

      • helperClass

        private java.lang.Class<?> helperClass

    • Constructor Detail

      • Instrumentor

        public Instrumentor​(Submit submit,
                    int rmiRegistryPort)
             throws java.rmi.RemoteException
        Throws:
        java.rmi.RemoteException

      • Instrumentor

        public Instrumentor()
             throws java.rmi.RemoteException
        Throws:
        java.rmi.RemoteException

      • Instrumentor

        public Instrumentor​(java.lang.String address,
                    int port)
             throws java.rmi.RemoteException
        Throws:
        java.rmi.RemoteException

      • Instrumentor

        public Instrumentor​(java.lang.String address,
                    int port,
                    int rmiPort)
             throws java.rmi.RemoteException
        Throws:
        java.rmi.RemoteException

    • Method Detail

      • getRedirectedSubmissionsFile

        public java.io.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​(java.io.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 java.lang.Class<?> getHelperClass()
        Returns a helper class which this Instrumentor instance defines as parameter of HELPER clause.
        Returns:
        the helper class

      • setHelperClass

        public void setHelperClass​(java.lang.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​(java.lang.String path)
                      throws java.lang.Exception
        Add the specified jar to the remote app's system classpath.
        Parameters:
        path - the absolute path to the .jar file.
        Throws:
        java.lang.Exception - in case of failure.

      • instrumentClass

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

      • instrumentClass

        public InstrumentedClass instrumentClass​(java.lang.Class clazz,
                                         java.lang.String... methodNames)
                                  throws java.lang.Exception
        Throws:
        java.lang.Exception

      • instrumentClass

        public InstrumentedClass instrumentClass​(java.lang.Class clazz,
                                         java.util.Set<java.lang.String> methodNames)
                                  throws java.lang.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:
        java.lang.Exception - in case of failure.

      • instrumentClass

        public InstrumentedClass instrumentClass​(java.lang.String className,
                                         java.lang.String... methodNames)
                                  throws java.lang.Exception
        See instrumentClass(String, Set)
        Parameters:
        className - the class name to instrument.
        methodNames - the selection of methods to instrument.
        Throws:
        java.lang.Exception - in case of failure.

      • instrumentClass

        public InstrumentedClass instrumentClass​(java.lang.String className,
                                         java.util.Set<java.lang.String> methodNames)
                                  throws java.lang.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:
        java.lang.NullPointerException - in case of methodNames parameter is null
        java.lang.Exception - in case of failure.

      • injectOnCall

        public void injectOnCall​(java.lang.Class clazz,
                         java.lang.String methodName,
                         java.lang.String action)
                  throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnCall

        public void injectOnCall​(java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String action)
                  throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnExit

        public void injectOnExit​(java.lang.Class clazz,
                         java.lang.String methodName,
                         java.lang.String action)
                  throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnExit

        public void injectOnExit​(java.lang.String className,
                         java.lang.String methodName,
                         java.lang.String action)
                  throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnMethod

        public void injectOnMethod​(java.lang.Class clazz,
                           java.lang.String methodName,
                           java.lang.String condition,
                           java.lang.String action,
                           java.lang.String atInjection)
                    throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnMethod

        public void injectOnMethod​(java.lang.String className,
                           java.lang.String methodName,
                           java.lang.String condition,
                           java.lang.String action,
                           java.lang.String atInjection)
                    throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnMethodWhere

        public void injectOnMethodWhere​(java.lang.Class clazz,
                                java.lang.String methodName,
                                java.lang.String condition,
                                java.lang.String action,
                                java.lang.String where)
                         throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectOnMethodWhere

        public void injectOnMethodWhere​(java.lang.String className,
                                java.lang.String methodName,
                                java.lang.String condition,
                                java.lang.String action,
                                java.lang.String where)
                         throws java.lang.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:
        java.lang.Exception - in case of failure.

      • injectFault

        public void injectFault​(java.lang.Class clazz,
                        java.lang.String methodName,
                        java.lang.Class<? extends java.lang.Throwable> fault,
                        java.lang.Object[] faultArgs)
                 throws java.lang.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:
        java.lang.Exception - in case of failure.

      • crashAtMethodExit

        public void crashAtMethodExit​(java.lang.Class clazz,
                              java.lang.String methodName)
                       throws java.lang.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:
        java.lang.Exception - in case of failure.

      • crashAtMethodExit

        public void crashAtMethodExit​(java.lang.String className,
                              java.lang.String methodName)
                       throws java.lang.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:
        java.lang.Exception - in case of failure.

      • crashAtMethodEntry

        public void crashAtMethodEntry​(java.lang.Class clazz,
                               java.lang.String methodName)
                        throws java.lang.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:
        java.lang.Exception - in case of failure.

      • crashAtMethodEntry

        public void crashAtMethodEntry​(java.lang.String className,
                               java.lang.String methodName)
                        throws java.lang.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:
        java.lang.Exception - in case of failure.

      • crashAtMethod

        public void crashAtMethod​(java.lang.String className,
                          java.lang.String methodName,
                          java.lang.String atInjection)
                   throws java.lang.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:
        java.lang.Exception - in case of failure.

      • installScript

        public void installScript​(java.lang.String scriptName,
                          java.lang.String scriptString)
                   throws java.lang.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:
        java.lang.Exception - in case of failure.

      • installRule

        public java.lang.String installRule​(RuleConstructor builder)
                             throws java.lang.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:
        java.lang.Exception - in case of failure

      • removeScript

        public void removeScript​(java.lang.String scriptName)
                  throws java.lang.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:
        java.lang.Exception - in case that script can't be removed

      • removeRule

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

      • removeLocalState

        public void removeLocalState()
                      throws java.lang.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:
        java.lang.Exception - in case of failure.

      • removeAllInstrumentation

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

      • appendToFile

        private void appendToFile​(java.io.File file,
                          java.lang.String rule)
                   throws java.lang.Exception
        Write the given text to the end of the file.
        Parameters:
        file - a file name.
        rule - the text to append to the file.
        Throws:
        java.lang.Exception - in case of failure.

      • publish

        private InstrumentedClass publish​(java.lang.String className)
                           throws java.lang.Exception
        Create a local communication endpoint for the the given class.
        Parameters:
        className - the class to create the wrapper for.
        Returns:
        a local handle for accessing trace information received from the remote instrumentation.
        Throws:
        java.lang.Exception - in case of failure.

      • unpublish

        private void unpublish​(java.lang.String className)
                throws java.lang.Exception
        Remove the local communication endpoint for the given class.
        Parameters:
        className - the class to remove.
        Throws:
        java.lang.Exception - in case of failure.

      • isInterface

        private boolean isInterface​(java.lang.String className)
        Trying to load a class and if successful then check if class is interface. If it's then returns true. In all other cases returns false.

      • findInstalledScript

        private ScriptText findInstalledScript​(java.lang.String scriptName)
        Looping through installed scripts and checking if scriptName is there. If so returns it otherwise returns null.