The program instrumentor implementation should return an
10 | * intrumentation instance for each intrumentation which is performed.
11 | *
12 | * @see Instrumentor */
13 |
14 | public interface Instrumentation {
15 |
16 | /** Interface adding instrumentation type. */
17 | int ADD_INTERFACE=0;
18 | /** Superclass setting instrumentation type. */
19 | int SET_SUPERCLASS=1;
20 | /** Class adding instrumentation type. */
21 | int ADD_CLASS=2;
22 | /** Before code instrumentation type. */
23 | int ADD_BEFORE_CODE=3;
24 | /** After code adding instrumentation type. */
25 | int ADD_AFTER_CODE=4;
26 | /** Metadata adding instrumentation type. */
27 | int ADD_METADATA=5;
28 |
29 | /**
30 | * Returns the location of this instrumentation. */
31 | Locator getLocation();
32 |
33 | /**
34 | * Gets the instrumentation type.
35 | *
36 | * @return ADD_INTERFACE | SET_SUPERCLASS | ADD_CLASS |
37 | * ADD_AFTER_CODE | ADD_BEFORE_CODE | ADD_AROUND_CODE |
38 | * ADD_METADATA */
39 | int getType();
40 |
41 | }
42 |
43 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/instrument/InstrumentationError.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.instrument;
3 |
4 | /**
5 | * The error that is raised when an error occurs during an instrumentation.
6 | *
7 | * @see Instrumentor */
8 |
9 | public class InstrumentationError extends Error {
10 |
11 | /**
12 | * Sets a generic error message for an instrumentation error. */
13 | public InstrumentationError(Instrumentation instrumentation,
14 | Throwable cause) {
15 | super("Error while instrumenting " + instrumentation,cause);
16 | }
17 |
18 | }
19 |
20 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/instrument/Instrumentor.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.instrument;
3 |
4 | import org.aopalliance.reflect.Code;
5 | import org.aopalliance.reflect.Class;
6 | import org.aopalliance.reflect.CodeLocator;
7 | import org.aopalliance.reflect.ClassLocator;
8 | import org.aopalliance.reflect.UnitLocator;
9 |
10 | /**
11 | * This interface defines all the methods that perform program
12 | * instrumentations that are useful for AOP.
13 | *
14 | *
The modifications definitions rely on an abstract representation
15 | * of locators, as defined in the {@link org.aopalliance.reflect}
16 | * package.
17 | *
18 | * @see org.aopalliance.reflect.Locator
19 | * @see org.aopalliance.reflect.ClassLocator
20 | * @see org.aopalliance.reflect.CodeLocator */
21 |
22 | public interface Instrumentor {
23 |
24 | /**
25 | * Creates a new class.
26 | *
27 | * @return the locator that corresponds to the newly created class
28 | */
29 | ClassLocator createClass(String name) throws InstrumentationError;
30 |
31 | /**
32 | * Adds a new implemented interface to a given class location.
33 | *
34 | * @return the object that corresponds to this instrumentation
35 | * @throws InstrumentationError if something went wrong with this
36 | * instrumentation
37 | * @see #undo(Instrumentation) */
38 | Instrumentation addInterface(ClassLocator location,
39 | String newInterfaceName)
40 | throws InstrumentationError;
41 |
42 | /**
43 | * Sets or replaces the current superclass of a class location.
44 | *
45 | *
The new superclass should be a subtype of the replaced one in
46 | * order to maintain backward compatibility.
47 | *
48 | * @return the object that corresponds to this instrumentation
49 | * @throws InstrumentationError if something went wrong with this
50 | * instrumentation
51 | * @see #undo(Instrumentation) */
52 | Instrumentation setSuperClass(ClassLocator location,
53 | String newSuperClassName)
54 | throws InstrumentationError;
55 |
56 | /**
57 | * Introduces a class into the class location (mixin).
58 | *
59 | *
Similarely to a mixin, the whole set of fields and methods
60 | * are introduced into the location's class, all the implemented
61 | * interface of the introduced class are also added as interfaces
62 | * of the location's class.
63 | *
64 | * @return the object that corresponds to this instrumentation
65 | * @throws InstrumentationError if something went wrong with this
66 | * instrumentation
67 | * @see #undo(Instrumentation) */
68 | Instrumentation addClass(ClassLocator location,String className)
69 | throws InstrumentationError;
70 |
71 | /**
72 | * Adds a new method to the class location.
73 | *
74 | * @return the object that corresponds to this instrumentation
75 | * @throws InstrumentationError if something went wrong with this
76 | * instrumentation
77 | * @see #undo(Instrumentation) */
78 | Instrumentation addMethod(ClassLocator location,
79 | String name,
80 | String[] parameterTypeNames,
81 | String[] parameterNames,
82 | Code body)
83 | throws InstrumentationError;
84 |
85 | /**
86 | * Adds a new field to the target class.
87 | *
88 | * @return the object that corresponds to this instrumentation
89 | * @throws InstrumentationError if something went wrong with this
90 | * instrumentation
91 | * @see #undo(Instrumentation) */
92 | Instrumentation addField(ClassLocator location,
93 | String name,
94 | String typeName,
95 | Code initializator)
96 | throws InstrumentationError;
97 |
98 | /**
99 | * Adds some code before a given method code body.
100 | *
101 | * @param location the modification locator that can represent a
102 | * method invocation, a field set/get, or a constructor (at callee
103 | * or caller side)
104 | * @param beforeCode the code to be added before
105 | * @param before the modification that must stay before this
106 | * before code
107 | * @param after the modification that must stay after this
108 | * before code
109 | * @return the object that corresponds to this instrumentation
110 | * @throws InstrumentationError if something went wrong with this
111 | * instrumentation
112 | * @see #undo(Instrumentation) */
113 | Instrumentation addBeforeCode(CodeLocator location,
114 | Code beforeCode,
115 | Instrumentation before,
116 | Instrumentation after)
117 | throws InstrumentationError;
118 |
119 | /**
120 | * Adds some code after a given method code body.
121 | *
122 | * @param location the modification locator that can represent a
123 | * method invocation, a field set/get, or a constructor (at callee
124 | * or caller side)
125 | * @param afterCode the code to be added after
126 | * @param before the modification that must stay before this
127 | * after code
128 | * @param after the modification that must stay after this
129 | * after code
130 | * @return the object that corresponds to this instrumentation
131 | * @throws InstrumentationError if something went wrong with this
132 | * instrumentation
133 | * @see #undo(Instrumentation) */
134 | Instrumentation addAfterCode(CodeLocator location,
135 | Code afterCode,
136 | Instrumentation before,
137 | Instrumentation after)
138 | throws InstrumentationError;
139 |
140 | /**
141 | * Adds some code around a given method code body.
142 | *
143 | *
An around code is a code that calls a proceed method
144 | * one or several times. When the proceed method is invoked, the
145 | * location is executed (for compile approched, the proceed method
146 | * call is subsituted by the location).
147 | *
148 | *
The proceed method name is parameterized by the
149 | * proceedMethodName argument (can be
150 | * proceed, invokeNext,
151 | * runNext, etc).
152 | *
153 | *
Note that if the around code does not call the proceed
154 | * method, then the around instrumentation is similar to a
155 | * replacement of the location. This is not aspect-safe but can be
156 | * useful in some instrumentation process to build AO systems.
157 | *
158 | * @param location the modification locator that can represent a
159 | * method invocation, a field set/get, or a constructor (at callee
160 | * or caller side)
161 | * @param aroundCode the code to be added after
162 | * @param proceedMethodName the name of the proceed method
163 | * @param before the modification that must stay before this
164 | * after code
165 | * @param after the modification that must stay after this
166 | * after code
167 | * @return the object that corresponds to this instrumentation
168 | * @throws InstrumentationError if something went wrong with this
169 | * instrumentation
170 | * @see #undo(Instrumentation) */
171 | Instrumentation addAroundCode(CodeLocator location,
172 | Code aroundCode,
173 | String proceedMethodName,
174 | Instrumentation before,
175 | Instrumentation after)
176 | throws InstrumentationError;
177 |
178 | /**
179 | * Cancels an instrumentation.
180 | *
181 | * @param instrumentation the instrumentation to cancel
182 | *
183 | * @throws UndoNotSupportedException when the implementation does
184 | * not support instrumentation cancellation for the given
185 | * instrumentation */
186 | void undo(Instrumentation instrumentation)
187 | throws UndoNotSupportedException;
188 |
189 | }
190 |
191 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/instrument/UndoNotSupportedException.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.instrument;
3 |
4 | /**
5 | * The exception that is raised when the client program tries to undo
6 | * an instrumentation and when current implementation does not support
7 | * it.
8 | *
9 | *
Undoing is implemented by the {@link
10 | * Instrumentor#undo(Instrumentation)} method.
11 | *
12 | * @see Instrumentor */
13 |
14 | public class UndoNotSupportedException extends Exception {
15 |
16 | /**
17 | * Sets a generic exception message for an instrumentation. */
18 | public UndoNotSupportedException(Instrumentation instrumentation) {
19 | super("Undo not supported for instrumentation: " + instrumentation);
20 | }
21 |
22 | }
23 |
24 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/instrument/package.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
This package provides an API for program instrumentation.
8 |
9 |
This package provides a set of interfaces for applying
10 | intrumentations on a program, i.e. a program modification which
11 | adds some feature (methods, classes, code) to the original
12 | program. These instrumentations are abstractly defined and can
13 | occur at compile-time, load-time, or runtime depending on the
14 | {@link org.aopalliance.instrument.Instrumentor}
15 | implementation. Moreover, since it uses the {@link
16 | org.aopalliance.reflect} package which provides an abstract
17 | representation of the program, the instrumentations can be
18 | implemented at a source-code level or at a bytecode level,
19 | depending on the implementation.
20 |
21 |
This API is specific to AOP. This means that the set of program
22 | instrumentations that is allowed is a restricted set compared to a
23 | general-purpose API. However, general-purpose transformation
24 | tools should provide an implementation of this API in order to be
25 | easily used by several AO systems.
26 |
27 |
Dependencies
28 |
29 |
This package requires the {@link org.aopalliance.reflect} package.
30 |
31 |
33 |
34 |
52 |
53 |
54 |
55 |
56 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/ConstructorInterceptor.java:
--------------------------------------------------------------------------------
1 | package org.aopalliance.intercept;
2 |
3 | /**
4 | * Intercepts the construction of a new object.
5 | *
6 | *
The user should implement the {@link
7 | * #construct(ConstructorInvocation)} method to modify the original
8 | * behavior. E.g. the following class implements a singleton
9 | * interceptor (allows only one unique instance for the intercepted
10 | * class):
11 | *
12 | *
*/
25 |
26 | public interface ConstructorInterceptor extends Interceptor
27 | {
28 | /**
29 | * Implement this method to perform extra treatments before and
30 | * after the consrution of a new object. Polite implementations
31 | * would certainly like to invoke {@link Joinpoint#proceed()}.
32 | *
33 | * @param invocation the construction joinpoint
34 | * @return the newly created object, which is also the result of
35 | * the call to {@link Joinpoint#proceed()}, might be replaced by
36 | * the interceptor.
37 | *
38 | * @throws Throwable if the interceptors or the
39 | * target-object throws an exception. */
40 | Object construct(ConstructorInvocation invocation) throws Throwable;
41 | }
42 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/ConstructorInvocation.java:
--------------------------------------------------------------------------------
1 | package org.aopalliance.intercept;
2 |
3 | import java.lang.reflect.Constructor;
4 |
5 | /**
6 | * Description of an invocation to a constuctor, given to an
7 | * interceptor upon construtor-call.
8 | *
9 | *
A constructor invocation is a joinpoint and can be intercepted
10 | * by a constructor interceptor.
11 | *
12 | * @see ConstructorInterceptor */
13 | public interface ConstructorInvocation extends Invocation {
14 |
15 | /**
16 | * Gets the constructor being called.
17 | *
18 | *
This method is a frienly implementation of the {@link
19 | * Joinpoint#getStaticPart()} method (same result).
20 | *
21 | * @return the constructor being called. */
22 | Constructor getConstructor();
23 |
24 | }
25 |
26 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/FieldAccess.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.intercept;
3 |
4 | import java.lang.reflect.Field;
5 |
6 | /**
7 | * This interface represents a field access in the program.
8 | *
9 | *
A field access is a joinpoint and can be intercepted by a field
10 | * interceptor.
11 | *
12 | * @see FieldInterceptor */
13 |
14 | public interface FieldAccess extends Joinpoint {
15 |
16 | /** The read access type (see {@link #getAccessType()}). */
17 | int READ=0;
18 | /** The write access type (see {@link #getAccessType()}). */
19 | int WRITE=1;
20 |
21 | /**
22 | * Gets the field being accessed.
23 | *
24 | *
This method is a frienly implementation of the {@link
25 | * Joinpoint#getStaticPart()} method (same result).
26 | *
27 | * @return the field being accessed. */
28 | Field getField();
29 |
30 | /**
31 | * Gets the value that must be set to the field.
32 | *
33 | *
This value can be intercepted and changed by a field
34 | * interceptor. */
35 | Object getValueToSet();
36 |
37 | /**
38 | * Returns the access type.
39 | *
40 | * @return FieldAccess.READ || FieldAccess.WRITE */
41 | int getAccessType();
42 |
43 | }
44 |
45 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/FieldInterceptor.java:
--------------------------------------------------------------------------------
1 | package org.aopalliance.intercept;
2 |
3 | /**
4 | * Intercepts field access on a target object.
5 | *
6 | *
The user should implement the {@link #set(FieldAccess)} and
7 | * {@link #get(FieldAccess)} methods to modify the original
8 | * behavior. E.g. the following class implements a tracing interceptor
9 | * (traces the accesses to the intercepted field(s)):
10 | *
11 | *
12 | * class TracingInterceptor implements FieldInterceptor {
13 | *
14 | * Object set(FieldAccess fa) throws Throwable {
15 | * System.out.println("field "+fa.getField()+" is set with value "+
16 | * fa.getValueToSet());
17 | * Object ret=fa.proceed();
18 | * System.out.println("field "+fa.getField()+" was set to value "+ret);
19 | * return ret;
20 | * }
21 | *
22 | * Object get(FieldAccess fa) throws Throwable {
23 | * System.out.println("field "+fa.getField()+" is about to be read");
24 | * Object ret=fa.proceed();
25 | * System.out.println("field "+fa.getField()+" was read; value is "+ret);
26 | * return ret;
27 | * }
28 | * }
29 | *
*/
30 |
31 | public interface FieldInterceptor extends Interceptor
32 | {
33 | /**
34 | * Do the stuff you want to do before and after the
35 | * field is getted.
36 | *
37 | *
Polite implementations would certainly like to call
38 | * {@link Joinpoint#proceed()}.
39 | *
40 | * @param fieldRead the joinpoint that corresponds to the field
41 | * read
42 | * @return the result of the field read {@link
43 | * Joinpoint#proceed()}, might be intercepted by the
44 | * interceptor.
45 | *
46 | * @throws Throwable if the interceptors or the
47 | * target-object throws an exception. */
48 | Object get(FieldAccess fieldRead) throws Throwable;
49 |
50 | /**
51 | * Do the stuff you want to do before and after the
52 | * field is setted.
53 | *
54 | *
Polite implementations would certainly like to implement
55 | * {@link Joinpoint#proceed()}.
56 | *
57 | * @param fieldWrite the joinpoint that corresponds to the field
58 | * write
59 | * @return the result of the field set {@link
60 | * Joinpoint#proceed()}, might be intercepted by the
61 | * interceptor.
62 | *
63 | * @throws Throwable if the interceptors or the
64 | * target-object throws an exception. */
65 | Object set(FieldAccess fieldWrite) throws Throwable;
66 |
67 | }
68 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/Interceptor.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.intercept;
3 |
4 | import org.aopalliance.aop.Advice;
5 |
6 | /**
7 | * This interface represents a generic interceptor.
8 | *
9 | *
A generic interceptor can intercept runtime events that occur
10 | * within a base program. Those events are materialized by (reified
11 | * in) joinpoints. Runtime joinpoints can be invocations, field
12 | * access, exceptions...
13 | *
14 | *
This interface is not used directly. Use the the sub-interfaces
15 | * to intercept specific events. For instance, the following class
16 | * implements some specific interceptors in order to implement a
17 | * debugger:
18 | *
19 | *
An invocation is a joinpoint and can be intercepted by an
8 | * interceptor.
9 | *
10 | * @author Rod Johnson */
11 |
12 | public interface Invocation extends Joinpoint {
13 |
14 | /**
15 | * Get the arguments as an array object.
16 | * It is possible to change element values within this
17 | * array to change the arguments.
18 | *
19 | * @return the argument of the invocation */
20 | Object[] getArguments();
21 |
22 | }
23 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/Joinpoint.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.intercept;
3 |
4 | import java.lang.reflect.AccessibleObject;
5 |
6 | /**
7 | * This interface represents a generic runtime joinpoint (in the AOP
8 | * terminology).
9 | *
10 | *
A runtime joinpoint is an event that occurs on a static
11 | * joinpoint (i.e. a location in a the program). For instance, an
12 | * invocation is the runtime joinpoint on a method (static joinpoint).
13 | * The static part of a given joinpoint can be generically retrieved
14 | * using the {@link #getStaticPart()} method.
15 | *
16 | *
In the context of an interception framework, a runtime joinpoint
17 | * is then the reification of an access to an accessible object (a
18 | * method, a constructor, a field), i.e. the static part of the
19 | * joinpoint. It is passed to the interceptors that are installed on
20 | * the static joinpoint.
21 | *
22 | * @see Interceptor */
23 |
24 | public interface Joinpoint {
25 |
26 | /**
27 | * Proceeds to the next interceptor in the chain.
28 | *
29 | *
The implementation and the semantics of this method depends
30 | * on the actual joinpoint type (see the children interfaces).
31 | *
32 | * @return see the children interfaces' proceed definition.
33 | *
34 | * @throws Throwable if the joinpoint throws an exception. */
35 | Object proceed() throws Throwable;
36 |
37 | /**
38 | * Returns the object that holds the current joinpoint's static
39 | * part.
40 | *
41 | *
For instance, the target object for an invocation.
42 | *
43 | * @return the object (can be null if the accessible object is
44 | * static). */
45 | Object getThis();
46 |
47 | /**
48 | * Returns the static part of this joinpoint.
49 | *
50 | *
The static part is an accessible object on which a chain of
51 | * interceptors are installed. */
52 | AccessibleObject getStaticPart();
53 |
54 | }
55 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/MethodInterceptor.java:
--------------------------------------------------------------------------------
1 | package org.aopalliance.intercept;
2 |
3 | /**
4 | * Intercepts calls on an interface on its way to the target. These
5 | * are nested "on top" of the target.
6 | *
7 | *
The user should implement the {@link #invoke(MethodInvocation)}
8 | * method to modify the original behavior. E.g. the following class
9 | * implements a tracing interceptor (traces all the calls on the
10 | * intercepted method(s)):
11 | *
12 | *
*/
23 |
24 | public interface MethodInterceptor extends Interceptor {
25 |
26 | /**
27 | * Implement this method to perform extra treatments before and
28 | * after the invocation. Polite implementations would certainly
29 | * like to invoke {@link Joinpoint#proceed()}.
30 | *
31 | * @param invocation the method invocation joinpoint
32 | * @return the result of the call to {@link
33 | * Joinpoint#proceed()}, might be intercepted by the
34 | * interceptor.
35 | *
36 | * @throws Throwable if the interceptors or the
37 | * target-object throws an exception. */
38 | Object invoke(MethodInvocation invocation) throws Throwable;
39 | }
40 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/MethodInvocation.java:
--------------------------------------------------------------------------------
1 | package org.aopalliance.intercept;
2 |
3 | import java.lang.reflect.Method;
4 |
5 | /**
6 | * Description of an invocation to a method, given to an interceptor
7 | * upon method-call.
8 | *
9 | *
A method invocation is a joinpoint and can be intercepted by a method
10 | * interceptor.
11 | *
12 | * @see MethodInterceptor */
13 | public interface MethodInvocation extends Invocation
14 | {
15 |
16 | /**
17 | * Gets the method being called.
18 | *
19 | *
This method is a frienly implementation of the {@link
20 | * Joinpoint#getStaticPart()} method (same result).
21 | *
22 | * @return the method being called.
23 | */
24 | Method getMethod();
25 |
26 | }
27 |
28 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/intercept/package.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
This package provides a set of interfaces for interception
8 | mechanisms.
9 |
10 |
Interception is a basic mechanism to implement AOP. This is
11 | widely used in middlewares and modern application servers,
12 | including J2EE ones.
13 |
14 |
This package provides an {@link
15 | org.aopalliance.intercept.Interceptor} interface that will
16 | intercept different runtime joinpoints (e.g. method calls, field
17 | access, ...). Thus, interceptors are able to add some behavior
18 | around the joinpoints actual executions. Several interceptors can
19 | be applied on a given joinpoint since they are chained. The AO
20 | system implementor should provide means to install and order these
21 | chains of interceptors.
22 |
23 |
41 |
42 |
43 |
44 |
45 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Class.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This element represents classes in the base program. */
6 |
7 | public interface Class extends ProgramUnit {
8 |
9 | /**
10 | * Returns the class locator that corresponds to this class.
11 | *
12 | *
This method returns exactly the same result as
13 | * ProgramUnit.getLocator() but with a more precise
14 | * type (ClassLocator instead of
15 | * UnitLocator).
16 | *
17 | * @see ProgramUnit#getLocator() */
18 | ClassLocator getClassLocator();
19 |
20 | /**
21 | * Gets the class's full name. */
22 | String getName();
23 |
24 | /**
25 | * Gets the fields of this class (including superclass fields). */
26 | Field[] getFields();
27 |
28 | /**
29 | * Gets the fields declared by this class. */
30 | Field[] getDeclaredFields();
31 |
32 | /**
33 | * Gets the methods of this class (including superclass
34 | * methods). */
35 | Method[] getMethods();
36 |
37 | /**
38 | * Gets the methods declared by this class. */
39 | Method[] getDeclaredMethods();
40 |
41 | /**
42 | * Gets the superclass of this class. */
43 | Class getSuperclass();
44 |
45 | /**
46 | * Gets all the interfaces implemented by this class. */
47 | Class[] getInterfaces();
48 |
49 | }
50 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/ClassLocator.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This interface represents a specific unit locator for base program
6 | * classes.
7 | *
8 | *
For instance, this locator can represent a given class, or a
9 | * given classes set (e.g. all the classes of a given package or all
10 | * the classes that implement a given interface).
11 | *
12 | * @see ProgramUnit#getLocator()
13 | * @see Class#getClassLocator() */
14 |
15 | public interface ClassLocator extends UnitLocator {
16 | }
17 |
18 |
19 |
20 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Code.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This represents a piece of code in the program.
6 | *
7 | *
It is formed of a set of instructions and can be implemented at
8 | * bytecode or source-code level.
9 | *
10 | *
Typically, a code in the program comes from method bodies (it
11 | * can be init methods (instance or static) or regular methods
12 | * (instance or static) with any kind of visibility modifiers (public,
13 | * protected, private).
14 | *
15 | *
So, this class allows the client to retrieve code locators on
16 | * instructions within this code. This locators shall be used
17 | * conjointly whith an {@link org.aopalliance.instrument.Instrumentor}
18 | * implementation in order to perform aspetual transformations of the
19 | * program (before/after/around type).
20 | *
21 | *
The {@link #getLocator} method returns the locator for the whole
22 | * method and can be used to implement callee-side transformations
23 | * before/after/around the callee method.
24 | *
25 | *
The other set of locating methods returns locators that allows
26 | * the client to implement caller-side transformations (e.g. when the
27 | * code accesses a field or calls a method).
28 | *
29 | * @see org.aopalliance.instrument.Instrumentor
30 | * @see CodeLocator
31 | * @see Method#getBody() */
32 |
33 | public interface Code {
34 |
35 | /**
36 | * Returns the code locator that corresponds to this code.
37 | *
38 | *
For instance, if a code is a set of instructions called
39 | * code, then the locator will designate
40 | * <code>.
41 | *
42 | *
This locator is typically used to locate a whole method body.
43 | *
44 | * @see Method#getBody() */
45 | CodeLocator getLocator();
46 |
47 | /**
48 | * Returns a call locator for the given callee method.
49 | *
50 | *
For instance, a call locator for method m()
51 | * designates the parts between <> in the
52 | * following code.
53 | *
54 | *
55 | * [...]
56 | * aLocalVariable.<m()>;
57 | * [...]
58 | * aMethodParameter.<m()>;
59 | * [...]
60 | * aField.<m()>;
61 | * [...]
62 | * <m()> // when m is a method of the class the current code belongs to
63 | * [...]
64 | *
65 | *
66 | *
If the given method is a static method, the locator follows
67 | * the same principles, as for constructors. For instance if the
68 | * current method is the init method of class
69 | * C:
70 | *
71 | *
76 | *
77 | * @param calleeMethod the method that is called from the current
78 | * code */
79 | CodeLocator getCallLocator(Method calleeMethod);
80 |
81 | /**
82 | * Returns a field reading locator in the current body.
83 | *
84 | *
For instance, a field read locator for field f
85 | * designates the parts between <> in the
86 | * following code.
87 | *
88 | *
95 | *
96 | * @param readField the field that is read from the current code */
97 | CodeLocator getReadLocator(Field readField);
98 |
99 | /**
100 | * Returns a field writing locator in the current body.
101 | *
102 | *
For instance, a field write locator for field f
103 | * designates the parts between <> in the
104 | * following code.
105 | *
106 | *
111 | *
112 | * @param writtenField the field that is written from the current
113 | * code */
114 | CodeLocator getWriteLocator(Field writtenField);
115 |
116 | /**
117 | * Returns a exception throwing locator in the current body.
118 | *
119 | *
For instance, an exception throw locator for exception of
120 | * type E designates the parts between
121 | * <> in the following code.
122 | *
123 | *
130 | *
131 | * @param exceptionType the type of the throwed exception */
132 | CodeLocator getThrowLocator(Class exceptionType);
133 |
134 | /**
135 | * Returns a exception catching locator in the current body.
136 | *
137 | *
For instance, an exception catch locator for exception of
138 | * type E designates the parts between
139 | * <> in the following code.
140 | *
141 | *
150 | *
151 | * @param exceptionType the type of the throwed exception */
152 | CodeLocator getCatchLocator(Class exceptionType);
153 |
154 | }
155 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/CodeLocator.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This interface represents a locator on a base program piece of
6 | * code.
7 | *
8 | *
The AOP Alliance implementation provider should provide code
9 | * locators implementations in order to support several kinds of code
10 | * locators (e.g. as the ones used in the Code
11 | * interface).
12 | *
13 | *
The AOP Alliance client program gets the locator by navigating
14 | * the base program metamodel (using the
15 | * {@link org.aopalliance.reflect} package) and using the
16 | * get...Locator(...) methods.
17 | *
18 | *
Code locators are quite different from unit locators.
19 | *
20 | * @see Code
21 | * @see Code#getLocator()
22 | * @see Code#getCallLocator(Method)
23 | * @see Code#getReadLocator(Field)
24 | * @see Code#getWriteLocator(Field)
25 | * @see Code#getThrowLocator(Class)
26 | * @see Code#getCatchLocator(Class)
27 | * @see Method#getCallLocator()
28 | * @see UnitLocator */
29 |
30 | public interface CodeLocator extends Locator {
31 | }
32 |
33 |
34 |
35 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Field.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This represents a field of a class. */
6 |
7 | public interface Field extends Member {
8 |
9 | /**
10 | * Same as getReadLocator(USER_SIDE).
11 | *
12 | * @see #getReadLocator(int) */
13 | CodeLocator getReadLocator();
14 |
15 | /**
16 | * This methods returns the points where the current field is read.
17 | *
18 | *
There are two different behaviors for this method depending
19 | * on the side of the locator. At the user side, the locator
20 | * designates all the points in methods bodies where the field is
21 | * read (similarly to Code.getReadLocator(Field)). At
22 | * the provider side, it really may depend on the implementor
23 | * choice (e.g. it can return a locator on the body of the field's
24 | * getter).
25 | *
26 | *
In Java, the user side is most of the time used so that you
27 | * can use the method getReadLocator().
28 | *
29 | * @param side USER_SIDE || PROVIDER_SIDE
30 | * @see #getReadLocator() */
31 | CodeLocator getReadLocator(int side);
32 |
33 | /**
34 | * Same as getWriteLocator(USER_SIDE).
35 | *
36 | * @see #getWriteLocator(int) */
37 | CodeLocator getWriteLocator();
38 |
39 | /**
40 | * This methods returns the points where the current field is
41 | * written.
42 | *
43 | *
There are two different behaviors for this method depending
44 | * on the side of the locator. At the user side, the locator
45 | * designates all the points in methods bodies where the field is
46 | * written (similarly to Code.getWriteLocator(Field)). At
47 | * the provider side, it really may depend on the implementor
48 | * choice (e.g. it can return a locator on the body of the field's
49 | * setter).
50 | *
51 | *
In Java, the user side is most of the time used so that you
52 | * can use the method getWriteLocator().
53 | *
54 | * @param side USER_SIDE || PROVIDER_SIDE
55 | * @see #getWriteLocator() */
56 | CodeLocator getWriteLocator(int side);
57 |
58 | }
59 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Locator.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This interface represents a locator on the base program.
6 | *
7 | *
The locators are used by the reflection API client to identify
8 | * point(s) in the program. The client can retrieve locators by using
9 | * the get...Locator(...) methods on the reflection API
10 | * elements. For futher details, see the subinterfaces of this
11 | * interface. */
12 |
13 | public interface Locator {
14 | }
15 |
16 |
17 |
18 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Member.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This interface represents a class member.
6 | *
7 | *
A member can be a field, a method, or a constructor. */
8 |
9 | public interface Member extends ProgramUnit {
10 |
11 | /**
12 | * A constant to denote the program side that uses this member. */
13 | int USER_SIDE=0;
14 | /**
15 | * A constant to denote the program side that provides this
16 | * member. */
17 | int PROVIDER_SIDE=1;
18 |
19 | /**
20 | * Gets the class that declares this member. */
21 | Class getDeclaringClass();
22 |
23 | /**
24 | * The member's name. */
25 | String getName();
26 |
27 | /**
28 | * The modifiers value. */
29 | int getModifiers();
30 |
31 | }
32 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Metadata.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * A metadata is a pair of values (key,data) that can be associated to
6 | * a program unit.
7 | *
8 | * @see ProgramUnit
9 | * @see ProgramUnit#addMetadata(Metadata) */
10 |
11 | public interface Metadata {
12 |
13 | /**
14 | * Gets the key of this metadata. */
15 | Object getKey();
16 |
17 | /**
18 | * Gets the value of this metadata. */
19 | Object getValue();
20 |
21 | }
22 |
23 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/Method.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This represents a method of a class. */
6 |
7 | public interface Method extends Member {
8 |
9 | /**
10 | * This locator contains all the points in the program that call
11 | * this method.
12 | *
13 | *
Note that this code locator corresponds to the client-side
14 | * call event (equiv. to
15 | * this.getLocator(USER_SIDE). To get the server-side
16 | * equivalent locator, one must write
17 | * this.getBody().getLocator() or
18 | * this.getLocator(PROVIDER_SIDE).
19 | *
20 | *
It is a very invasive feature since it designates all the
21 | * calling points in all the classes of the application. To only
22 | * designate the calling points in a given client method, one
23 | * should write
24 | * aClientMethod.getBody().getCallLocator(this).
25 | *
26 | * @see Code#getLocator()
27 | * @see Code#getCallLocator(Method) */
28 | CodeLocator getCallLocator();
29 |
30 | /**
31 | * A full version of {@link #getCallLocator()}.
32 | *
33 | * @param side USER_SIDE || PROVIDER_SIDE
34 | * @see #getCallLocator() */
35 | CodeLocator getCallLocator(int side);
36 |
37 |
38 | /**
39 | * Returns the body of the current method. */
40 | Code getBody();
41 |
42 | }
43 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/ProgramUnit.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * An abstract program unit.
6 | *
7 | *
Any structural unit of a base program (class, member,
8 | * ...). Units exclude the code.
9 | *
10 | *
When referencing a program unit, the client can retrieve unit
11 | * locators using {@link #getLocator()} or more specific methods. This
12 | * locators shall be used conjointly whith an {@link
13 | * org.aopalliance.instrument.Instrumentor} implementation in order to
14 | * perform aspetual transformations of the program (e.g. type merging,
15 | * parameters adding,...).
16 | *
17 | *
Program units also supports metadatas, i.e. the ability to add
18 | * extra information on the base program so that the client can
19 | * extends its meaning very easily.
20 | *
21 | * @see org.aopalliance.instrument.Instrumentor
22 | * @see UnitLocator
23 | * @see Class
24 | * @see Method
25 | * @see Field */
26 |
27 | public interface ProgramUnit {
28 |
29 | /**
30 | * Returns the locator that corresponds to this unit.
31 | */
32 | UnitLocator getLocator();
33 |
34 | /**
35 | * Returns the metadata that is associated to this unit from its
36 | * key. */
37 | Metadata getMetadata(Object key);
38 |
39 | /**
40 | * Returns all the metadatas that are associated to the current
41 | * unit. */
42 | Metadata[] getMetadatas();
43 |
44 | /**
45 | * Associates a metadata to the current unit.
46 | *
47 | *
If a metadata already exists with the same key, then its
48 | * value is replaced by the newly given one. */
49 | void addMetadata(Metadata metadata);
50 |
51 | /**
52 | * Removes a metadata from its key.
53 | *
54 | *
If none metadata having the given key exists, then this method
55 | * has no effect. */
56 | void removeMetadata(Object key);
57 | }
58 |
59 |
--------------------------------------------------------------------------------
/aopalliance/src/main/org/aopalliance/reflect/UnitLocator.java:
--------------------------------------------------------------------------------
1 |
2 | package org.aopalliance.reflect;
3 |
4 | /**
5 | * This interface represents a locator on a base program structural unit.
6 | *
7 | *
A program unit represents any structural part of the program
8 | * (i.e. any part excepting code) such as a class, a method, a
9 | * field...
10 | *
11 | *
This package provides a set of interfaces for implementing a
8 | generic reflection API.
9 |
10 |
The motivations of this package are to have a generic
11 | reflection API with interfaces so that any AO system provider can
12 | implement its own base program introspection package. In general,
13 | we cannot use java.lang.reflect since in most of the
14 | AOP systems, this representation is not available (e.g. in
15 | load-time systems or compile-time systems).
16 |
17 |
The implementor can implement this API for compile-time purpose
18 | (for instance based on a source-code analysis implementation), for a
19 | load-time purpose (mostly based on a bytecode-level
20 | implementation), or for a run-time purpose.
21 |
22 |
Provides some generic interfaces for configuration of aspects
8 | when allowed by the AO system.
9 |
10 |
It is still to be investigated (not a priority at this stage).
11 |
12 |
Dependencies
13 |
14 |
This package requires the aopi.core package.
15 |
16 |
34 |
35 |
36 |
37 |
38 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/modif/Modification.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.modif;
3 |
4 | import aopi.reflect.Locator;
5 |
6 | /**
7 | * This interface represents a modification on the base program.
8 | *
9 | *
The program modifier implementation should return a modification
10 | * instance for each modification which is performed.
11 | *
12 | * @see ProgramModifier */
13 |
14 | public interface Modification {
15 |
16 | /** Interface adding modification type. */
17 | int ADD_INTERFACE=0;
18 | /** Superclass setting modification type. */
19 | int SET_SUPERCLASS=1;
20 | /** Class adding modification type. */
21 | int ADD_CLASS=2;
22 | /** Before code modification type. */
23 | int ADD_BEFORE_CODE=3;
24 | /** After code adding modification type. */
25 | int ADD_AFTER_CODE=4;
26 | /** Metadata adding modification type. */
27 | int ADD_METADATA=5;
28 |
29 | /**
30 | * Returns the location of this modification. */
31 | Locator getLocation();
32 |
33 | /**
34 | * Gets the modification type.
35 | *
36 | * @return ADD_INTERFACE | SET_SUPERCLASS | ADD_CLASS |
37 | * ADD_AFTER_CODE | ADD_BEFORE_CODE | ADD_AROUND_CODE |
38 | * ADD_METADATA */
39 | int getType();
40 |
41 | }
42 |
43 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/modif/ProgramModifier.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.modif;
3 |
4 | import aopi.reflect.Code;
5 | import aopi.reflect.CodeLocator;
6 | import aopi.reflect.ClassLocator;
7 | import aopi.reflect.UnitLocator;
8 |
9 | /**
10 | * This interface defines all the methods that perform program
11 | * modification that are useful for AOP.
12 | *
13 | *
The modifications definitions rely on an abstract representation
14 | * of locators, as defined in the aopi.reflect package.
15 | *
16 | * @see aopi.reflect.Locator
17 | * @see aopi.reflect.ClassLocator
18 | * @see aopi.reflect.CodeLocator
19 | */
20 |
21 | public interface ProgramModifier {
22 |
23 | /**
24 | * Adds a new implemented interface to a given class location. */
25 | Modification addInterface(ClassLocator location,
26 | String newInterfaceName);
27 |
28 | /**
29 | * Sets or replaces the current superclass of a class location.
30 | *
31 | *
The new superclass should be a subtype of the replaced one in
32 | * order to maintain backward compatibility. */
33 | Modification setSuperClass(ClassLocator location,
34 | String newSuperClassName);
35 |
36 | /**
37 | * Introduces a class to the class location.
38 | *
39 | *
The whole set of fields and methods are introduced into the
40 | * location's class, all the implemented interface of the
41 | * introduced class are also added as interfaces of the location's
42 | * class. */
43 | Modification addClass(ClassLocator location,String className);
44 |
45 | /**
46 | * Adds a new method to the class location. */
47 | Modification addMethod(ClassLocator location,
48 | String name,
49 | String[] parameterTypeNames,
50 | String[] parameterNames,
51 | Code body);
52 |
53 | /**
54 | * Adds a new field to the target class. */
55 | Modification addField(ClassLocator location,
56 | String name,
57 | String typeName,
58 | Code initializator);
59 |
60 | /**
61 | * Adds some code before a given method code body.
62 | *
63 | * @param location the modification locator that can represent a
64 | * method invocation, a field set/get, or a constructor (at callee
65 | * or caller side)
66 | * @param beforeCode the code to be added before
67 | * @param before the modification that must stay before this
68 | * before code
69 | * @param after the modification that must stay after this
70 | * before code
71 | * @return the modification (can be used to place the
72 | * next modifications relatively to this one) */
73 | Modification addBeforeCode(CodeLocator location,
74 | Code beforeCode,
75 | Modification before, Modification after);
76 |
77 | /**
78 | * Adds some code after a given method code body.
79 | *
80 | * @param location the modification locator that can represent a
81 | * method invocation, a field set/get, or a constructor (at callee
82 | * or caller side)
83 | * @param afterCode the code to be added after
84 | * @param before the modification that must stay before this
85 | * after code
86 | * @param after the modification that must stay after this
87 | * after code
88 | * @return this modification (can be used to place the
89 | * next modifications relatively to this one) */
90 | Modification addAfterCode(CodeLocator location,
91 | Code afterCode,
92 | Modification before, Modification after);
93 |
94 | /**
95 | * Adds some code around a given method code body.
96 | *
97 | * @param location the modification locator that can represent a
98 | * method invocation, a field set/get, or a constructor (at callee
99 | * or caller side)
100 | * @param aroundCode the code to be added after
101 | * @param before the modification that must stay before this
102 | * after code
103 | * @param after the modification that must stay after this
104 | * after code
105 | * @return this modification (can be used to place the
106 | * next modifications relatively to this one) */
107 | Modification addAroundCode(CodeLocator location,
108 | Code aroundCode,
109 | Modification before, Modification after);
110 |
111 | }
112 |
113 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/modif/package.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
Provides an API for program modification.
8 |
9 |
This package provides a set of interfaces for applying
10 | modifications on a program. These modifications are abstractly
11 | defined and can occur at compile-time, load-time, or runtime
12 | depending on the ProgramModifier
13 | implementation. Moreover, since it uses the
14 | aopi.reflect package which provides an abstract
15 | representation of the program, the transformations can be
16 | implemented at a source-code level or at a bytecode level,
17 | depending on the implementation.
18 |
19 |
This API is specific to AOP. This means that the set of program
20 | modifications that is allowed is a restricted set compared to a
21 | general-purpose API. However, general-purpose transformation
22 | tools should provide an implementation of this API in order to be
23 | easily used by several AO systems.
24 |
25 |
Dependencies
26 |
27 |
This package requires the aopi.reflect package.
28 |
29 |
It is typically used by aopi.core package (but in
30 | an optional mode).
31 |
32 |
50 |
51 |
52 |
53 |
54 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/package.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
AOPI (AOP Interfaces) are a standard specification of a set of
8 | useful or mandatory componants for aspect-oriented systems.
9 |
10 |
The idea is to have a common set of abstract components
11 | specifications, distributed under a Public Domain licence, that
12 | will help all the projets to communicate and reuse components
13 | coming from other projects.
14 |
15 |
The AOPI project is a joint project between several software
16 | engineering people who are interested in AOP or some other
17 | related projects.
18 |
19 |
20 |
Overview
21 |
22 |
23 |
24 |
25 |
26 |
Motiviations
27 |
28 |
AOP is a new programming paradigm and set of techniques that
29 | allows better separation and modularization of concerns.
30 |
31 |
Several projects now provide AOP-related techniques such as
32 | generic proxies, interceptors, or bytecode translators. Thus, we
33 | can see a lot of new components or systems arising to perform
34 | AOP or AOP-releated stuffs:
35 |
36 |
37 |
38 | AspectJ: an AO
39 | source-level weaver. New Language.
40 |
41 | AspectWerkz: an AO
42 | framework (bytecode-level dynamic weaver+configuration).
43 |
64 | Prose: an AO
65 | bytecode-level dynamic weaver (framework).
66 |
67 | ... and many others (email me to add a new one)
69 |
70 |
71 |
72 |
All these projects have their onw goals and
73 | speficities. However, several common basic components are still
74 | usefull (and sometimes required) to build a full AO system. For
75 | instance, a component that is able to add metadata on the base
76 | components, a component that is able to perform code translation
77 | in order to advice the classes, a weaver component, a
78 | configuration component, and so on.
79 |
80 |
To us, it would be great to be able to reuse different
81 | components coming from different projects to build a full AO
82 | system, and for three main reasons.
83 |
84 |
85 |
Firstly, several components
86 | already exist and it would be stupid to rebuild them.
87 |
88 |
Secondly,
89 | various implementation of the same component may be useful and be
90 | more-or-less suited depending on the environement. For instance:
91 |
92 |
93 | the program tranformation can be done at a bytecode or a
94 | the source-code level, at compile or at run time, using an
95 | interception or a code insertion mechanism depending on
96 | the implementation of the component that translates the
97 | base program,
the weaver may be used within a
98 | standard Java context or within an EJB context, which may
99 | imply some implementation differencies
100 |
101 |
102 |
103 | Thirdly, having common interfaces
104 | would help in reusing aspects (for instance, we could imagine to
105 | reuse a JAC or a JBoss aspect in other contexts than JAC or
106 | JBoss and with other weavers -- e.g. Prose, Nanning, or
107 | AspectWerkz weavers).
108 |
109 |
110 |
111 |
For these reasons, we think that a standarization of the
112 | interfaces of the aspect-oriented components would be great and
113 | will bring great simplifications for the entire AOSD community,
114 | but also for all the communities that will to use AOP in a close
115 | future (e.g. JBoss).
116 |
117 |
135 |
136 |
137 |
138 |
139 |
140 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Class.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This element represents classes in the base program. */
6 |
7 | public interface Class extends ProgramUnit {
8 |
9 | /**
10 | * Returns the class locator that corresponds to this class.
11 | *
12 | *
This method returns exactly the same result as
13 | * ProgramUnit.getLocator() but with a more precise
14 | * type (ClassLocator instead of
15 | * UnitLocator).
16 | *
17 | * @see ProgramUnit#getLocator() */
18 | ClassLocator getClassLocator();
19 |
20 | /**
21 | * Gets the class's full name. */
22 | String getName();
23 |
24 | /**
25 | * Gets the fields of this class (including superclass fields). */
26 | Field[] getFields();
27 |
28 | /**
29 | * Gets the fields declared by this class. */
30 | Field[] getDeclaredFields();
31 |
32 | /**
33 | * Gets the methods of this class (including superclass
34 | * methods). */
35 | Method[] getMethods();
36 |
37 | /**
38 | * Gets the methods declared by this class. */
39 | Method[] getDeclaredMethods();
40 |
41 | /**
42 | * Gets the superclass of this class. */
43 | Class getSuperclass();
44 |
45 | /**
46 | * Gets all the interfaces implemented by this class. */
47 | Class[] getInterfaces();
48 |
49 | }
50 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/ClassLocator.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This interface represents a specific unit locator for base program classes.
6 | *
7 | *
For instance, this locator can represent a given class, or a
8 | * given classes set (e.g. all the classes of a given package or all
9 | * the classes that implement a given interface).
10 | *
11 | * @see ProgramUnit#getLocator()
12 | * @see Class#getClassLocator() */
13 |
14 | public interface ClassLocator extends UnitLocator {
15 | }
16 |
17 |
18 |
19 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Code.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This represents a piece of code in the program.
6 | *
7 | *
It is formed of a set of instructions and can be implemented at
8 | * bytecode or source-code level.
9 | *
10 | *
Typically, a code in the program comes from method bodies (it
11 | * can be init methods (instance or static) or regular methods
12 | * (instance or static) with any kind of visibility modifiers (public,
13 | * protected, private).
14 | *
15 | *
So, this class allows the client to retrieve code locators on
16 | * instructions within this code. This locators shall be used
17 | * conjointly whith an aopi.modif.ProgramModifier
18 | * implementation in order to perform aspetual transformations of the
19 | * program (before/after/around type).
20 | *
21 | *
The getLocator method returns the locator for the
22 | * whole method and can be used to implement callee-side
23 | * transformations before/after/around the callee method.
24 | *
25 | *
The other set of locating methods returns locators that allows
26 | * the client to implement caller-side transformations (e.g. when the
27 | * code accesses a field or calls a method).
28 | *
29 | * @see aopi.modif.ProgramModifier
30 | * @see CodeLocator
31 | * @see Method#getBody() */
32 |
33 | public interface Code {
34 |
35 | /**
36 | * Returns the code locator that corresponds to this code.
37 | *
38 | *
For instance, if a code is a set of instructions called
39 | * code, then the locator will designate
40 | * <code>.
41 | *
42 | *
This locator is typically used to locate a whole method body.
43 | *
44 | * @see Method#getBody() */
45 | CodeLocator getLocator();
46 |
47 | /**
48 | * Returns a call locator for the given callee method.
49 | *
50 | *
For instance, a call locator for method m()
51 | * designates the parts between <> in the
52 | * following code.
53 | *
54 | *
55 | * [...]
56 | * aLocalVariable.<m()>;
57 | * [...]
58 | * aMethodParameter.<m()>;
59 | * [...]
60 | * aField.<m()>;
61 | * [...]
62 | * <m()> // when m is a method of the class the current code belongs to
63 | * [...]
64 | *
65 | *
66 | *
If the given method is a static method, the locator follows
67 | * the same principles, as for constructors. For instance if the
68 | * current method is the init method of class
69 | * C:
70 | *
71 | *
76 | *
77 | * @param calleeMethod the method that is called from the current
78 | * code */
79 | CodeLocator getCallLocator(Method calleeMethod);
80 |
81 | /**
82 | * Returns a field reading locator in the current body.
83 | *
84 | *
For instance, a field read locator for field f
85 | * designates the parts between <> in the
86 | * following code.
87 | *
88 | *
95 | *
96 | * @param readField the field that is read from the current code */
97 | CodeLocator getReadLocator(Field readField);
98 |
99 | /**
100 | * Returns a field writing locator in the current body.
101 | *
102 | *
For instance, a field write locator for field f
103 | * designates the parts between <> in the
104 | * following code.
105 | *
106 | *
111 | *
112 | * @param writtenField the field that is written from the current
113 | * code */
114 | CodeLocator getWriteLocator(Field writtenField);
115 |
116 | /**
117 | * Returns a exception throwing locator in the current body.
118 | *
119 | *
For instance, an exception throw locator for exception of
120 | * type E designates the parts between
121 | * <> in the following code.
122 | *
123 | *
130 | *
131 | * @param exeptionType the type of the throwed exception */
132 | CodeLocator getThrowLocator(Class exceptionType);
133 |
134 | /**
135 | * Returns a exception catching locator in the current body.
136 | *
137 | *
For instance, an exception catch locator for exception of
138 | * type E designates the parts between
139 | * <> in the following code.
140 | *
141 | *
150 | *
151 | * @param exeptionType the type of the throwed exception */
152 | CodeLocator getCatchLocator(Class exceptionType);
153 |
154 | }
155 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/CodeLocator.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This interface represents a locator on a base program piece of
6 | * code.
7 | *
8 | *
The AOPI implementation provider should provide code locators
9 | * implementations in order to support several kinds of code locators
10 | * (e.g. as the ones used in the Code interface).
11 | *
12 | *
The AOPI client program gets the locator by navigating the base
13 | * program metamodel (using the aopi.reflect package) and
14 | * using the get...Locator(...) methods.
15 | *
16 | *
Code locators are quite different from unit locators.
17 | *
18 | * @see Code
19 | * @see Code#getLocator()
20 | * @see Code#getCallLocator(Method)
21 | * @see Code#getReadLocator(Field)
22 | * @see Code#getWriteLocator(Field)
23 | * @see Code#getThrowLocator(Class)
24 | * @see Code#getCatchLocator(Class)
25 | * @see Method#getCallLocator()
26 | * @see UnitLocator */
27 |
28 | public interface CodeLocator extends Locator {
29 | }
30 |
31 |
32 |
33 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Field.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This represents a field of a class. */
6 |
7 | public interface Field extends Member {
8 |
9 | /**
10 | * Same as getReadLocator(USER_SIDE).
11 | *
12 | * @see #getReadLocator(int) */
13 | CodeLocator getReadLocator();
14 |
15 | /**
16 | * This methods returns the points where the current field is read.
17 | *
18 | *
There are two different behaviors for this method depending
19 | * on the side of the locator. At the user side, the locator
20 | * designates all the points in methods bodies where the field is
21 | * read (similarly to Code.getReadLocator(Field)). At
22 | * the provider side, it really may depend on the implementor
23 | * choice (e.g. it can return a locator on the body of the field's
24 | * getter).
25 | *
26 | *
In Java, the user side is most of the time used so that you
27 | * can use the method getReadLocator().
28 | *
29 | * @param side USER_SIDE || PROVIDER_SIDE
30 | * @see #getReadLocator() */
31 | CodeLocator getReadLocator(int side);
32 |
33 | /**
34 | * Same as getWriteLocator(USER_SIDE).
35 | *
36 | * @see #getWriteLocator(int) */
37 | CodeLocator getWriteLocator();
38 |
39 | /**
40 | * This methods returns the points where the current field is
41 | * written.
42 | *
43 | *
There are two different behaviors for this method depending
44 | * on the side of the locator. At the user side, the locator
45 | * designates all the points in methods bodies where the field is
46 | * written (similarly to Code.getWriteLocator(Field)). At
47 | * the provider side, it really may depend on the implementor
48 | * choice (e.g. it can return a locator on the body of the field's
49 | * setter).
50 | *
51 | *
In Java, the user side is most of the time used so that you
52 | * can use the method getWriteLocator().
53 | *
54 | * @param side USER_SIDE || PROVIDER_SIDE
55 | * @see #getWriteLocator() */
56 | CodeLocator getWriteLocator(int side);
57 |
58 | }
59 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Locator.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This interface represents a locator on the base program.
6 | *
7 | *
The locators are used by the reflection API client to identify
8 | * point(s) in the program. The client can retrieve locators by using
9 | * the get...Locator(...) methods on the reflection API
10 | * elements. For futher details, see the subinterfaces of this
11 | * interface. */
12 |
13 | public interface Locator {
14 | }
15 |
16 |
17 |
18 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Member.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This interface represents a class member.
6 | *
7 | *
A member can be a field, a method, or a constructor. */
8 |
9 | public interface Member extends ProgramUnit {
10 |
11 | /**
12 | * A constant to denote the program side that uses this member. */
13 | int USER_SIDE=0;
14 | /**
15 | * A constant to denote the program side that provides this
16 | * member. */
17 | int PROVIDER_SIDE=1;
18 |
19 | /**
20 | * Gets the class that declares this member. */
21 | Class getDeclaringClass();
22 |
23 | /**
24 | * The member's name. */
25 | String getName();
26 |
27 | /**
28 | * The modifiers value. */
29 | int getModifiers();
30 |
31 | }
32 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Metadata.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * A metadata is a pair of values (key,data) that can be associated to
6 | * a program unit.
7 | *
8 | * @see ProgramUnit
9 | * @see ProgramUnit#addMetadata(Metadata) */
10 |
11 | public interface Metadata {
12 |
13 | /**
14 | * Gets the key of this metadata. */
15 | Object getKey();
16 |
17 | /**
18 | * Gets the value of this metadata. */
19 | Object getValue();
20 |
21 | }
22 |
23 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/Method.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This represents a method of a class. */
6 |
7 | public interface Method extends Member {
8 |
9 | /**
10 | * This locator contains all the points in the program that call
11 | * this method.
12 | *
13 | *
Note that this code locator corresponds to the client-side
14 | * call event (equiv. to
15 | * this.getLocator(USER_SIDE). To get the server-side
16 | * equivalent locator, one must write
17 | * this.getBody().getLocator() or
18 | * this.getLocator(PROVIDER_SIDE).
19 | *
20 | *
It is a very invasive feature since it designates all the
21 | * calling points in all the classes of the application. To only
22 | * designate the calling points in a given client method, one
23 | * should write
24 | * aClientMethod.getBody().getCallLocator(this).
25 | *
26 | * @see Code#getLocator()
27 | * @see Code#getCallLocator(Method) */
28 | CodeLocator getCallLocator();
29 |
30 | /**
31 | * A full version of getCallLocator().
32 | *
33 | * @param side USER_SIDE || PROVIDER_SIDE
34 | * @see #getCallLocator() */
35 | CodeLocator getCallLocator(int side);
36 |
37 |
38 | /**
39 | * Returns the body of the current method. */
40 | Code getBody();
41 |
42 | }
43 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/ProgramUnit.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * An abstract program unit.
6 | *
7 | *
Any structural unit of a base program (class, member,
8 | * ...). Units exclude the code.
9 | *
10 | *
When referencing a program unit, the client can retrieve unit
11 | * locators using getLocator() or more specific
12 | * methods. This locators shall be used conjointly whith an
13 | * aopi.modif.ProgramModifier implementation in order to
14 | * perform aspetual transformations of the program (e.g. type merging,
15 | * parameters adding,...).
16 | *
17 | *
Program units also supports metadatas, i.e. the ability to add
18 | * extra information on the base program so that the client can
19 | * extends its meaning very easily.
20 | *
21 | * @see aopi.modif.ProgramModifier
22 | * @see UnitLocator
23 | * @see Class
24 | * @see Method
25 | * @see Field */
26 |
27 | public interface ProgramUnit {
28 |
29 | /**
30 | * Returns the locator that corresponds to this unit.
31 | */
32 | UnitLocator getLocator();
33 |
34 | /**
35 | * Returns the metadata that is associated to this unit from its
36 | * key. */
37 | Metadata getMetadata(Object key);
38 |
39 | /**
40 | * Returns all the metadatas that are associated to the current
41 | * unit. */
42 | Metadata[] getMetadatas();
43 |
44 | /**
45 | * Associates a metadata to the current unit.
46 | *
47 | *
If a metadata already exists with the same key, then its
48 | * value is replaced by the newly given one. */
49 | void addMetadata(Metadata metadata);
50 |
51 | /**
52 | * Removes a metadata from its key.
53 | *
54 | *
If none metadata having the given key exists, then this method
55 | * has no effect. */
56 | void removeMetadata(Object key);
57 | }
58 |
59 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/reflect/UnitLocator.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.reflect;
3 |
4 | /**
5 | * This interface represents a locator on a base program structural unit.
6 | *
7 | *
A program unit represents any structural part of the program
8 | * (i.e. any part excepting code) such as a class, a method, a
9 | * field...
10 | *
11 | *
Provides a set of interfaces for implementing a generic
8 | reflection API.
9 |
10 |
The motivations of this package are to have a generic
11 | reflection API with interfaces so that any AO system provider can
12 | implement its own base program introspection package. In general,
13 | we cannot use java.lang.reflect since in most of the
14 | AOP systems, this representation is not available (e.g. in
15 | load-time systems or compile-time systems).
16 |
17 |
The implementor can implement this API for compile-time purpose
18 | (for instance based on a source-code analysis implementation), for a
19 | load-time purpose (mostly based on a bytecode-level
20 | implementation), or for a run-time purpose.
21 |
22 |
This package has be rougthly specified and really needs further
23 | investigations.
24 |
25 |
Dependencies
26 |
27 |
This package is used by most of the AOPI packages (as soon as a
28 | reference on a class or a member is requiered in the API).
29 |
30 |
48 |
49 |
50 |
51 |
52 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/weaving/DynamicWeaver.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.weaving;
3 |
4 | import aopi.core.Aspect;
5 | import aopi.core.AspectElement;
6 |
7 | /**
8 | * This interface represents a dynamic weaver for dynamic AOP.
9 | *
10 | *
In dynamic AOP, aspects can be removed or reconfigured at
11 | * runtime. */
12 |
13 | public interface DynamicWeaver extends Weaver {
14 |
15 | /**
16 | * Unweaves a currently woven aspect. */
17 | void unweave(Aspect aspect);
18 |
19 | /**
20 | * Unweaves a currently applied aspect element.
21 | *
22 | *
This feature allows finer grained unweaving. */
23 | void unweave(AspectElement aspectElement);
24 |
25 | /**
26 | * Reloads a given aspect (its definition and/or configuration
27 | * might have changed since it has been last woven or reloaded). */
28 | void reload(Aspect aspect);
29 |
30 | /**
31 | * Reloads a given aspect element. */
32 | void reload(AspectElement aspectElement);
33 |
34 | }
35 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/weaving/Weaver.java:
--------------------------------------------------------------------------------
1 |
2 | package aopi.weaving;
3 |
4 | import aopi.core.Aspect;
5 | import aopi.core.WeavingRule;
6 |
7 | /**
8 | * This interface represents a weaver in an AO system.
9 | *
10 | *
A weaver is the sofware component which is responsible for
11 | * taking all the aspects and composing then to the base program. To
12 | * be AOPI-compliant, this weaver should use the
13 | * aopi.modif.ProgramModifier interface.
14 | *
15 | * @see aopi.modif.ProgramModifier */
16 |
17 | public interface Weaver {
18 |
19 | /**
20 | * Weaves a given aspect to the program. */
21 | void weave(Aspect aspect);
22 |
23 | /**
24 | * Get all the aspects handled by this weaver. */
25 | Aspect getAspects();
26 |
27 | /**
28 | * Returns the list of all the global weaving rules.
29 | *
30 | *
This has to be further investigated and specified. */
31 | WeavingRule[] getWeavingRules();
32 | }
33 |
34 |
--------------------------------------------------------------------------------
/aopi-pre-spec/src/aopi/weaving/package.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
Provides the standard weaving components interfaces in an AOP
8 | system.
The AOP Alliance project is a joint open-source project between
18 | several software engineering people who are interested in AOP and
19 | Java.
20 |
21 |
LICENCE: all the source code provided by AOP Alliance is Public Domain.
22 |
23 |
We believe that Aspect-Oriented Programming (AOP) offers a
26 | better solution to many problems than do existing technologies
27 | such as EJB. AOP Alliance intends to facilitate and standardize
28 | the use of AOP to enhance existing middleware environments (such
29 | as J2EE), or development environements (e.g. JBuilder, Eclipse).
30 | The AOP Alliance also aims to ensure interoperability between
31 | Java/J2EE AOP implementations to build a larger AOP community.
32 |
33 |
Aspect-Oriented Programming (AOP) is a programming technique
18 | that will be able to enhance several existing middleware
19 | environments (such as J2EE), or development environements
20 | (e.g. JBuilder, Eclipse).
21 |
22 |
Several projects now provide AOP-related techniques such as
23 | generic proxies, interceptors, or bytecode translators.
24 |
25 |
59 | Prose: an AO
60 | bytecode-level dynamic weaver (framework).
61 |
62 | ... and many others (email me to add a new one)
64 |
65 |
66 |
67 |
All these projects have their onw goals and
68 | speficities. However, several common basic components are still
69 | usefull (and sometimes required) to build a full AO system. For
70 | instance, a component that is able to add metadata on the base
71 | components, an interception framework, a component that is able
72 | to perform code translation in order to advice the classes, a
73 | weaver component, a configuration component, and so on.
74 |
75 |
To us, it would be great to be able to reuse different
76 | components coming from different projects to build a full AO
77 | system, and for three main reasons.
78 |
79 |
80 |
Firstly, several components
81 | already exist and it would be stupid to rebuild them.
82 |
83 |
Secondly,
84 | various implementation of the same component may be useful and be
85 | more-or-less suited depending on the environement. For instance:
86 |
87 |
88 | the program tranformation can be done at a bytecode or a
89 | the source-code level, at compile or at run time, using an
90 | interception or a code insertion mechanism depending on
91 | the implementation of the component that translates the
92 | base program,
the weaver may be used within a
93 | standard Java context or within an EJB context, which may
94 | imply some implementation differencies
95 |
96 |
97 |
98 | Thirdly, having common interfaces and components would help in
99 | reusing aspects on different weaving environements... this
100 | will greatly improve sofware reusing.
101 |
102 |
103 |
104 |
For these reasons, we think that a standarization of the
105 | interfaces of the aspect-oriented components would be great and
106 | will bring great simplifications for the entire AOSD community,
107 | but also for all the communities that will to use AOP in a close
108 | future.
109 |
110 |
111 |
24 |