org.jboss.byteman.contrib.dtest
Class Instrumentor

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

public class Instrumentor
extends java.lang.Object

The Instrumentor provides for installing tracing and other rules into a remote JVM.

Author:
Jonathan Halliday (jonathan.halliday@redhat.com) 2010-05

Constructor Summary
Instrumentor()
           
Instrumentor(java.lang.String address, int port)
           
Instrumentor(java.lang.String address, int port, int rmiPort)
           
Instrumentor(Submit submit, int rmiRegistryPort)
           
 
Method Summary
 void crashAtMethod(java.lang.String className, java.lang.String methodName, java.lang.String where)
          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()
 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 installHelperJar(java.lang.String path)
          Add the specified jar to the remote app's system classpath.
 InstrumentedClass instrumentClass(java.lang.Class clazz)
          Add method tracing rules to the specified class.
 InstrumentedClass instrumentClass(java.lang.Class clazz, java.util.Set<java.lang.String> methodNames)
          Add method tracing rules to the specified 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 setRedirectedSubmissionsFile(java.io.File redirectedSubmissionsFile)
          Sets the file to which Rule submissions should be redirected.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

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

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.

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.

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 where)
                   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.
where - the injection point e.g. "ENTRY".
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.


Copyright © 2012. All Rights Reserved.