com.google.testing.threadtester
Interface ClassInstrumentation

public interface ClassInstrumentation

Contains information about a class that has been instrumented. This allows CodePosition objects to be created for the class.

CodePositions are often specified relative to methods. For example, a CodePosition can be created at the beginning of a particular method within the instrumented class. When referring to methods, two approaches are offered: by name, and by a Method object. Names are simpler, but can be ambiguous when overloading is used. Given the following code:

 public void printMessage();
 public void printMessage(PrintStream output);
 

a simple reference to the method "printMessage" is ambiguous. In order to specify which version of printMessage is being referred to, specify a CodePosition using a Method object. See atMethodStart(String) and atMethodStart(Method).

If an ambiguous method is referred to by name, then an IllegalArgumentException will be thrown. In addition, if a reference is made to a non-existent or invalid method, an IllegalArgumentException will be thrown. Note that CodePositions can only be created for methods directly defined in the corresponding Class. Given a class Foo, the ClassInstrumentation corresponding to Foo can only be used to create breakpoints in methods defined directly in Foo. (I.e. for methods that can be obtained by invoking Foo.class.getDeclaredMethod().) CodePositions cannot be created in constructors.

Author:

alasdair.mackintosh@gmail.com (Alasdair Mackintosh)

Method Summary

CodePosition	afterCall(Method caller, Method called) Returns a CodePosition just after a call made within a method.
CodePosition	afterCall(String caller, String called) Returns a CodePosition just after a call made within a method.
CodePosition	afterSync(Method method, Object syncTarget) Returns a CodePosition representing the end of a synchronized block, after the lock has been released
CodePosition	afterSync(String methodName, Object syncTarget) Returns a CodePosition representing the end of a synchronized block, after the lock has been released
CodePosition	atMethodEnd(Method method) Returns a CodePosition representing the end of a method, after all of the code in the method has executed.
CodePosition	atMethodEnd(String methodName) Returns a CodePosition representing the end of a method, after all of the code in the method has executed.
CodePosition	atMethodStart(Method method) Returns a CodePosition representing the start of a method, before any of the code in the method executes.
CodePosition	atMethodStart(String methodName) Returns a CodePosition representing the start of a method, before any of the code in the method executes.
CodePosition	beforeCall(Method caller, Method called) Returns a CodePosition just before a call made within a method.
CodePosition	beforeCall(String caller, String called) Returns a CodePosition just before a call to a target method from within the main method.
CodePosition	beforeSync(Method method, Object syncTarget) Returns a CodePosition representing the start of a synchronized block, before the lock has beebn taken.
CodePosition	beforeSync(String methodName, Object syncTarget) Returns a CodePosition representing the start of a synchronized block, before the lock has beebn taken.
MethodInstrumentation	getMethod(Method method) Returns the instrumented method for the given method.
MethodInstrumentation	getMethod(String methodName) Returns the instrumented method for the given method name.
Collection<MethodInstrumentation>	getMethods() Returns the instrumented methods in this class.

Method Detail

atMethodStart

CodePosition atMethodStart(String methodName)

Returns a CodePosition representing the start of a method, before any of the code in the method executes. If the method is synchronized, this represents a position before the synchronized block is entered.

atMethodStart

CodePosition atMethodStart(Method method)

Returns a CodePosition representing the start of a method, before any of the code in the method executes. If the method is synchronized, this represents a position before the synchronized block is entered.

atMethodEnd

CodePosition atMethodEnd(String methodName)

Returns a CodePosition representing the end of a method, after all of the code in the method has executed. If the method throws an exception, then a Breakpoint created at this position will still be hit.

atMethodEnd

CodePosition atMethodEnd(Method method)

Returns a CodePosition representing the end of a method, after all of the code in the method has executed. If the method throws an exception, then a Breakpoint created at this position will still be hit.

beforeCall

CodePosition beforeCall(String caller,
                        String called)

Returns a CodePosition just before a call to a target method from within the main method. A Breakpoint created at this position will be hit the first time the target method is called. (If there are multiple calls to the same target method, only the first call is considered.)

Given the following code in the class:

 public void printSomething() {
   System.out.printf("Hello\n");
 }
 

Then we can get the CodePoint representing a position just before the call to "printf" made within the method "printSomething" by:

 CodePosition cp = beforeCall("printSomething", "printf",...);
 

Parameters:

caller - the name of the method in which the position should be created.

called - the name of the target method.

Returns:

the new code position

beforeCall

CodePosition beforeCall(Method caller,
                        Method called)

Returns a CodePosition just before a call made within a method. See beforeCall(Method, Method).

Parameters:

caller - the method in which the position should be created.

called - the target method.

Returns:

the new code position

afterCall

CodePosition afterCall(String caller,
                       String called)

Returns a CodePosition just after a call made within a method. A Breakpoint created at this position will be hit on returning from the first invocation of the the target method. (If there are multiple calls to the same target method, only the first call is considered.)

Given the following code in the class:

 public void printSomething() {
   System.out.printf("Hello\n");
 }
 

Then we can get the CodePoint representing a position just after the call to "printf" made within the method "printSomething" by:

 CodePosition cp = afterCall("printSomething", "printf",...);
 

Parameters:

caller - the name of the method in which the position should be created

called - the name of the target method

Returns:

the new code position

afterCall

CodePosition afterCall(Method caller,
                       Method called)

Returns a CodePosition just after a call made within a method. See afterCall(Method, Method).

Parameters:

caller - the method in which the position should be created.

called - the target method.

Returns:

the new code position

beforeSync

CodePosition beforeSync(String methodName,
                        Object syncTarget)

Returns a CodePosition representing the start of a synchronized block, before the lock has beebn taken.

Parameters:

methodName - the name of the method containing the synchronized block.

syncTarget - the object being synchronized.

Returns:

the code position

beforeSync

CodePosition beforeSync(Method method,
                        Object syncTarget)

Returns a CodePosition representing the start of a synchronized block, before the lock has beebn taken.

Parameters:

method - the method containing the synchronized block.

syncTarget - the object being synchronized.

Returns:

the code position

afterSync

CodePosition afterSync(String methodName,
                       Object syncTarget)

Returns a CodePosition representing the end of a synchronized block, after the lock has been released

Parameters:

methodName - the name of the method containing the synchronized block.

syncTarget - the object being synchronized.

Returns:

the code position

afterSync

CodePosition afterSync(Method method,
                       Object syncTarget)

Returns a CodePosition representing the end of a synchronized block, after the lock has been released

Parameters:

method - the method containing the synchronized block.

syncTarget - the object being synchronized.

Returns:

the code position

getMethods

Collection<MethodInstrumentation> getMethods()

Returns the instrumented methods in this class.

Returns:

the methods

getMethod

MethodInstrumentation getMethod(String methodName)

Returns the instrumented method for the given method name.

getMethod

MethodInstrumentation getMethod(Method method)

Returns the instrumented method for the given method.