de.uka.ipd.sdq.ByCounter.execution
Class BytecodeCounter

java.lang.Object
  extended by de.uka.ipd.sdq.ByCounter.execution.BytecodeCounter

public final class BytecodeCounter
extends java.lang.Object

Use this class to trigger counting of instructions for your methods. Bytecode instructions are counted accurately with the exception of certain special versions of opcodes, as described in the ASM JavaDoc (http://asm.objectweb.org/asm30/javadoc/user/org/objectweb/asm/Opcodes.html): "[..] some opcodes are automatically handled. For example, the xLOAD and xSTORE opcodes are automatically replaced by xLOAD_n and xSTORE_n opcodes when possible. The xLOAD_n and xSTORE_n opcodes are therefore not defined in this interface. Likewise for LDC, IINC, RET automatically replaced by LDC_W or LDC2_W when necessary, WIDE, GOTO_W and JSR_W." To instrument methods of classes, call instrument(...). To execute instrumented code, call execute(...). To access the results use CountingResultCollector singleton.

Since:
0.1
Version:
1.2 TODO investigate whether slash-separated class names should be supported alongside "."-supported class names
Author:
Martin Krogmann, Michael Kuperberg

Constructor Summary
BytecodeCounter()
          Setup a new BytecodeCounter.
 
Method Summary
 void clearClassFileToInstrument()
          This undoes the call of setClassToInstrument() and returns BytecodeCounter into its standard instrumentation mode.
 void clearConstructionParameters()
          Removes all construction parameters passed by calling setConstructionParameters(..);.
 InvocationResultData execute(MethodDescriptor methodToExecute, java.lang.Object[] params)
          Execute the method specified by methodToExecute using the given parameters.
 InvocationResultData execute(MethodDescriptor methodToExecute, java.lang.Object target, java.lang.Object[] params)
          Execute the method specified by methodToExecute using the given parameters on the given instance.
 InvocationResultData execute(MethodDescriptor methodToExecute, java.lang.Object target, RuntimeMethodParameters params)
          Execute the method specified by methodToExecute using the given parameters.
 InvocationResultData execute(MethodDescriptor methodToExecute, RuntimeMethodParameters params)
          Execute the method specified by methodToExecute using the given parameters.
 ExecutionSettings getExecutionSettings()
          Use these parameters to influence the way execution and counting of instrumentation results are handled.
 InstrumentationParameters getInstrumentationParams()
          Returns the current instrumentation parameters.
 byte[] getInstrumentedBytes()
          Gets a byte[] representing a Class of the type specified by the className attribute of the first MethodDescriptor supplied to instrument(..)
 java.lang.Object instantiate(MethodDescriptor methodToExecute)
          Creates an instance of the class which contains the provided method.
 boolean instrument()
          Instrument the methods specified in the InstrumentationParameters of this BytecodeCounter.
 boolean instrument(java.util.List<MethodDescriptor> methodsToInstrument)
          Instrument the specified methods with ByCounter instructions for counting, reporting etc.
 void instrument(MethodDescriptor methodToInstrument)
          Instrument the specified method with ByCounter instructions for counting, reporting etc.
 boolean instrumentAllInClass(java.lang.String className, java.lang.String[] listOfExceptions)
           
 boolean instrumentAllInClass(java.lang.String className, java.lang.String[] listOfExceptions, boolean printInstrumentationSummary)
          Instrument all methods.
 boolean instrumentAllInClassWithoutExceptions(java.lang.String className)
          Instrument all methods of a class, without exceptions.
 void setClassToInstrument(byte[] classToInstrument)
          Specifies (changes) the class to instrument to be the class specified as the byte array.
 void setConstructionParameters(MethodDescriptor constructor, java.lang.Object[] parameters)
          Parameters for class construction are needed when execute is called on a class with no default constructor.
 void setExecutionSettings(ExecutionSettings executionSettings)
          Use these parameters to influence the way execution and counting of instrumentation results are handled.
 void setInstrumentationParams(InstrumentationParameters params)
          Sets the parameters for instrumentation.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

BytecodeCounter

public BytecodeCounter()
Setup a new BytecodeCounter.

Method Detail

clearClassFileToInstrument

public void clearClassFileToInstrument()
This undoes the call of setClassToInstrument() and returns BytecodeCounter into its standard instrumentation mode.


clearConstructionParameters

public void clearConstructionParameters()
Removes all construction parameters passed by calling setConstructionParameters(..);. This is necessary if you want to call execute() on a method that was called before and that was constructed differently.


execute

public InvocationResultData execute(MethodDescriptor methodToExecute,
                                    java.lang.Object[] params)
Execute the method specified by methodToExecute using the given parameters. Every time you call execute on a non-static method, the containing class will be instantiated by ByCounter.

Parameters:
methodToExecute - A MethodDescriptor describing the specific method that shall be executed.
params - Parameters as an array of Objects that are used to execute the method specified by methodToExecute. Use an empty array for methods that take no parameters.
Returns:
Result and duration of execution.

execute

public InvocationResultData execute(MethodDescriptor methodToExecute,
                                    java.lang.Object target,
                                    java.lang.Object[] params)
Execute the method specified by methodToExecute using the given parameters on the given instance.

Parameters:
methodToExecute - A MethodDescriptor describing the specific method that shall be executed.
params - Parameters as an array of Objects that are used to execute the method specified by methodToExecute. Use an empty array for methods that take no parameters.
Returns:
Result and duration of execution.

execute

public InvocationResultData execute(MethodDescriptor methodToExecute,
                                    RuntimeMethodParameters params)
Execute the method specified by methodToExecute using the given parameters. Every time you call execute on a non-static method, the containing class will be instantiated by ByCounter.

Parameters:
methodToExecute - A MethodDescriptor describing the specific method that shall be executed.
params - Parameters as RuntimeMethodParameters that are used to execute the method specified by methodToExecute. Use the default constructor of RuntimeMethodParameters for methods that take no parameters.
Returns:
Result and duration of execution.

execute

public InvocationResultData execute(MethodDescriptor methodToExecute,
                                    java.lang.Object target,
                                    RuntimeMethodParameters params)
Execute the method specified by methodToExecute using the given parameters. Static methods can be executed with parameter target equals null.

Parameters:
methodToExecute - A MethodDescriptor describing the specific method that shall be executed.
target - Instance on which the method is executed.
params - Parameters as RuntimeMethodParameters that are used to execute the method specified by methodToExecute. Use the default constructor of RuntimeMethodParameters for methods that take no parameters.
Returns:
Result and duration of execution.

getExecutionSettings

public ExecutionSettings getExecutionSettings()
Use these parameters to influence the way execution and counting of instrumentation results are handled.

Returns:
The current execution parameters.

getInstrumentationParams

public InstrumentationParameters getInstrumentationParams()
Returns the current instrumentation parameters. Use this to change the way the instrumenter works. Note that the methods to instrument will be overridden by the instrument* methods.

Returns:
the instrumentation parameters.

getInstrumentedBytes

public byte[] getInstrumentedBytes()
Gets a byte[] representing a Class of the type specified by the className attribute of the first MethodDescriptor supplied to instrument(..) The class is modified in such a way that the methods specified by methodsToInstrument (again see instrument(..)) have been instrumented by ByCounter. This makes the assumption that the class for all methods is the same.

Returns:
Class as byte[] with instrumented methods if the instrumentation succeeded. 'null' otherwise.

instrument

public boolean instrument()
Instrument the methods specified in the InstrumentationParameters of this BytecodeCounter. The InstrumentationParameters can be accessed using get- or setInstrumentationParameters(). Make sure you set the methodsToInstrument or this call will fail with an error.

Returns:
True, if the instrumentation was successful, false otherwise.

instrumentAllInClass

public boolean instrumentAllInClass(java.lang.String className,
                                    java.lang.String[] listOfExceptions)

instrumentAllInClass

public boolean instrumentAllInClass(java.lang.String className,
                                    java.lang.String[] listOfExceptions,
                                    boolean printInstrumentationSummary)
Instrument all methods.

Parameters:
className - Canonical class name
listOfExceptions - A list of packages prefixes or classes that will not be instrumented TODO this is not working right now...
Returns:
True, if the instrumentation process succeeds.

instrumentAllInClassWithoutExceptions

public boolean instrumentAllInClassWithoutExceptions(java.lang.String className)
Instrument all methods of a class, without exceptions.

Parameters:
className - Canonical class name
Returns:
True, if the instrumentation process succeeds.

instrument

public boolean instrument(java.util.List<MethodDescriptor> methodsToInstrument)
Instrument the specified methods with ByCounter instructions for counting, reporting etc.

Parameters:
methodsToInstrument - A List of MethodDescriptors where each MethodDescriptor represent a method that will be instrumented.
Returns:
True, if the instrumentation was successful, false otherwise.

instrument

public void instrument(MethodDescriptor methodToInstrument)
Instrument the specified method with ByCounter instructions for counting, reporting etc.

Parameters:
methodToInstrument - A MethodDescriptor representing the method to instrument.

setClassToInstrument

public void setClassToInstrument(byte[] classToInstrument)
Specifies (changes) the class to instrument to be the class specified as the byte array.

To stop using the here specified class and use the standard instrumentation mode again, call clearClassFileToInstrument().

Parameters:
classToInstrument - A byte array representing the class to instrument.

setConstructionParameters

public void setConstructionParameters(MethodDescriptor constructor,
                                      java.lang.Object[] parameters)
Parameters for class construction are needed when execute is called on a class with no default constructor. Use this method to supply these construction parameters.

Parameters:
constructor - A MethodDescriptor for the constructor that shall be used for a following execute() call on the same class. Use MethodDescriptor.forConstructor() to describe constructors.
parameters -

setExecutionSettings

public void setExecutionSettings(ExecutionSettings executionSettings)
Use these parameters to influence the way execution and counting of instrumentation results are handled.

Parameters:
executionSettings - The current execution parameters to use.

setInstrumentationParams

public void setInstrumentationParams(InstrumentationParameters params)
Sets the parameters for instrumentation.

Parameters:
params - An InstrumentationParameters object with all properties for instrumentation set.

instantiate

public java.lang.Object instantiate(MethodDescriptor methodToExecute)
Creates an instance of the class which contains the provided method.

Parameters:
methodToExecute - Method (which will later be executed on the created instance).
Returns:
Class instance.