de.uka.ipd.sdq.ByCounter.instrumentation
Class InstrumentationParameters

java.lang.Object
  extended by de.uka.ipd.sdq.ByCounter.instrumentation.InstrumentationParameters
All Implemented Interfaces:
java.lang.Cloneable

public final class InstrumentationParameters
extends java.lang.Object
implements java.lang.Cloneable

A collection of properties that determine the way the instrumentation is done.

Some combination of parameters only make sense in combination with others. The following list summarizes these dependencies.

Since:
0.1
Version:
1.2
Author:
Martin Krogmann, Michael Kuperberg

Field Summary
static boolean COUNT_STATICALLY_DEFAULT
          Default value for getCountStatically().
static java.lang.String[] IGNORED_PACKAGES_DEFAULT
          Default value for getIgnoredPackagePrefixes().
static boolean INSTRUMENT_RECURSIVELY_DEFAULT
          Default value for getInstrumentRecursively().
static int INSTRUMENT_RECURSIVELY_MAX_DEPTH_DEFAULT
          Default value for getInstrumentRecursivelyMaxDepth().
static InstrumentationScopeModeEnum INSTRUMENTATION_SCOPE_OVERRIDE_CLASS_LEVEL_DEFAULT
          Default value for getInstrumentationScopeOverrideClassLevel().
static InstrumentationScopeModeEnum INSTRUMENTATION_SCOPE_OVERRIDE_METHOD_LEVEL_DEFAULT
          Default value for getInstrumentationScopeOverrideMethodLevel().
static java.util.List<MethodDescriptor> METHODS_TO_INSTRUMENT_DEFAULT
          Default value for getMethodsToInstrument().
static boolean RECORD_BLOCK_EXECUTION_ORDER_DEFAULT
          Default value for getRecordBlockExecutionOrder(): true
static java.lang.String RESULT_LOG_DEFAULT_DIRECTORY
          Directory in which result log files are written by default.
static java.lang.String RESULT_LOG_DEFAULT_PREFIX
          Default file name prefix of the result log files.
static boolean TRACE_AND_IDENTIFY_REQUESTS_DEFAULT
          Default value for getTraceAndIdentifyRequests().
static boolean USE_ARRAY_PARAMETER_RECORDING
          Default value for getUseArrayParameterRecording().
static boolean USE_BASIC_BLOCKS_DEFAULT
          Default value for getUseBasicBlocks(): false
static boolean USE_HIGH_REGISTERS_FOR_COUNTING_DEFAULT
          Default value for getUseHighRegistersForCounting().
static boolean USE_RESULT_COLLECTOR_DEFAULT
          Default value for getUseResultCollector().
static boolean USE_RESULT_LOG_WRITER_DEFAULT
          Default value for getUseResultLogWriter().
static boolean WRITE_CLASSES_TO_DISK_DEFAULT
          Default value for getWriteClassesToDisk().
static java.io.File WRITE_CLASSES_TO_DISK_DIRECTORY_DEFAULT
          Default value for getWriteClassesToDiskDirectory().
 
Constructor Summary
InstrumentationParameters()
          This is intended only for construction in multiple steps.
InstrumentationParameters(java.util.List<MethodDescriptor> pMethodsToInstrument)
          Assumes dynamic analysis and usage of the CountingResultCollector.
InstrumentationParameters(java.util.List<MethodDescriptor> pMethodsToInstrument, boolean pUseHighRegistersForCounting, boolean pUseResultCollector, boolean pUseArrayParameterRecording, boolean countStatically, InstrumentationCounterPrecision counterPrecision)
           
 
Method Summary
 InstrumentationParameters clone()
           
 void disableResultLogWriter()
          Disable result log writing.
 void enableResultLogWriter(java.lang.String resultLogFileName)
          Enable writing of result logs and set the filename for the log that is created.
 InstrumentationCounterPrecision getCounterPrecision()
           
 boolean getCountStatically()
          Deprecated. Static counting is implemented only in it's basics (opcode and method call counts). It is not a focus of ByCounter.
 java.lang.String[] getIgnoredPackagePrefixes()
           
 InstrumentationScopeModeEnum getInstrumentationScopeOverrideClassLevel()
           
 InstrumentationScopeModeEnum getInstrumentationScopeOverrideMethodLevel()
           
 boolean getInstrumentRecursively()
           
 int getInstrumentRecursivelyMaxDepth()
           
 java.util.List<MethodDescriptor> getMethodsToInstrument()
           
 boolean getProvideOnlineSectionExecutionUpdates()
          CountingResultCollector provides a mechanism for monitoring online updates on incoming results.
 boolean getRecordBlockExecutionOrder()
          When true, record the exact order in which blocks are executed.
 java.lang.String getResultLogFileName()
           
 boolean getTraceAndIdentifyRequests()
          RequestIDs are UUIDs used to track the method call graph across threads.
 boolean getUseArrayParameterRecording()
          Decides whether instrumentation for the recording of parameters of array construction takes place.
 boolean getUseBasicBlocks()
          When true, bytecode instructions will be counted in groups made up of identified basic blocks.
 boolean getUseHighRegistersForCounting()
           
 boolean getUseResultCollector()
           
 boolean getUseResultLogWriter()
           
 boolean getWriteClassesToDisk()
          When true, ByCounter will write the instrumented class files to the "bin_instrumented" directory.
 java.io.File getWriteClassesToDiskDirectory()
           
 boolean hasMethodsWithCodeAreas()
           
 void setCounterPrecision(InstrumentationCounterPrecision counterPrecision)
           
 void setCountStatically(boolean countStatically)
          Deprecated. Static counting is implemented only in it's basics (opcode and method call counts). It is not a focus of ByCounter.
static void setIgnoredPackagePrefixes(java.lang.String[] ignoredPackagePrefixes)
           
 void setInstrumentationScopeOverrideClassLevel(InstrumentationScopeModeEnum instrumentationScopeOverrideClassLevel)
           
 void setInstrumentationScopeOverrideMethodLevel(InstrumentationScopeModeEnum instrumentationScopeOverrideMethodLevel)
           
 void setInstrumentRecursively(boolean instrumentRecursively)
          When set, instruments methods called from the setMethodsToInstrument(List) that are not Java API methods (packages java.*, javax.* sun.*) and not native methods.
 void setInstrumentRecursively(boolean instrumentRecursively, int maxDepth)
           
 void setMethodsToInstrument(java.util.List<MethodDescriptor> methodsToInstrument)
           
 void setProvideOnlineSectionExecutionUpdates(boolean provideOnlineSectionExecutionUpdates)
           
 void setRecordBlockExecutionOrder(boolean recordBlockExecutionOrder)
           
 void setTraceAndIdentifyRequests(boolean traceAndIdentifyRequests)
          RequestIDs are UUIDs used to track the method call graph across threads.
 void setUseArrayParameterRecording(boolean useArrayParameterRecording)
          Decides whether instrumentation for the recording of parameters of array construction takes place.
 void setUseBasicBlocks(boolean useBasicBlocks)
          When true, bytecode instructions will be counted in groups made up of identified basic blocks.
 void setUseHighRegistersForCounting(boolean useHighRegistersForCounting)
          Decides whether to preallocate registers near max_locals instead of using LocalVariablesSorter.
 void setUseResultCollector(boolean useResultCollector)
           
 void setWriteClassesToDisk(boolean write)
          Sets the value of writeClassesToDisk.
 void setWriteClassesToDiskDirectory(java.io.File outputClassDirectory)
          If getWriteClassesToDisk() is enabled, classes will be written to the here specified directory.
 java.lang.String toString()
          
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

IGNORED_PACKAGES_DEFAULT

public static final java.lang.String[] IGNORED_PACKAGES_DEFAULT
Default value for getIgnoredPackagePrefixes().


USE_BASIC_BLOCKS_DEFAULT

public static final boolean USE_BASIC_BLOCKS_DEFAULT
Default value for getUseBasicBlocks(): false

See Also:
Constant Field Values

RECORD_BLOCK_EXECUTION_ORDER_DEFAULT

public static final boolean RECORD_BLOCK_EXECUTION_ORDER_DEFAULT
Default value for getRecordBlockExecutionOrder(): true

See Also:
Constant Field Values

INSTRUMENTATION_SCOPE_OVERRIDE_CLASS_LEVEL_DEFAULT

public static final InstrumentationScopeModeEnum INSTRUMENTATION_SCOPE_OVERRIDE_CLASS_LEVEL_DEFAULT
Default value for getInstrumentationScopeOverrideClassLevel().


INSTRUMENTATION_SCOPE_OVERRIDE_METHOD_LEVEL_DEFAULT

public static final InstrumentationScopeModeEnum INSTRUMENTATION_SCOPE_OVERRIDE_METHOD_LEVEL_DEFAULT
Default value for getInstrumentationScopeOverrideMethodLevel().


WRITE_CLASSES_TO_DISK_DIRECTORY_DEFAULT

public static final java.io.File WRITE_CLASSES_TO_DISK_DIRECTORY_DEFAULT
Default value for getWriteClassesToDiskDirectory().


TRACE_AND_IDENTIFY_REQUESTS_DEFAULT

public static final boolean TRACE_AND_IDENTIFY_REQUESTS_DEFAULT
Default value for getTraceAndIdentifyRequests().

See Also:
Constant Field Values

WRITE_CLASSES_TO_DISK_DEFAULT

public static final boolean WRITE_CLASSES_TO_DISK_DEFAULT
Default value for getWriteClassesToDisk().

See Also:
Constant Field Values

INSTRUMENT_RECURSIVELY_DEFAULT

public static final boolean INSTRUMENT_RECURSIVELY_DEFAULT
Default value for getInstrumentRecursively().

See Also:
Constant Field Values

INSTRUMENT_RECURSIVELY_MAX_DEPTH_DEFAULT

public static final int INSTRUMENT_RECURSIVELY_MAX_DEPTH_DEFAULT
Default value for getInstrumentRecursivelyMaxDepth().

See Also:
Constant Field Values

METHODS_TO_INSTRUMENT_DEFAULT

public static final java.util.List<MethodDescriptor> METHODS_TO_INSTRUMENT_DEFAULT
Default value for getMethodsToInstrument().


USE_HIGH_REGISTERS_FOR_COUNTING_DEFAULT

public static final boolean USE_HIGH_REGISTERS_FOR_COUNTING_DEFAULT
Default value for getUseHighRegistersForCounting().

See Also:
Constant Field Values

USE_RESULT_COLLECTOR_DEFAULT

public static final boolean USE_RESULT_COLLECTOR_DEFAULT
Default value for getUseResultCollector().

See Also:
Constant Field Values

USE_RESULT_LOG_WRITER_DEFAULT

public static final boolean USE_RESULT_LOG_WRITER_DEFAULT
Default value for getUseResultLogWriter().

See Also:
Constant Field Values

USE_ARRAY_PARAMETER_RECORDING

public static final boolean USE_ARRAY_PARAMETER_RECORDING
Default value for getUseArrayParameterRecording().

See Also:
Constant Field Values

COUNT_STATICALLY_DEFAULT

public static final boolean COUNT_STATICALLY_DEFAULT
Default value for getCountStatically().

See Also:
Constant Field Values

RESULT_LOG_DEFAULT_DIRECTORY

public static final java.lang.String RESULT_LOG_DEFAULT_DIRECTORY
Directory in which result log files are written by default. This only applies if getUseResultCollector() == true.

See Also:
RESULT_LOG_DEFAULT_PREFIX, Constant Field Values

RESULT_LOG_DEFAULT_PREFIX

public static final java.lang.String RESULT_LOG_DEFAULT_PREFIX
Default file name prefix of the result log files. This only applies if getUseResultCollector() == true.

See Also:
RESULT_LOG_DEFAULT_DIRECTORY
Constructor Detail

InstrumentationParameters

public InstrumentationParameters()
This is intended only for construction in multiple steps. Methods to instrument are NOT set - you must do so manually! Assumes dynamic analysis and usage of the CountingResultCollector. Uses high registers for counting and the CountingResultCollector framework.


InstrumentationParameters

public InstrumentationParameters(java.util.List<MethodDescriptor> pMethodsToInstrument)
Assumes dynamic analysis and usage of the CountingResultCollector. Array construction parameters will not be recorded. Uses high registers for counting.

Parameters:
pMethodsToInstrument - Name of the methods that shall be instrumented. When false, results are written to disk directly.

InstrumentationParameters

public InstrumentationParameters(java.util.List<MethodDescriptor> pMethodsToInstrument,
                                 boolean pUseHighRegistersForCounting,
                                 boolean pUseResultCollector,
                                 boolean pUseArrayParameterRecording,
                                 boolean countStatically,
                                 InstrumentationCounterPrecision counterPrecision)
Parameters:
pMethodsToInstrument - Name of the methods that shall be instrumented.
pUseHighRegistersForCounting - Decides whether to preallocate registers near max_locals instead of using LocalVariablesSorter.
pUseResultCollector - Decides whether to use the CountingResultCollector framework.
pUseArrayParameterRecording - Decides whether instrumentation for the recording of parameters of array construction takes place. Causes some additional overhead.
countStatically - When true, ByCounter makes a static analysis of the specified code.
counterPrecision - Decides on the precision of the variables used for counting. See the COUNTER_PRECISION_ constants.
Method Detail

clone

public InstrumentationParameters clone()
Overrides:
clone in class java.lang.Object

getCountStatically

public boolean getCountStatically()
Deprecated. Static counting is implemented only in it's basics (opcode and method call counts). It is not a focus of ByCounter.

Returns:
Reflects, whether dynamic or static method analysis is employed.

getInstrumentRecursively

public boolean getInstrumentRecursively()
Returns:
@see setInstrumentRecursively(boolean).

getMethodsToInstrument

public java.util.List<MethodDescriptor> getMethodsToInstrument()
Returns:
The methods to instrument described as MethodDescriptor.

getResultLogFileName

public java.lang.String getResultLogFileName()
Returns:
The result log filename used if getUseResultLogWriter() == true. The given filename is a prefix to the generated filename that includes the method descriptor and a timestamp.
See Also:
enableResultLogWriter(String), getUseResultLogWriter()

getUseArrayParameterRecording

public boolean getUseArrayParameterRecording()
Decides whether instrumentation for the recording of parameters of array construction takes place. Causes some additional overhead.

Returns:
True if recording is inserted, false otherwise.

getUseHighRegistersForCounting

public boolean getUseHighRegistersForCounting()
Returns:
useHighRegistersForCounting

getUseResultCollector

public boolean getUseResultCollector()
Returns:
When true, results will be collected using CountingResultCollector.

getUseResultLogWriter

public boolean getUseResultLogWriter()
Returns:
When true, a log file will be written when instrumented methods are executed.

getWriteClassesToDisk

public boolean getWriteClassesToDisk()
When true, ByCounter will write the instrumented class files to the "bin_instrumented" directory.

Returns:
The value of writeClassesToDisk.

setCountStatically

public void setCountStatically(boolean countStatically)
Deprecated. Static counting is implemented only in it's basics (opcode and method call counts). It is not a focus of ByCounter.

Parameters:
countStatically - When true, no runtime analysis is done. Instead the method is statically analysed.

setMethodsToInstrument

public void setMethodsToInstrument(java.util.List<MethodDescriptor> methodsToInstrument)
Parameters:
methodsToInstrument - Sets the methods to instrument described as MethodDescriptor.

enableResultLogWriter

public void enableResultLogWriter(java.lang.String resultLogFileName)
Enable writing of result logs and set the filename for the log that is created. Use this if you want to override the default file name RESULT_LOG_DEFAULT_PREFIX that consists of a time stamp and the class and method name, and will be written to the RESULT_LOG_DEFAULT_DIRECTORY directory. The given filename is a prefix to the generated filename that includes the method descriptor and a timestamp.

Parameters:
resultLogFileName - The prefix of written log files.

disableResultLogWriter

public void disableResultLogWriter()
Disable result log writing.

See Also:
enableResultLogWriter(String), setUseResultCollector(boolean)

setUseArrayParameterRecording

public void setUseArrayParameterRecording(boolean useArrayParameterRecording)
Decides whether instrumentation for the recording of parameters of array construction takes place. Causes some additional overhead.

Parameters:
useArrayParameterRecording - Set to true if recording is to be inserted, false otherwise.

setUseHighRegistersForCounting

public void setUseHighRegistersForCounting(boolean useHighRegistersForCounting)
Decides whether to preallocate registers near max_locals instead of using LocalVariablesSorter. The default (when not called) is false. When true, the instrumented bytecode remains closer to the original bytecode in that the register numbers stay the same. Setting this to true might cause problems if the instrumented code uses very high register numbers (near 65000).

Parameters:
useHighRegistersForCounting - Defaults to false.

setUseResultCollector

public void setUseResultCollector(boolean useResultCollector)
Parameters:
useResultCollector - Set whether to use the CountingResultCollector.
See Also:
getUseResultCollector(), getUseResultLogWriter(), enableResultLogWriter(String), disableResultLogWriter()

setWriteClassesToDisk

public void setWriteClassesToDisk(boolean write)
Sets the value of writeClassesToDisk. When true, ByCounter will write the instrumented class files to the "bin_instrumented" directory.

Parameters:
write - The new value for writeClassesToDisk.

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

setUseBasicBlocks

public void setUseBasicBlocks(boolean useBasicBlocks)
When true, bytecode instructions will be counted in groups made up of identified basic blocks. The execution numbers of single instructions are calculated after the execution. When false, every single bytecode instruction will be counted by an individual counter.

Parameters:
useBasicBlocks - the useBasicBlocks to set

getUseBasicBlocks

public boolean getUseBasicBlocks()
When true, bytecode instructions will be counted in groups made up of identified basic blocks. The execution numbers of single instructions are calculated after the execution. When false, every single bytecode instruction will be counted by an individual counter.

Returns:
the useBasicBlocks

setTraceAndIdentifyRequests

public void setTraceAndIdentifyRequests(boolean traceAndIdentifyRequests)
RequestIDs are UUIDs used to track the method call graph across threads. They are created in a root method (a method called with no request ID) and then passed recursively on to all methods it calls. Note: Currently, constructors cannot be tracked.

Parameters:
traceAndIdentifyRequests - True, when request IDs are to be used. False otherwise. Default is false.

getTraceAndIdentifyRequests

public boolean getTraceAndIdentifyRequests()
RequestIDs are UUIDs used to track the method call graph across threads. They are created in a root method (a method called with no request ID) and then passed recursively on to all methods it calls. Note: Currently, constructors cannot be tracked.

Returns:
True, when request IDs are used. False otherwise.

setWriteClassesToDiskDirectory

public void setWriteClassesToDiskDirectory(java.io.File outputClassDirectory)
If getWriteClassesToDisk() is enabled, classes will be written to the here specified directory.

Parameters:
outputClassDirectory - The directory where instrumented class files will be written to.

getWriteClassesToDiskDirectory

public java.io.File getWriteClassesToDiskDirectory()
Returns:
If getWriteClassesToDisk() is enabled, classes will be written to the here specified directory.

setInstrumentationScopeOverrideClassLevel

public void setInstrumentationScopeOverrideClassLevel(InstrumentationScopeModeEnum instrumentationScopeOverrideClassLevel)
Parameters:
instrumentationScopeOverrideClassLevel - the instrumentationScopeOverrideClassLevel to set

getInstrumentationScopeOverrideClassLevel

public InstrumentationScopeModeEnum getInstrumentationScopeOverrideClassLevel()
Returns:
the instrumentationScopeOverrideClassLevel

setInstrumentationScopeOverrideMethodLevel

public void setInstrumentationScopeOverrideMethodLevel(InstrumentationScopeModeEnum instrumentationScopeOverrideMethodLevel)
Parameters:
instrumentationScopeOverrideMethodLevel - the instrumentationScopeOverrideMethodLevel to set

getInstrumentationScopeOverrideMethodLevel

public InstrumentationScopeModeEnum getInstrumentationScopeOverrideMethodLevel()
Returns:
the instrumentationScopeOverrideMethodLevel

getIgnoredPackagePrefixes

public java.lang.String[] getIgnoredPackagePrefixes()
Returns:
A list of strings that cause a class to be ignored in the parsing when found at the start of a package name.

getCounterPrecision

public InstrumentationCounterPrecision getCounterPrecision()
Returns:
The precision currently set.
See Also:
InstrumentationCounterPrecision

setCounterPrecision

public void setCounterPrecision(InstrumentationCounterPrecision counterPrecision)
Parameters:
counterPrecision - The precision to set.
See Also:
InstrumentationCounterPrecision

setInstrumentRecursively

public void setInstrumentRecursively(boolean instrumentRecursively)
When set, instruments methods called from the setMethodsToInstrument(List) that are not Java API methods (packages java.*, javax.* sun.*) and not native methods. Recursion will stop when getInstrumentRecursivelyMaxDepth() is reached.

Parameters:
instrumentRecursively - When true, the above aplies. specified for instrumentation (@see setMethodsToInstrument(java.util.List)).

setInstrumentRecursively

public void setInstrumentRecursively(boolean instrumentRecursively,
                                     int maxDepth)
See Also:
setInstrumentRecursively(boolean)

getInstrumentRecursivelyMaxDepth

public int getInstrumentRecursivelyMaxDepth()
Returns:
depth
See Also:
setInstrumentRecursively(boolean)

setIgnoredPackagePrefixes

public static void setIgnoredPackagePrefixes(java.lang.String[] ignoredPackagePrefixes)
Parameters:
ignoredPackagePrefixes - Prefixes of packages that are ignored.
See Also:
getIgnoredPackagePrefixes()

setRecordBlockExecutionOrder

public void setRecordBlockExecutionOrder(boolean recordBlockExecutionOrder)
Parameters:
recordBlockExecutionOrder - the recordBlockExecutionOrder to set
See Also:
getRecordBlockExecutionOrder()

getRecordBlockExecutionOrder

public boolean getRecordBlockExecutionOrder()
When true, record the exact order in which blocks are executed. This applies to range blocks and to basic blocks. The order of the results as returned by the CountingResultCollector then reflects the execution order. If this flag is set to false, the execution counts for each section are aggregated.

Note that enabling this option may result in memory and processing overhead if the instrumented code contains sections that are executed extremely often.

Returns:
the recordBlockExecutionOrder

getProvideOnlineSectionExecutionUpdates

public boolean getProvideOnlineSectionExecutionUpdates()
CountingResultCollector provides a mechanism for monitoring online updates on incoming results.

Returns:
When true, the instrumentation for providing updates on the execution of user specified code sections is inserted. This only applies when getRecordBlockExecutionOrder() is also set to true.
See Also:
Observable.addObserver(java.util.Observer)

setProvideOnlineSectionExecutionUpdates

public void setProvideOnlineSectionExecutionUpdates(boolean provideOnlineSectionExecutionUpdates)
Parameters:
provideOnlineSectionExecutionUpdates - When true, instrumentation for providing updates is added.
See Also:
getRecordBlockExecutionOrder(), getProvideOnlineSectionExecutionUpdates()

hasMethodsWithCodeAreas

public boolean hasMethodsWithCodeAreas()
Returns:
True, if there is a method that has codeareas defined using the MethodDescriptor.setCodeAreasToInstrument(LineNumberRange[]) method.