Class Instrumentor

java.lang.Object
org.jboss.byteman.contrib.dtest.Instrumentor

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

    • submit

      private final Submit submit
    • registry

      private final Registry registry
    • rmiRegistryPort

      private final int rmiRegistryPort
    • instrumentedClasses

      private final Map<String,InstrumentedClass> instrumentedClasses
    • installedScripts

      private final List<ScriptText> installedScripts
    • redirectedSubmissionsFile

      private File redirectedSubmissionsFile
    • helperClass

      private Class<?> helperClass
  • Constructor Details

  • Method Details

    • 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, String... methodNames) throws Exception
      Throws:
      Exception
    • 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, String... methodNames) throws Exception
      Parameters:
      className - the class name to instrument.
      methodNames - the selection of methods to instrument.
      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.
      condition - the rule condition
      action - The action that should take place upon invocation of the method.
      atInjection - the injection point e.g. "ENTRY".
      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.
      condition - the rule condition
      action - The action that should take place upon invocation of the method.
      atInjection - the injection point e.g. "ENTRY".
      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.
      condition - the rule condition
      action - The action that should take place upon invocation of the method.
      where - the injection definition e.g. "AT ENTRY" or "AFTER SYNCHRONIZATION".
      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.
      condition - the rule condition
      action - The action that should take place upon invocation of the method.
      where - the injection definition e.g. "AT ENTRY" or "AFTER SYNCHRONIZATION".
      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.
    • appendToFile

      private void appendToFile(File file, String rule) throws 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:
      Exception - in case of failure.
    • publish

      private InstrumentedClass publish(String className) throws 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:
      Exception - in case of failure.
    • unpublish

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

      private boolean isInterface(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(String scriptName)
      Looping through installed scripts and checking if scriptName is there. If so returns it otherwise returns null.