org.jboss.byteman.contrib.dtest

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.

Author:

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

Constructor Summary

Constructors

Constructor and Description
Instrumentor()
Instrumentor(String address, int port)
Instrumentor(String address, int port, int rmiPort)
Instrumentor(Submit submit, int rmiRegistryPort)

Method Summary

Methods

Modifier and Type	Method and Description
void	crashAtMethod(String className, String methodName, String where) Inject a Rule to kill the target JVM at a given point within the specified Class.method()
void	crashAtMethodEntry(Class clazz, String methodName) Inject a Rule to kill the target JVM upon entry to the specified Class.method()
void	crashAtMethodEntry(String className, String methodName) Inject a Rule to kill the target JVM upon entry to the specified Class.method()
void	crashAtMethodExit(Class clazz, String methodName) Inject a Rule to kill the target JVM upon exit of the specified Class.method()
void	crashAtMethodExit(String className, String methodName) Inject a Rule to kill the target JVM upon exit of the specified Class.method()
File	getRedirectedSubmissionsFile() Returns the file to which Rule submission is currently redirected
void	injectFault(Class clazz, String methodName, Class<? extends Throwable> fault, Object[] faultArgs) Inject a fault (i.e.
void	injectOnCall(Class clazz, String methodName, String action) Inject an action to take place upon the invocation of the specified class.method
void	injectOnExit(Class clazz, String methodName, String action) Inject an action to take place upon exit of the specified class.method
void	injectOnMethod(Class clazz, String methodName, String condition, String action, String where) Inject an action to take place at a given point within the specified class.method
void	installHelperJar(String path) Add the specified jar to the remote app's system classpath.
void	installScript(String scriptName, String scriptString) Pass the assembled script to the remote JVM, either via.
InstrumentedClass	instrumentClass(Class clazz) Add method tracing rules to the specified class.
InstrumentedClass	instrumentClass(Class clazz, Set<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(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 RemoteException

Throws:

RemoteException

Instrumentor

public Instrumentor()
             throws RemoteException

Throws:

RemoteException

Instrumentor

public Instrumentor(String address,
            int port)
             throws RemoteException

Throws:

RemoteException

Instrumentor

public Instrumentor(String address,
            int port,
            int rmiPort)
             throws RemoteException

Throws:

RemoteException

Method Detail

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.

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.

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.

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.

injectOnMethod

public void injectOnMethod(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

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 point e.g. "ENTRY".

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

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

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.