de.uni_hildesheim.sse.monitoring.runtime.instrumentation

Class AbstractClassTransformer

java.lang.Object

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.AbstractClassTransformer

All Implemented Interfaces:

ISemanticsCollector

Direct Known Subclasses:

MonitoringClassFileTransformer

public class AbstractClassTransformer
extends java.lang.Object
implements ISemanticsCollector

Implements the class file transformer introducing additional code for instrumentation. Note that some methods in this class require the class name to be given in in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. This is due to performance reasons for runtime instrumentation.

Since:

1.00

Version:

1.13

Author:

Holger Eichelberger

Field Summary

Fields

Modifier and Type	Field and Description
private HashMap<java.lang.String,java.lang.Boolean>	analyzeMembers Analyze the members of the individual classes.
private HashMap<java.lang.String,HashMap<java.lang.String,Monitor>>	assignments Stores the assignments.
(package private) static java.lang.String	DELEGATING_RANDOM_ACCESS_FILE The fully qualified name of the delegating random access file.
private java.lang.String[]	excludeClasses Stores classes to be excluded.
private boolean	isStatic Stores if static instrumentation should be done.
private int	mainCount Counts the number of main methods (usually only the first one is relevant).
private java.util.HashSet<java.lang.String>	registeredClasses Stores registered classes.

Constructor Summary

Constructors

Constructor and Description
AbstractClassTransformer(boolean isStatic) Creates a new monitoring class file transformer.

Method Summary

Modifier and Type	Method and Description
private boolean	analyzeMembers(java.lang.String clName, de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl) Returns whether the members of a class shall be analyzed.
void	assignSemantics(java.lang.String cls, java.lang.String methodSignature, Monitor semantics) Assigns the monitoring semantics for the method methodName in class cls.
void	deleteSemantics(java.lang.String cls) Removes the assigned semantics for cls.
private boolean	doFirstMain(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cls, de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior, Monitor mGroupClass, TransformationType type) Processes the first main method which occurs during instrumentation of a program.
private boolean	doMethod(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior, Monitor mGroupClass, boolean inherited, TransformationType type, MethodEditor editor) Processes a method of a regular class (system under measurement).
protected static <T extends java.lang.annotation.Annotation> T	getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior member, java.lang.Class<T> annotation, AnnotationSearchType search) Returns the annotation of the specified annotation type if it is defined for member.
private static <T extends java.lang.annotation.Annotation> T	getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior member, de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass searchIn, java.lang.Class<T> annotation, AnnotationSearchType search, boolean topCall) Returns the annotation of the specified annotation type if it is defined for member.
protected static <T extends java.lang.annotation.Annotation> T	getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cls, java.lang.Class<T> annotation, AnnotationSearchType search) Returns the annotation of the specified annotation type if it is defined for cls.
protected static <T extends java.lang.annotation.Annotation> T	getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IField member, java.lang.Class<T> annotation, AnnotationSearchType search) Returns the annotation of the specified annotation type if it is defined for member.
private static Monitor	getMonitorAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl) Returns the Monitor annotation for cl.
protected boolean	handleMethodInstrumentationException(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException exception) Is called to handle an instrumentation which occurred during instrumenting a method.
private boolean	instrumentNotifyTimer(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior, Timer notifyTimer) Performs the instrumentation for the timer notification.
private boolean	instrumentThreadRun(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl, TransformationType type) Instruments the run method of a thread.
static java.lang.String	internalVmFqnToJavaFqn(java.lang.String vmFqn) Converts a given fully qualified class name in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification (slash separated) to a Java fully qualified name (dot separated).
private boolean	isRandomAccessFile(java.lang.String className) Returns if the given class name denotes the random access file.
private boolean	isRecorderClass(java.lang.String className) Returns if the given class name denotes a recorder class.
private boolean	isSocketInputStream(java.lang.String className) Returns if the given class name denotes the socket input stream.
private boolean	isSocketOutputStream(java.lang.String className) Returns if the given class name denotes the socket output stream.
static java.lang.String	javaFqnToInternalVmFqnTo(java.lang.String fqn) Converts a given Java fully qualified class name (dot separated) to the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification (slash separated).
private boolean	processNotifications(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior, Monitor mGroup, de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.ICodeModifier modifier) Processes value notifications on the given method.
protected static <T extends java.lang.annotation.Annotation> boolean	pruneAnnotation(java.lang.Class<T> annotation) Returns whether the specified annotation may be pruned, i.e. removed from resulting bytecode.
private boolean	registerRecorderId(Monitor mGroup, de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl) Registers a monitoring element (class or method) for monitoring.
protected void	retransformAssigned(java.lang.String[] classNames) Retransforms the specified classes.
boolean	shouldInstrument(java.lang.String className) Returns if the class given by its class name should be instrumented.
boolean	transform(java.lang.String name, de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl, TransformationType type) Processes a class of the system under monitoring.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DELEGATING_RANDOM_ACCESS_FILE

static final java.lang.String DELEGATING_RANDOM_ACCESS_FILE

The fully qualified name of the delegating random access file. Do not refer this class directly because otherwise it is loaded before self-instrumentation.

isStatic

private boolean isStatic

Stores if static instrumentation should be done.

registeredClasses

private java.util.HashSet<java.lang.String> registeredClasses

Stores registered classes.

mainCount

private int mainCount

Counts the number of main methods (usually only the first one is relevant).

excludeClasses

private java.lang.String[] excludeClasses

Stores classes to be excluded.

Since:

1.13

analyzeMembers

private HashMap<java.lang.String,java.lang.Boolean> analyzeMembers

Analyze the members of the individual classes.

Since:

1.13

assignments

private final HashMap<java.lang.String,HashMap<java.lang.String,Monitor>> assignments

Stores the assignments.

Constructor Detail

AbstractClassTransformer

public AbstractClassTransformer(boolean isStatic)

Creates a new monitoring class file transformer.

Parameters:

isStatic - denotes if static instrumentation should be done or dynamic

Since:

1.00

Method Detail

isRandomAccessFile

private final boolean isRandomAccessFile(java.lang.String className)

Returns if the given class name denotes the random access file.

Parameters:

className - the class name to be tested given in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".

Returns:

false if it is not the random access file, true else

Since:

1.00

isSocketInputStream

private final boolean isSocketInputStream(java.lang.String className)

Returns if the given class name denotes the socket input stream.

Parameters:

className - the class name to be tested given in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".

Returns:

false if it is not the socket input stream, true else

Since:

1.00

isSocketOutputStream

private final boolean isSocketOutputStream(java.lang.String className)

Returns if the given class name denotes the socket output stream.

Parameters:

className - the class name to be tested given in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".

Returns:

false if it is not the socket output stream, true else

Since:

1.00

isRecorderClass

private final boolean isRecorderClass(java.lang.String className)

Returns if the given class name denotes a recorder class.

Parameters:

className - the class name to be tested given in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".

Returns:

false if it is not a recorder class, true else

Since:

1.00

internalVmFqnToJavaFqn

public static final java.lang.String internalVmFqnToJavaFqn(java.lang.String vmFqn)

Converts a given fully qualified class name in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification (slash separated) to a Java fully qualified name (dot separated).

Parameters:

vmFqn - the fully qualified name according to the Java Virtual Machine Specification

Returns:

the Java typical name

Since:

1.00

javaFqnToInternalVmFqnTo

public static final java.lang.String javaFqnToInternalVmFqnTo(java.lang.String fqn)

Converts a given Java fully qualified class name (dot separated) to the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification (slash separated).

Parameters:

fqn - the fully qualified Java name

Returns:

the fully qualified name according to the Java Virtual Machine Specification

Since:

1.00

shouldInstrument

public final boolean shouldInstrument(java.lang.String className)

Returns if the class given by its class name should be instrumented.

Parameters:

className - the name of the class to be checked given in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".

Returns:

true if the class should be instrumented, false else

Since:

1.00

getMonitorAnnotation

private static final Monitor getMonitorAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl)
                                           throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Returns the Monitor annotation for cl. This method considers whether cl or its (outer) declaring class has a Monitor annotation and returns it or stops at a ExcludeFromMonitoring annotation.

Parameters:

cl - the class to be queried for the annotation

Returns:

the related annotation or null in case that none was found or the class is explicitly excluded from monitoring.

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case that some class cannot be found

Since:

1.00

analyzeMembers

private boolean analyzeMembers(java.lang.String clName,
                               de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl)
                        throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Returns whether the members of a class shall be analyzed. Prerequisite is that analyzeMembers is not null.

Parameters:

clName - the class name

cl - the class itself for further inspection

Returns:

true if the

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case of problems with the bytecode

Since:

1.00

transform

public final boolean transform(java.lang.String name,
                               de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl,
                               TransformationType type)
                        throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Processes a class of the system under monitoring.

Parameters:

name - the name of the class given in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".

cl - the class

type - the type of the transformation

Returns:

true if the class was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case that any error occurs while processing bytecode

Since:

1.00

retransformAssigned

protected void retransformAssigned(java.lang.String[] classNames)

Retransforms the specified classes.

Parameters:

classNames - the class names

Since:

1.00

instrumentThreadRun

private final boolean instrumentThreadRun(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl,
                                          TransformationType type)
                                   throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Instruments the run method of a thread. This method is called only if JMX is not supported, e.g. on Android.

Parameters:

cl - the class to analyze

type - the type of the transformation

Returns:

true if the class was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case that the new code cannot be compiled

Since:

1.00

registerRecorderId

private final boolean registerRecorderId(Monitor mGroup,
                                         de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cl)
                                  throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Registers a monitoring element (class or method) for monitoring.

Parameters:

mGroup - the monitoring annotation

cl - the containing class

Returns:

true if the class was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case of any byte code error

Since:

1.00

pruneAnnotation

protected static final <T extends java.lang.annotation.Annotation> boolean pruneAnnotation(java.lang.Class<T> annotation)

Returns whether the specified annotation may be pruned, i.e. removed from resulting bytecode. The results depends on the current configuration and the concrete type of the annotation, i.e. no pruning happens, if pruning is disabled by default. If pruning is enabled, it is enabled for all annotations except of the Instrumented annotation, which is enabled only in case of dynamic instrumentation (for staged static instrumentations).

Type Parameters:

T - the type of the annotation

Parameters:

annotation - the type of the annotation (meta class)

Returns:

true if the given annotation (type) may be pruned, false else

Since:

1.00

getAnnotation

protected static final <T extends java.lang.annotation.Annotation> T getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IField member,
                                                                                   java.lang.Class<T> annotation,
                                                                                   AnnotationSearchType search)

Returns the annotation of the specified annotation type if it is defined for member.

Type Parameters:

T - the type of the annotation

Parameters:

member - the member to be considered for querying the annotation

annotation - the type of the annotation to be searched for (meta class)

search - the annotation search type

Returns:

the instance of the annotation if it is defined on method, null otherwise

Since:

1.00

getAnnotation

protected static final <T extends java.lang.annotation.Annotation> T getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior member,
                                                                                   java.lang.Class<T> annotation,
                                                                                   AnnotationSearchType search)

Returns the annotation of the specified annotation type if it is defined for member.

Type Parameters:

T - the type of the annotation

Parameters:

member - the member to be considered for querying the annotation

annotation - the type of the annotation to be searched for (meta class)

search - the annotation search type

Returns:

the instance of the annotation if it is defined on method, null otherwise

Since:

1.00

getAnnotation

private static final <T extends java.lang.annotation.Annotation> T getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior member,
                                                                                 de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass searchIn,
                                                                                 java.lang.Class<T> annotation,
                                                                                 AnnotationSearchType search,
                                                                                 boolean topCall)

Returns the annotation of the specified annotation type if it is defined for member.

Type Parameters:

T - the type of the annotation

Parameters:

member - the member to be considered for querying the annotation

searchIn - the class / interface to search in

annotation - the type of the annotation to be searched for (meta class)

search - the annotation search type

topCall - is this method called from the top of the current recursion or from within

Returns:

the instance of the annotation if it is defined on method, null otherwise

Since:

1.00

getAnnotation

protected static final <T extends java.lang.annotation.Annotation> T getAnnotation(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cls,
                                                                                   java.lang.Class<T> annotation,
                                                                                   AnnotationSearchType search)

Returns the annotation of the specified annotation type if it is defined for cls.

Type Parameters:

T - the type of the annotation

Parameters:

cls - the class to be considered for querying the annotation

annotation - the type of the annotation to be searched for (meta class)

search - the annotation search type

Returns:

the instance of the annotation if it is defined on method, null otherwise

Since:

1.00

doFirstMain

private final boolean doFirstMain(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IClass cls,
                                  de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior,
                                  Monitor mGroupClass,
                                  TransformationType type)
                           throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Processes the first main method which occurs during instrumentation of a program.

Parameters:

cls - the class

behavior - the behavior to be modified

mGroupClass - the annotation on class level as cause for instrumenting this method (may be null)

type - the type of the transformation

Returns:

true if the class was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case that the code added by instrumentation does not compile

Since:

1.00

doMethod

private final boolean doMethod(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior,
                               Monitor mGroupClass,
                               boolean inherited,
                               TransformationType type,
                               MethodEditor editor)
                        throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Processes a method of a regular class (system under measurement).

Parameters:

behavior - the behavior to be modified

mGroupClass - the annotation on class level as cause for instrumenting this method (may be null)

inherited - whether mGroupClass is inherited

type - the type of the transformation

editor - the editor for modifications

Returns:

true if the behavior was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case that the code added by instrumentation does not compile

Since:

1.00

processNotifications

private boolean processNotifications(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior,
                                     Monitor mGroup,
                                     de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.ICodeModifier modifier)
                              throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Processes value notifications on the given method.

Parameters:

behavior - the method to be changed

mGroup - the annotation which indicated recording (may be null)

modifier - the code modifier to be used

Returns:

true if the behavior was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - if any instrumented code is not valid

Since:

1.00

instrumentNotifyTimer

private boolean instrumentNotifyTimer(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.IBehavior behavior,
                                      Timer notifyTimer)
                               throws de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException

Performs the instrumentation for the timer notification. This method determines the point within the method / constructor to affect existing code at, constructs the call to the recorder and inserts the call accordingly.

Parameters:

behavior - the method / constructor being processed

notifyTimer - the timer annotation appended to behaviorInfo

Returns:

true if the behavior was modified, false else

Throws:

de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException - in case that new code cannot be compiled

Since:

1.00

handleMethodInstrumentationException

protected boolean handleMethodInstrumentationException(de.uni_hildesheim.sse.monitoring.runtime.instrumentation.lib.InstrumenterException exception)

Is called to handle an instrumentation which occurred during instrumenting a method. By default, this method does not handle this exception and causes throwing for further handling

Parameters:

exception - the exception occurred

Returns:

true if the exception was handled and instrumentation can continue with the next method, false if the exception should be thrown by the caller for further handling

Since:

1.00

assignSemantics

public void assignSemantics(java.lang.String cls,
                            java.lang.String methodSignature,
                            Monitor semantics)

Assigns the monitoring semantics for the method methodName in class cls.

Specified by:

assignSemantics in interface ISemanticsCollector

Parameters:

cls - the name of the class the monitoring semantics is defined for

methodSignature - the name of the method to assign the semantics to

semantics - the monitoring semantics

Since:

1.00

deleteSemantics

public void deleteSemantics(java.lang.String cls)

Removes the assigned semantics for cls.

Parameters:

cls - the name of the class the monitoring semantics shall be removed for

Since:

1.00