org.aopalliance.instrument

Interface Instrumentor

public interface Instrumentor

This interface defines all the methods that perform program instrumentations that are useful for AOP.

The modifications definitions rely on an abstract representation of locators, as defined in the org.aopalliance.reflect package.

See Also:

Locator, ClassLocator, CodeLocator

Method Summary

Modifier and Type	Method and Description
Instrumentation	addAfterCode(CodeLocator location, Code afterCode, Instrumentation before, Instrumentation after) Adds some code after a given method code body.
Instrumentation	addAroundCode(CodeLocator location, Code aroundCode, String proceedMethodName, Instrumentation before, Instrumentation after) Adds some code around a given method code body.
Instrumentation	addBeforeCode(CodeLocator location, Code beforeCode, Instrumentation before, Instrumentation after) Adds some code before a given method code body.
Instrumentation	addClass(ClassLocator location, String className) Introduces a class into the class location (mixin).
Instrumentation	addField(ClassLocator location, String name, String typeName, Code initializator) Adds a new field to the target class.
Instrumentation	addInterface(ClassLocator location, String newInterfaceName) Adds a new implemented interface to a given class location.
Instrumentation	addMethod(ClassLocator location, String name, String[] parameterTypeNames, String[] parameterNames, Code body) Adds a new method to the class location.
ClassLocator	createClass(String name) Creates a new class.
Instrumentation	setSuperClass(ClassLocator location, String newSuperClassName) Sets or replaces the current superclass of a class location.
void	undo(Instrumentation instrumentation) Cancels an instrumentation.

Method Detail

createClass

ClassLocator createClass(String name)
                  throws InstrumentationError

Creates a new class.

Returns:

the locator that corresponds to the newly created class

Throws:

InstrumentationError

addInterface

Instrumentation addInterface(ClassLocator location,
                             String newInterfaceName)
                      throws InstrumentationError

Adds a new implemented interface to a given class location.

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

setSuperClass

Instrumentation setSuperClass(ClassLocator location,
                              String newSuperClassName)
                       throws InstrumentationError

Sets or replaces the current superclass of a class location.

The new superclass should be a subtype of the replaced one in order to maintain backward compatibility.

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

addClass

Instrumentation addClass(ClassLocator location,
                         String className)
                  throws InstrumentationError

Introduces a class into the class location (mixin).

Similarely to a mixin, the whole set of fields and methods are introduced into the location's class, all the implemented interface of the introduced class are also added as interfaces of the location's class.

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

addMethod

Instrumentation addMethod(ClassLocator location,
                          String name,
                          String[] parameterTypeNames,
                          String[] parameterNames,
                          Code body)
                   throws InstrumentationError

Adds a new method to the class location.

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

addField

Instrumentation addField(ClassLocator location,
                         String name,
                         String typeName,
                         Code initializator)
                  throws InstrumentationError

Adds a new field to the target class.

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

addBeforeCode

Instrumentation addBeforeCode(CodeLocator location,
                              Code beforeCode,
                              Instrumentation before,
                              Instrumentation after)
                       throws InstrumentationError

Adds some code before a given method code body.

Parameters:

location - the modification locator that can represent a method invocation, a field set/get, or a constructor (at callee or caller side)

beforeCode - the code to be added before

before - the modification that must stay before this before code

after - the modification that must stay after this before code

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

addAfterCode

Instrumentation addAfterCode(CodeLocator location,
                             Code afterCode,
                             Instrumentation before,
                             Instrumentation after)
                      throws InstrumentationError

Adds some code after a given method code body.

Parameters:

location - the modification locator that can represent a method invocation, a field set/get, or a constructor (at callee or caller side)

afterCode - the code to be added after

before - the modification that must stay before this after code

after - the modification that must stay after this after code

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

addAroundCode

Instrumentation addAroundCode(CodeLocator location,
                              Code aroundCode,
                              String proceedMethodName,
                              Instrumentation before,
                              Instrumentation after)
                       throws InstrumentationError

Adds some code around a given method code body.

An around code is a code that calls a proceed method one or several times. When the proceed method is invoked, the location is executed (for compile approched, the proceed method call is subsituted by the location).

The proceed method name is parameterized by the proceedMethodName argument (can be proceed, invokeNext, runNext, etc).

Note that if the around code does not call the proceed method, then the around instrumentation is similar to a replacement of the location. This is not aspect-safe but can be useful in some instrumentation process to build AO systems.

Parameters:

location - the modification locator that can represent a method invocation, a field set/get, or a constructor (at callee or caller side)

aroundCode - the code to be added after

proceedMethodName - the name of the proceed method

before - the modification that must stay before this after code

after - the modification that must stay after this after code

Returns:

the object that corresponds to this instrumentation

Throws:

InstrumentationError - if something went wrong with this instrumentation

See Also:

undo(Instrumentation)

undo

void undo(Instrumentation instrumentation)
   throws UndoNotSupportedException

Cancels an instrumentation.

Parameters:

instrumentation - the instrumentation to cancel

Throws:

UndoNotSupportedException - when the implementation does not support instrumentation cancellation for the given instrumentation