de.uka.ipd.sdq.beagle.measurement.kieker.instrumentation

Class EclipseAstInstrumentor

java.lang.Object

de.uka.ipd.sdq.beagle.measurement.kieker.instrumentation.EclipseAstInstrumentor

public class EclipseAstInstrumentor
extends Object

Instruments code sections using Eclipse’s JDT Abstract Syntax Tree. The instrumentor is configured through instrumentation strategies, providing the statements that shall be inserted.

Instrumentation takes place on a best effort base. It is performed as follows:

• The instrumentor queries the instrumentation strategy reported through useStrategy(de.uka.ipd.sdq.beagle.measurement.kieker.instrumentation.EclipseAstInstrumentationStrategy, java.util.Collection<de.uka.ipd.sdq.beagle.core.CodeSection>) for instrumentation instructions to instrument the code sections provided through the same method call.
• start instrumentation instructions will be placed before the instrumented code section. There are no guarantees for the number of statements executed between the instrumentation instruction and the instrumented code section. However, the instrumentor tries to keep this number as small as possible.
• end instrumentation instructions will be placed after the instrumented code section. There are no guarantees for the number of statements executed between the instrumented code section and the instrumentation instruction. However, the instrumentor tries to keep this number as small as possible.
• After successful instrumentation, the instrumentor queries the EclipseAstInstrumentor.InstrumentationResultFileProvider for each compilation unit it manipulated to get a file to write the result to. It then writes the instrumented source code to that file.
• The instrumentor will report failures through the Failure API. It will report failures in batches instead for every file. Such failures may be:
  • Input/Output errors while trying to read a source file.
  • Input/Output errors while trying to write to an output file.
  • The input source file doesn’t define a Java type.

The result of the instrumentation is undefiend for a source file referenced by a code section that is not a valid Java file defining a class.

The instrumentation is executed using multible threads. However, the class itself is not thread safe and may thus not be called from multible threads.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	EclipseAstInstrumentor.InstrumentationResultFileProvider Appoints a file the instrumented source code of a Java type shall be written to.

Constructor Summary

Constructors

Constructor and Description
EclipseAstInstrumentor(EclipseAstInstrumentor.InstrumentationResultFileProvider instrumentedFileProvider) Creates an instrumentor that writes its resulting instrumented code to the files provided by instrumentedFileProvider.

Method Summary

Modifier and Type	Method and Description
void	instrument() Executes the instrumentation based on the settings set on this instrumentor.
EclipseAstInstrumentor	useCharset(Charset ioCharset) Makes the instrumentor use charset to read and write source code.
EclipseAstInstrumentor	useStrategy(EclipseAstInstrumentationStrategy instrumentationStrategy, CodeSection... codeSections) Makes this instrumentor use the provided strategy to instrument the provided code sections.
EclipseAstInstrumentor	useStrategy(EclipseAstInstrumentationStrategy instrumentationStrategy, Collection<CodeSection> codeSections) Makes this instrumentor use the provided strategy to instrument the provided code sections.

Methods inherited from class java.lang.Object

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

Constructor Detail

EclipseAstInstrumentor

public EclipseAstInstrumentor(EclipseAstInstrumentor.InstrumentationResultFileProvider instrumentedFileProvider)

Creates an instrumentor that writes its resulting instrumented code to the files provided by instrumentedFileProvider.

Parameters:

instrumentedFileProvider - A function taking a fully qualified path of a Java type and returning a file to write the instrumented code of this type to. Must not be null.

Method Detail

useStrategy

public EclipseAstInstrumentor useStrategy(EclipseAstInstrumentationStrategy instrumentationStrategy,
                                          Collection<CodeSection> codeSections)

Makes this instrumentor use the provided strategy to instrument the provided code sections.

Parameters:

instrumentationStrategy - The strategy to instrument with.

codeSections - The sections that shall be instrumented using the provided strategy.

Returns:

this.

useStrategy

public EclipseAstInstrumentor useStrategy(EclipseAstInstrumentationStrategy instrumentationStrategy,
                                          CodeSection... codeSections)

Makes this instrumentor use the provided strategy to instrument the provided code sections.

Parameters:

instrumentationStrategy - The strategy to instrument with.

codeSections - The sections that shall be instrumented using the provided strategy.

Returns:

this.

useCharset

public EclipseAstInstrumentor useCharset(Charset ioCharset)

Makes the instrumentor use charset to read and write source code. It defaults to using Charset.defaultCharset() if no charset was set.

Parameters:

ioCharset - The charset to be used by this Instrumentor for input and output.

Returns:

this.

instrument

public void instrument()

Executes the instrumentation based on the settings set on this instrumentor.