This package provides the most generic and common interfaces for AOP.
libaopalliance-java-20070526/src/main/org/aopalliance/instrument/ 0000755 0001750 0001750 00000000000 10626104376 024564 5 ustar twerner twerner libaopalliance-java-20070526/src/main/org/aopalliance/instrument/Instrumentation.java 0000644 0001750 0001750 00000002100 07676272772 030644 0 ustar twerner twerner package org.aopalliance.instrument; import org.aopalliance.reflect.Locator; /** * This interface represents an instrumentation on the base program. * *The program instrumentor implementation should return an * intrumentation instance for each intrumentation which is performed. * * @see Instrumentor */ public interface Instrumentation { /** Interface adding instrumentation type. */ int ADD_INTERFACE=0; /** Superclass setting instrumentation type. */ int SET_SUPERCLASS=1; /** Class adding instrumentation type. */ int ADD_CLASS=2; /** Before code instrumentation type. */ int ADD_BEFORE_CODE=3; /** After code adding instrumentation type. */ int ADD_AFTER_CODE=4; /** Metadata adding instrumentation type. */ int ADD_METADATA=5; /** * Returns the location of this instrumentation. */ Locator getLocation(); /** * Gets the instrumentation type. * * @return ADD_INTERFACE | SET_SUPERCLASS | ADD_CLASS | * ADD_AFTER_CODE | ADD_BEFORE_CODE | ADD_AROUND_CODE | * ADD_METADATA */ int getType(); } libaopalliance-java-20070526/src/main/org/aopalliance/instrument/InstrumentationError.java 0000644 0001750 0001750 00000000724 07700063407 031645 0 ustar twerner twerner package org.aopalliance.instrument; /** * The error that is raised when an error occurs during an instrumentation. * * @see Instrumentor */ public class InstrumentationError extends Error { /** * Sets a generic error message for an instrumentation error. */ public InstrumentationError(Instrumentation instrumentation, Throwable cause) { super("Error while instrumenting " + instrumentation,cause); } } libaopalliance-java-20070526/src/main/org/aopalliance/instrument/Instrumentor.java 0000644 0001750 0001750 00000016241 07700063322 030136 0 ustar twerner twerner package org.aopalliance.instrument; import org.aopalliance.reflect.Code; import org.aopalliance.reflect.Class; import org.aopalliance.reflect.CodeLocator; import org.aopalliance.reflect.ClassLocator; import org.aopalliance.reflect.UnitLocator; /** * 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 {@link org.aopalliance.reflect} * package. * * @see org.aopalliance.reflect.Locator * @see org.aopalliance.reflect.ClassLocator * @see org.aopalliance.reflect.CodeLocator */ public interface Instrumentor { /** * Creates a new class. * * @return the locator that corresponds to the newly created class */ ClassLocator createClass(String name) throws InstrumentationError; /** * Adds a new implemented interface to a given class location. * * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addInterface(ClassLocator location, String newInterfaceName) 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. * * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation setSuperClass(ClassLocator location, String newSuperClassName) 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. * * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addClass(ClassLocator location,String className) throws InstrumentationError; /** * Adds a new method to the class location. * * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addMethod(ClassLocator location, String name, String[] parameterTypeNames, String[] parameterNames, Code body) throws InstrumentationError; /** * Adds a new field to the target class. * * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addField(ClassLocator location, String name, String typeName, Code initializator) throws InstrumentationError; /** * Adds some code before a given method code body. * * @param location the modification locator that can represent a * method invocation, a field set/get, or a constructor (at callee * or caller side) * @param beforeCode the code to be added before * @param before the modification that must stay before this * before code * @param after the modification that must stay after this * before code * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addBeforeCode(CodeLocator location, Code beforeCode, Instrumentation before, Instrumentation after) throws InstrumentationError; /** * Adds some code after a given method code body. * * @param location the modification locator that can represent a * method invocation, a field set/get, or a constructor (at callee * or caller side) * @param afterCode the code to be added after * @param before the modification that must stay before this * after code * @param after the modification that must stay after this * after code * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addAfterCode(CodeLocator location, Code afterCode, 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. * * @param location the modification locator that can represent a * method invocation, a field set/get, or a constructor (at callee * or caller side) * @param aroundCode the code to be added after * @param proceedMethodName the name of the proceed method * @param before the modification that must stay before this * after code * @param after the modification that must stay after this * after code * @return the object that corresponds to this instrumentation * @throws InstrumentationError if something went wrong with this * instrumentation * @see #undo(Instrumentation) */ Instrumentation addAroundCode(CodeLocator location, Code aroundCode, String proceedMethodName, Instrumentation before, Instrumentation after) throws InstrumentationError; /** * Cancels an instrumentation. * * @param instrumentation the instrumentation to cancel * * @throws UndoNotSupportedException when the implementation does * not support instrumentation cancellation for the given * instrumentation */ void undo(Instrumentation instrumentation) throws UndoNotSupportedException; } libaopalliance-java-20070526/src/main/org/aopalliance/instrument/UndoNotSupportedException.java 0000644 0001750 0001750 00000001135 07700063407 032600 0 ustar twerner twerner package org.aopalliance.instrument; /** * The exception that is raised when the client program tries to undo * an instrumentation and when current implementation does not support * it. * *
Undoing is implemented by the {@link * Instrumentor#undo(Instrumentation)} method. * * @see Instrumentor */ public class UndoNotSupportedException extends Exception { /** * Sets a generic exception message for an instrumentation. */ public UndoNotSupportedException(Instrumentation instrumentation) { super("Undo not supported for instrumentation: " + instrumentation); } } libaopalliance-java-20070526/src/main/org/aopalliance/instrument/package.html 0000644 0001750 0001750 00000003436 07676272773 027075 0 ustar twerner twerner
This package provides an API for program instrumentation.
This package provides a set of interfaces for applying intrumentations on a program, i.e. a program modification which adds some feature (methods, classes, code) to the original program. These instrumentations are abstractly defined and can occur at compile-time, load-time, or runtime depending on the {@link org.aopalliance.instrument.Instrumentor} implementation. Moreover, since it uses the {@link org.aopalliance.reflect} package which provides an abstract representation of the program, the instrumentations can be implemented at a source-code level or at a bytecode level, depending on the implementation.
This API is specific to AOP. This means that the set of program instrumentations that is allowed is a restricted set compared to a general-purpose API. However, general-purpose transformation tools should provide an implementation of this API in order to be easily used by several AO systems.
This package requires the {@link org.aopalliance.reflect} package. libaopalliance-java-20070526/src/main/org/aopalliance/intercept/ 0000755 0001750 0001750 00000000000 10626104376 024351 5 ustar twerner twerner libaopalliance-java-20070526/src/main/org/aopalliance/intercept/ConstructorInterceptor.java 0000644 0001750 0001750 00000002562 07700064476 031772 0 ustar twerner twerner package org.aopalliance.intercept; /** * Intercepts the construction of a new object. * *
The user should implement the {@link * #construct(ConstructorInvocation)} method to modify the original * behavior. E.g. the following class implements a singleton * interceptor (allows only one unique instance for the intercepted * class): * *
* class DebuggingInterceptor implements ConstructorInterceptor {
* Object instance=null;
*
* Object construct(ConstructorInvocation i) throws Throwable {
* if(instance==null) {
* return instance=i.proceed();
* } else {
* throw new Exception("singleton does not allow multiple instance");
* }
* }
* }
* */
public interface ConstructorInterceptor extends Interceptor
{
/**
* Implement this method to perform extra treatments before and
* after the consrution of a new object. Polite implementations
* would certainly like to invoke {@link Joinpoint#proceed()}.
*
* @param invocation the construction joinpoint
* @return the newly created object, which is also the result of
* the call to {@link Joinpoint#proceed()}, might be replaced by
* the interceptor.
*
* @throws Throwable if the interceptors or the
* target-object throws an exception. */
Object construct(ConstructorInvocation invocation) throws Throwable;
}
libaopalliance-java-20070526/src/main/org/aopalliance/intercept/ConstructorInvocation.java 0000644 0001750 0001750 00000001213 07700064605 031567 0 ustar twerner twerner package org.aopalliance.intercept;
import java.lang.reflect.Constructor;
/**
* Description of an invocation to a constuctor, given to an
* interceptor upon construtor-call.
*
* A constructor invocation is a joinpoint and can be intercepted * by a constructor interceptor. * * @see ConstructorInterceptor */ public interface ConstructorInvocation extends Invocation { /** * Gets the constructor being called. * *
This method is a frienly implementation of the {@link * Joinpoint#getStaticPart()} method (same result). * * @return the constructor being called. */ Constructor getConstructor(); } libaopalliance-java-20070526/src/main/org/aopalliance/intercept/FieldAccess.java 0000644 0001750 0001750 00000001770 07700064655 027372 0 ustar twerner twerner package org.aopalliance.intercept; import java.lang.reflect.Field; /** * This interface represents a field access in the program. * *
A field access is a joinpoint and can be intercepted by a field * interceptor. * * @see FieldInterceptor */ public interface FieldAccess extends Joinpoint { /** The read access type (see {@link #getAccessType()}). */ int READ=0; /** The write access type (see {@link #getAccessType()}). */ int WRITE=1; /** * Gets the field being accessed. * *
This method is a frienly implementation of the {@link * Joinpoint#getStaticPart()} method (same result). * * @return the field being accessed. */ Field getField(); /** * Gets the value that must be set to the field. * *
This value can be intercepted and changed by a field * interceptor. */ Object getValueToSet(); /** * Returns the access type. * * @return FieldAccess.READ || FieldAccess.WRITE */ int getAccessType(); } libaopalliance-java-20070526/src/main/org/aopalliance/intercept/FieldInterceptor.java 0000644 0001750 0001750 00000004251 07700064476 030465 0 ustar twerner twerner package org.aopalliance.intercept; /** * Intercepts field access on a target object. * *
The user should implement the {@link #set(FieldAccess)} and * {@link #get(FieldAccess)} methods to modify the original * behavior. E.g. the following class implements a tracing interceptor * (traces the accesses to the intercepted field(s)): * *
* class TracingInterceptor implements FieldInterceptor {
*
* Object set(FieldAccess fa) throws Throwable {
* System.out.println("field "+fa.getField()+" is set with value "+
* fa.getValueToSet());
* Object ret=fa.proceed();
* System.out.println("field "+fa.getField()+" was set to value "+ret);
* return ret;
* }
*
* Object get(FieldAccess fa) throws Throwable {
* System.out.println("field "+fa.getField()+" is about to be read");
* Object ret=fa.proceed();
* System.out.println("field "+fa.getField()+" was read; value is "+ret);
* return ret;
* }
* }
* */
public interface FieldInterceptor extends Interceptor
{
/**
* Do the stuff you want to do before and after the
* field is getted.
*
* Polite implementations would certainly like to call * {@link Joinpoint#proceed()}. * * @param fieldRead the joinpoint that corresponds to the field * read * @return the result of the field read {@link * Joinpoint#proceed()}, might be intercepted by the * interceptor. * * @throws Throwable if the interceptors or the * target-object throws an exception. */ Object get(FieldAccess fieldRead) throws Throwable; /** * Do the stuff you want to do before and after the * field is setted. * *
Polite implementations would certainly like to implement * {@link Joinpoint#proceed()}. * * @param fieldWrite the joinpoint that corresponds to the field * write * @return the result of the field set {@link * Joinpoint#proceed()}, might be intercepted by the * interceptor. * * @throws Throwable if the interceptors or the * target-object throws an exception. */ Object set(FieldAccess fieldWrite) throws Throwable; } libaopalliance-java-20070526/src/main/org/aopalliance/intercept/Interceptor.java 0000644 0001750 0001750 00000002721 10026623630 027505 0 ustar twerner twerner package org.aopalliance.intercept; import org.aopalliance.aop.Advice; /** * This interface represents a generic interceptor. * *
A generic interceptor can intercept runtime events that occur * within a base program. Those events are materialized by (reified * in) joinpoints. Runtime joinpoints can be invocations, field * access, exceptions... * *
This interface is not used directly. Use the the sub-interfaces * to intercept specific events. For instance, the following class * implements some specific interceptors in order to implement a * debugger: * *
* class DebuggingInterceptor implements MethodInterceptor,
* ConstructorInterceptor, FieldInterceptor {
*
* Object invoke(MethodInvocation i) throws Throwable {
* debug(i.getMethod(), i.getThis(), i.getArgs());
* return i.proceed();
* }
*
* Object construct(ConstructorInvocation i) throws Throwable {
* debug(i.getConstructor(), i.getThis(), i.getArgs());
* return i.proceed();
* }
*
* Object get(FieldAccess fa) throws Throwable {
* debug(fa.getField(), fa.getThis(), null);
* return fa.proceed();
* }
*
* Object set(FieldAccess fa) throws Throwable {
* debug(fa.getField(), fa.getThis(), fa.getValueToSet());
* return fa.proceed();
* }
*
* void debug(AccessibleObject ao, Object this, Object value) {
* ...
* }
* }
*
*
* @see Joinpoint */
public interface Interceptor extends Advice {
}
libaopalliance-java-20070526/src/main/org/aopalliance/intercept/Invocation.java 0000644 0001750 0001750 00000000760 10026623630 027321 0 ustar twerner twerner
package org.aopalliance.intercept;
/**
* This interface represents an invocation in the program.
*
* An invocation is a joinpoint and can be intercepted by an * interceptor. * * @author Rod Johnson */ public interface Invocation extends Joinpoint { /** * Get the arguments as an array object. * It is possible to change element values within this * array to change the arguments. * * @return the argument of the invocation */ Object[] getArguments(); } libaopalliance-java-20070526/src/main/org/aopalliance/intercept/Joinpoint.java 0000644 0001750 0001750 00000003252 07700063631 027164 0 ustar twerner twerner package org.aopalliance.intercept; import java.lang.reflect.AccessibleObject; /** * This interface represents a generic runtime joinpoint (in the AOP * terminology). * *
A runtime joinpoint is an event that occurs on a static * joinpoint (i.e. a location in a the program). For instance, an * invocation is the runtime joinpoint on a method (static joinpoint). * The static part of a given joinpoint can be generically retrieved * using the {@link #getStaticPart()} method. * *
In the context of an interception framework, a runtime joinpoint * is then the reification of an access to an accessible object (a * method, a constructor, a field), i.e. the static part of the * joinpoint. It is passed to the interceptors that are installed on * the static joinpoint. * * @see Interceptor */ public interface Joinpoint { /** * Proceeds to the next interceptor in the chain. * *
The implementation and the semantics of this method depends * on the actual joinpoint type (see the children interfaces). * * @return see the children interfaces' proceed definition. * * @throws Throwable if the joinpoint throws an exception. */ Object proceed() throws Throwable; /** * Returns the object that holds the current joinpoint's static * part. * *
For instance, the target object for an invocation. * * @return the object (can be null if the accessible object is * static). */ Object getThis(); /** * Returns the static part of this joinpoint. * *
The static part is an accessible object on which a chain of * interceptors are installed. */ AccessibleObject getStaticPart(); } libaopalliance-java-20070526/src/main/org/aopalliance/intercept/MethodInterceptor.java 0000644 0001750 0001750 00000002611 10026623630 030644 0 ustar twerner twerner package org.aopalliance.intercept; /** * Intercepts calls on an interface on its way to the target. These * are nested "on top" of the target. * *
The user should implement the {@link #invoke(MethodInvocation)} * method to modify the original behavior. E.g. the following class * implements a tracing interceptor (traces all the calls on the * intercepted method(s)): * *
* class TracingInterceptor implements MethodInterceptor {
* Object invoke(MethodInvocation i) throws Throwable {
* System.out.println("method "+i.getMethod()+" is called on "+
* i.getThis()+" with args "+i.getArguments());
* Object ret=i.proceed();
* System.out.println("method "+i.getMethod()+" returns "+ret);
* return ret;
* }
* }
* */
public interface MethodInterceptor extends Interceptor {
/**
* Implement this method to perform extra treatments before and
* after the invocation. Polite implementations would certainly
* like to invoke {@link Joinpoint#proceed()}.
*
* @param invocation the method invocation joinpoint
* @return the result of the call to {@link
* Joinpoint#proceed()}, might be intercepted by the
* interceptor.
*
* @throws Throwable if the interceptors or the
* target-object throws an exception. */
Object invoke(MethodInvocation invocation) throws Throwable;
}
libaopalliance-java-20070526/src/main/org/aopalliance/intercept/MethodInvocation.java 0000644 0001750 0001750 00000001132 07700063532 030460 0 ustar twerner twerner package org.aopalliance.intercept;
import java.lang.reflect.Method;
/**
* Description of an invocation to a method, given to an interceptor
* upon method-call.
*
* A method invocation is a joinpoint and can be intercepted by a method * interceptor. * * @see MethodInterceptor */ public interface MethodInvocation extends Invocation { /** * Gets the method being called. * *
This method is a frienly implementation of the {@link * Joinpoint#getStaticPart()} method (same result). * * @return the method being called. */ Method getMethod(); } libaopalliance-java-20070526/src/main/org/aopalliance/intercept/package.html 0000644 0001750 0001750 00000002371 07676272773 026657 0 ustar twerner twerner
This package provides a set of interfaces for interception mechanisms.
Interception is a basic mechanism to implement AOP. This is widely used in middlewares and modern application servers, including J2EE ones.
This package provides an {@link org.aopalliance.intercept.Interceptor} interface that will intercept different runtime joinpoints (e.g. method calls, field access, ...). Thus, interceptors are able to add some behavior around the joinpoints actual executions. Several interceptors can be applied on a given joinpoint since they are chained. The AO system implementor should provide means to install and order these chains of interceptors. libaopalliance-java-20070526/src/main/org/aopalliance/reflect/ 0000755 0001750 0001750 00000000000 10626104376 024000 5 ustar twerner twerner libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Class.java 0000644 0001750 0001750 00000002172 07676272773 025734 0 ustar twerner twerner package org.aopalliance.reflect; /** * This element represents classes in the base program. */ public interface Class extends ProgramUnit { /** * Returns the class locator that corresponds to this class. * *
This method returns exactly the same result as
* ProgramUnit.getLocator() but with a more precise
* type (ClassLocator instead of
* UnitLocator).
*
* @see ProgramUnit#getLocator() */
ClassLocator getClassLocator();
/**
* Gets the class's full name. */
String getName();
/**
* Gets the fields of this class (including superclass fields). */
Field[] getFields();
/**
* Gets the fields declared by this class. */
Field[] getDeclaredFields();
/**
* Gets the methods of this class (including superclass
* methods). */
Method[] getMethods();
/**
* Gets the methods declared by this class. */
Method[] getDeclaredMethods();
/**
* Gets the superclass of this class. */
Class getSuperclass();
/**
* Gets all the interfaces implemented by this class. */
Class[] getInterfaces();
}
libaopalliance-java-20070526/src/main/org/aopalliance/reflect/ClassLocator.java 0000644 0001750 0001750 00000000667 07676272773 027267 0 ustar twerner twerner
package org.aopalliance.reflect;
/**
* This interface represents a specific unit locator for base program
* classes.
*
*
For instance, this locator can represent a given class, or a * given classes set (e.g. all the classes of a given package or all * the classes that implement a given interface). * * @see ProgramUnit#getLocator() * @see Class#getClassLocator() */ public interface ClassLocator extends UnitLocator { } libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Code.java 0000644 0001750 0001750 00000010744 10155612436 025521 0 ustar twerner twerner 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);
}
libaopalliance-java-20070526/src/main/org/aopalliance/reflect/CodeLocator.java 0000644 0001750 0001750 00000001650 07676272773 027065 0 ustar twerner twerner
package org.aopalliance.reflect;
/**
* This interface represents a locator on a base program piece of
* code.
*
* The AOP Alliance implementation provider should provide code
* locators implementations in order to support several kinds of code
* locators (e.g. as the ones used in the Code
* interface).
*
*
The AOP Alliance client program gets the locator by navigating
* the base program metamodel (using the
* {@link org.aopalliance.reflect} package) and using the
* get...Locator(...) methods.
*
*
Code locators are quite different from unit locators.
*
* @see Code
* @see Code#getLocator()
* @see Code#getCallLocator(Method)
* @see Code#getReadLocator(Field)
* @see Code#getWriteLocator(Field)
* @see Code#getThrowLocator(Class)
* @see Code#getCatchLocator(Class)
* @see Method#getCallLocator()
* @see UnitLocator */
public interface CodeLocator extends Locator {
}
libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Field.java 0000644 0001750 0001750 00000003626 07676272773 025717 0 ustar twerner twerner
package org.aopalliance.reflect;
/**
* This represents a field of a class. */
public interface Field extends Member {
/**
* Same as getReadLocator(USER_SIDE).
*
* @see #getReadLocator(int) */
CodeLocator getReadLocator();
/**
* This methods returns the points where the current field is read.
*
*
There are two different behaviors for this method depending
* on the side of the locator. At the user side, the locator
* designates all the points in methods bodies where the field is
* read (similarly to Code.getReadLocator(Field)). At
* the provider side, it really may depend on the implementor
* choice (e.g. it can return a locator on the body of the field's
* getter).
*
*
In Java, the user side is most of the time used so that you
* can use the method getReadLocator().
*
* @param side USER_SIDE || PROVIDER_SIDE
* @see #getReadLocator() */
CodeLocator getReadLocator(int side);
/**
* Same as getWriteLocator(USER_SIDE).
*
* @see #getWriteLocator(int) */
CodeLocator getWriteLocator();
/**
* This methods returns the points where the current field is
* written.
*
*
There are two different behaviors for this method depending
* on the side of the locator. At the user side, the locator
* designates all the points in methods bodies where the field is
* written (similarly to Code.getWriteLocator(Field)). At
* the provider side, it really may depend on the implementor
* choice (e.g. it can return a locator on the body of the field's
* setter).
*
*
In Java, the user side is most of the time used so that you
* can use the method getWriteLocator().
*
* @param side USER_SIDE || PROVIDER_SIDE
* @see #getWriteLocator() */
CodeLocator getWriteLocator(int side);
}
libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Locator.java 0000644 0001750 0001750 00000000647 07676272773 026277 0 ustar twerner twerner
package org.aopalliance.reflect;
/**
* This interface represents a locator on the base program.
*
*
The locators are used by the reflection API client to identify
* point(s) in the program. The client can retrieve locators by using
* the get...Locator(...) methods on the reflection API
* elements. For futher details, see the subinterfaces of this
* interface. */
public interface Locator {
}
libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Member.java 0000644 0001750 0001750 00000001152 07676272773 026073 0 ustar twerner twerner
package org.aopalliance.reflect;
/**
* This interface represents a class member.
*
*
A member can be a field, a method, or a constructor. */ public interface Member extends ProgramUnit { /** * A constant to denote the program side that uses this member. */ int USER_SIDE=0; /** * A constant to denote the program side that provides this * member. */ int PROVIDER_SIDE=1; /** * Gets the class that declares this member. */ Class getDeclaringClass(); /** * The member's name. */ String getName(); /** * The modifiers value. */ int getModifiers(); } libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Metadata.java 0000644 0001750 0001750 00000000570 07676272773 026407 0 ustar twerner twerner package org.aopalliance.reflect; /** * A metadata is a pair of values (key,data) that can be associated to * a program unit. * * @see ProgramUnit * @see ProgramUnit#addMetadata(Metadata) */ public interface Metadata { /** * Gets the key of this metadata. */ Object getKey(); /** * Gets the value of this metadata. */ Object getValue(); } libaopalliance-java-20070526/src/main/org/aopalliance/reflect/Method.java 0000644 0001750 0001750 00000002263 07676272773 026110 0 ustar twerner twerner package org.aopalliance.reflect; /** * This represents a method of a class. */ public interface Method extends Member { /** * This locator contains all the points in the program that call * this method. * *
Note that this code locator corresponds to the client-side
* call event (equiv. to
* this.getLocator(USER_SIDE). To get the server-side
* equivalent locator, one must write
* this.getBody().getLocator() or
* this.getLocator(PROVIDER_SIDE).
*
*
It is a very invasive feature since it designates all the
* calling points in all the classes of the application. To only
* designate the calling points in a given client method, one
* should write
* aClientMethod.getBody().getCallLocator(this).
*
* @see Code#getLocator()
* @see Code#getCallLocator(Method) */
CodeLocator getCallLocator();
/**
* A full version of {@link #getCallLocator()}.
*
* @param side USER_SIDE || PROVIDER_SIDE
* @see #getCallLocator() */
CodeLocator getCallLocator(int side);
/**
* Returns the body of the current method. */
Code getBody();
}
libaopalliance-java-20070526/src/main/org/aopalliance/reflect/ProgramUnit.java 0000644 0001750 0001750 00000003110 07676272773 027127 0 ustar twerner twerner
package org.aopalliance.reflect;
/**
* An abstract program unit.
*
*
Any structural unit of a base program (class, member, * ...). Units exclude the code. * *
When referencing a program unit, the client can retrieve unit * locators using {@link #getLocator()} or more specific methods. This * locators shall be used conjointly whith an {@link * org.aopalliance.instrument.Instrumentor} implementation in order to * perform aspetual transformations of the program (e.g. type merging, * parameters adding,...). * *
Program units also supports metadatas, i.e. the ability to add * extra information on the base program so that the client can * extends its meaning very easily. * * @see org.aopalliance.instrument.Instrumentor * @see UnitLocator * @see Class * @see Method * @see Field */ public interface ProgramUnit { /** * Returns the locator that corresponds to this unit. */ UnitLocator getLocator(); /** * Returns the metadata that is associated to this unit from its * key. */ Metadata getMetadata(Object key); /** * Returns all the metadatas that are associated to the current * unit. */ Metadata[] getMetadatas(); /** * Associates a metadata to the current unit. * *
If a metadata already exists with the same key, then its * value is replaced by the newly given one. */ void addMetadata(Metadata metadata); /** * Removes a metadata from its key. * *
If none metadata having the given key exists, then this method * has no effect. */ void removeMetadata(Object key); } libaopalliance-java-20070526/src/main/org/aopalliance/reflect/UnitLocator.java 0000644 0001750 0001750 00000000705 07676272773 027132 0 ustar twerner twerner package org.aopalliance.reflect; /** * This interface represents a locator on a base program structural unit. * *
A program unit represents any structural part of the program * (i.e. any part excepting code) such as a class, a method, a * field... * *
Unit locators are quite different from code locators. * * @see ProgramUnit * @see ProgramUnit#getLocator() * @see CodeLocator */ public interface UnitLocator extends Locator { } libaopalliance-java-20070526/src/main/org/aopalliance/reflect/package.html 0000644 0001750 0001750 00000002544 07676272773 026310 0 ustar twerner twerner
This package provides a set of interfaces for implementing a generic reflection API.
The motivations of this package are to have a generic
reflection API with interfaces so that any AO system provider can
implement its own base program introspection package. In general,
we cannot use java.lang.reflect since in most of the
AOP systems, this representation is not available (e.g. in
load-time systems or compile-time systems).
The implementor can implement this API for compile-time purpose (for instance based on a source-code analysis implementation), for a load-time purpose (mostly based on a bytecode-level implementation), or for a run-time purpose.
This package has be rougthly specified and really needs further
investigations.
libaopalliance-java-20070526/build.xml 0000644 0001750 0001750 00000002177 10026655624 017433 0 ustar twerner twerner