org.aopalliance.reflect.Code Maven / Gradle / Ivy
package org.aopalliance.reflect;
/**
* This represents a piece of code in the program.
*
* It is formed of a set of instructions and can be implemented at
* bytecode or source-code level.
*
*
Typically, a code in the program comes from method bodies (it
* can be init methods (instance or static) or regular methods
* (instance or static) with any kind of visibility modifiers (public,
* protected, private).
*
*
So, this class allows the client to retrieve code locators on
* instructions within this code. This locators shall be used
* conjointly whith an {@link org.aopalliance.instrument.Instrumentor}
* implementation in order to perform aspetual transformations of the
* program (before/after/around type).
*
*
The {@link #getLocator} method returns the locator for the whole
* method and can be used to implement callee-side transformations
* before/after/around the callee method.
*
*
The other set of locating methods returns locators that allows
* the client to implement caller-side transformations (e.g. when the
* code accesses a field or calls a method).
*
* @see org.aopalliance.instrument.Instrumentor
* @see CodeLocator
* @see Method#getBody() */
public interface Code {
/**
* Returns the code locator that corresponds to this code.
*
*
For instance, if a code is a set of instructions called
* code, then the locator will designate
* <code>.
*
*
This locator is typically used to locate a whole method body.
*
* @see Method#getBody() */
CodeLocator getLocator();
/**
* Returns a call locator for the given callee method.
*
*
For instance, a call locator for method m()
* designates the parts between <> in the
* following code.
*
*
* [...]
* aLocalVariable.<m()>;
* [...]
* aMethodParameter.<m()>;
* [...]
* aField.<m()>;
* [...]
* <m()> // when m is a method of the class the current code belongs to
* [...]
*
*
* If the given method is a static method, the locator follows
* the same principles, as for constructors. For instance if the
* current method is the init method of class
* C:
*
*
* [...]
* aVar = <new C()>;
* [...]
*
*
* @param calleeMethod the method that is called from the current
* code */
CodeLocator getCallLocator(Method calleeMethod);
/**
* Returns a field reading locator in the current body.
*
* For instance, a field read locator for field f
* designates the parts between <> in the
* following code.
*
*
* [...]
* <f>.m();
* [...]
* aVarOrFieldOrParam = <f>;
* [...]
*
*
* @param readField the field that is read from the current code */
CodeLocator getReadLocator(Field readField);
/**
* Returns a field writing locator in the current body.
*
* For instance, a field write locator for field f
* designates the parts between <> in the
* following code.
*
*
* [...]
* <f=> aVarOrFieldOrParam;
* [...]
*
*
* @param writtenField the field that is written from the current
* code */
CodeLocator getWriteLocator(Field writtenField);
/**
* Returns a exception throwing locator in the current body.
*
* For instance, an exception throw locator for exception of
* type E designates the parts between
* <> in the following code.
*
*
* [...]
* <throw> new E();
* [...]
* throw new AnotherExceptionType();
* [...]
*
*
* @param exceptionType the type of the throwed exception */
CodeLocator getThrowLocator(Class exceptionType);
/**
* Returns a exception catching locator in the current body.
*
* For instance, an exception catch locator for exception of
* type E designates the parts between
* <> in the following code.
*
*
* [...]
* try {
* [...]
* } catch(E e1) {
* <[...]>
* } catch(AnotherExceptionType e2) { [...] };
* [...]
*
*
* @param exceptionType the type of the throwed exception */
CodeLocator getCatchLocator(Class exceptionType);
}