Headlines per ADOC file should start at level 1, not 2. Adjusting the level offset for books helps to avoid warnings when including book chapters, but still allows to also use the chapters as stand-alone documents. Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>tags/V1_9_21_1
@@ -1,4 +1,4 @@ | |||
== *AspectJ^TM^ Compiler and Core Tools License* | |||
= AspectJ^TM^ Compiler and Core Tools License | |||
This is a binary-only release. Source code is available from | |||
https://eclipse.org/aspectj | |||
@@ -7,7 +7,7 @@ The Eclipse Foundation makes available all content in this distribution | |||
("Content"). Unless otherwise indicated below, the Content is provided | |||
to you under the terms and conditions of the Eclipse Public License | |||
Version v 2.0 ("EPL"). A copy of the EPL is available at | |||
xref:../../org/documents/epl-2.0/EPL-2.0.txt[https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt]. | |||
link:[https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt]. | |||
For purposes of the EPL, "Program" will mean the Content. | |||
If you did not receive this Content directly from the Eclipse | |||
@@ -17,9 +17,9 @@ use of any object code in the Content. Check the Redistributor's license | |||
that was provided with the Content. If no such license exists, contact | |||
the Redistributor. Unless otherwise indicated below, the terms and | |||
conditions of the EPL still apply to any source code in the Content and | |||
such source code may be obtained at link:/[https://www.eclipse.org]. | |||
such source code may be obtained at link:[https://www.eclipse.org]. | |||
=== Third Party Content | |||
== Third Party Content | |||
The Content includes items that have been sourced from third parties as | |||
set out below. If you did not receive this Content directly from the | |||
@@ -27,9 +27,7 @@ Eclipse Foundation, the following is provided for informational purposes | |||
only, and you should look to the Redistributor's license for terms and | |||
conditions of use. | |||
__ | |||
==== BCEL v5.1 | |||
=== BCEL v5.1 | |||
This product contains software developed by the Apache Software | |||
Foundation (http://www.apache.org/[http://www.apache.org]). | |||
@@ -40,7 +38,7 @@ https://commons.apache.org/bcel/. Source code for the modified version | |||
of BCEL is available at Eclipse.org in the AspectJ source tree. This | |||
code is made available under the Apache Software License v1.1 | |||
==== ASM v2.2.1 | |||
=== ASM v2.2.1 | |||
AspectJ includes a binary version of ASM v2.2.1 | |||
(http://asm.objectweb.org/index.html[http://asm.objectweb.org/]) The |
@@ -1,8 +1,8 @@ | |||
== AspectJ^TM^ | |||
= AspectJ^TM^ | |||
_Version @build.version.long@ released on @build.date@._ | |||
=== 1 Contents of this Package | |||
== 1 Contents of this Package | |||
* the link:bin[`<aspectj install dir>/bin`] directory has scripts for | |||
** `ajc`: the compiler for the AspectJ language | |||
@@ -19,7 +19,7 @@ the link:doc/index.html[index] page. | |||
''''' | |||
=== 2 Install Procedure | |||
== 2 Install Procedure | |||
The AspectJ tool `ajc` is a Java program that can be | |||
run indirectly from the scripts or directly from `aspectjtools.jar`. The | |||
@@ -62,7 +62,7 @@ create short launch scripts to start ajc easily (section 3). | |||
''''' | |||
=== 3. Running the Tools | |||
== 3. Running the Tools | |||
If you did not use the automatic installation process or the default | |||
launch scripts do not work on your system, you may wish to create short | |||
@@ -98,9 +98,9 @@ ____ | |||
''''' | |||
[[configInstructions]] | |||
=== 4. Configuration Instructions | |||
== 4. Configuration Instructions | |||
==== 4.1 Adding `<aspectj install dir>/lib/aspectjrt.jar` to your classpath | |||
=== 4.1 Adding `<aspectj install dir>/lib/aspectjrt.jar` to your classpath | |||
There are several ways to add this jar file to your classpath: | |||
@@ -110,7 +110,7 @@ next section for details) | |||
* always use the "`-classpath aspectjrt.jar`" option when running | |||
programs compiled with ajc | |||
==== 4.2 [#6.1]#Setting the Environment Variables on Windows# | |||
=== 4.2 [#6.1]#Setting the Environment Variables on Windows# | |||
The following instructions use the PATH variable as an example, but this | |||
process is identical for the CLASSPATH variable. |
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ 5 Development Kit Developer's Notebook | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -1,14 +1,14 @@ | |||
== Annotations | |||
= Annotations | |||
[[annotations-inJava5]] | |||
=== Annotations in Java 5 | |||
== Annotations in Java 5 | |||
This section provides the essential information about annotations in | |||
Java 5 needed to understand how annotations are treated in AspectJ 5. | |||
For a full introduction to annotations in Java, please see the | |||
documentation for the Java 5 SDK. | |||
==== Using Annotations | |||
=== Using Annotations | |||
Java 5 introduces _annotation types_ which can be used to express | |||
metadata relating to program members in the form of _annotations_. | |||
@@ -55,7 +55,7 @@ Multi-value annotations must use the `member-name=value | |||
public void someMethod() {...} | |||
.... | |||
==== Retention Policies | |||
=== Retention Policies | |||
Annotations can have one of three retention policies: | |||
@@ -74,7 +74,7 @@ Local variable annotations are not retained in class files (or at | |||
runtime) regardless of the retention policy set on the annotation type. | |||
See JLS 9.6.1.2. | |||
==== Accessing Annotations at Runtime | |||
=== Accessing Annotations at Runtime | |||
Java 5 supports a new interface, `java.lang.reflect.AnnotatedElement`, | |||
that is implemented by the reflection classes in Java (`Class`, | |||
@@ -84,7 +84,7 @@ you access to annotations _that have runtime retention_ via the | |||
annotation types are just regular Java classes, the annotations returned | |||
by these methods can be queried just like any regular Java object. | |||
==== Annotation Inheritance | |||
=== Annotation Inheritance | |||
It is important to understand the rules relating to inheritance of | |||
annotations, as these have a bearing on join point matching based on the | |||
@@ -120,7 +120,7 @@ interfaces never inherits any annotations from the interfaces it | |||
implements. | |||
[[annotations-aspectmembers]] | |||
=== Annotating Aspects | |||
== Annotating Aspects | |||
AspectJ 5 supports annotations on aspects, and on method, field, | |||
constructor, advice, and inter-type declarations within aspects. Method | |||
@@ -210,14 +210,14 @@ public aspect AnAspect { | |||
.... | |||
[[annotations-pointcuts-and-advice]] | |||
=== Join Point Matching based on Annotations | |||
== Join Point Matching based on Annotations | |||
This section discusses changes to type pattern and signature pattern | |||
matching in AspectJ 5 that support matching join points based on the | |||
presence or absence of annotations. We then discuss means of exposing | |||
annotation values within the body of advice. | |||
==== Annotation Patterns | |||
=== Annotation Patterns | |||
For any kind of annotated element (type, method, constructor, package, | |||
etc.), an annotation pattern can be used to match against the set of | |||
@@ -254,7 +254,7 @@ Some examples of annotation patterns follow: | |||
element with an annotation that is declared in the org.xyz package or | |||
a sub-package. (The parenthesis are required in this example). | |||
==== Type Patterns | |||
=== Type Patterns | |||
AspectJ 1.5 extends type patterns to allow an optional | |||
`AnnotationPattern` prefix. | |||
@@ -320,10 +320,10 @@ patterns: | |||
`@Inherited` annotation. | |||
[[signaturePatterns]] | |||
==== Signature Patterns | |||
=== Signature Patterns | |||
[[fieldPatterns]] | |||
===== Field Patterns | |||
==== Field Patterns | |||
A `FieldPattern` can optionally specify an annotation-matching pattern | |||
as the first element: | |||
@@ -365,7 +365,7 @@ annotations that match the pattern. For example: | |||
`@Classified`. | |||
[[methodPatterns]] | |||
===== Method and Constructor Patterns | |||
==== Method and Constructor Patterns | |||
A `MethodPattern` can optionally specify an annotation-matching pattern | |||
as the first element. | |||
@@ -424,7 +424,7 @@ annotations that match the pattern. For example: | |||
Matches any method taking at least one parameter, where the parameter | |||
type has an annotation `@Immutable`. | |||
==== Example Pointcuts | |||
=== Example Pointcuts | |||
`within(@Secure *)`:: | |||
Matches any join point where the code executing is declared in a type | |||
@@ -448,7 +448,7 @@ annotations that match the pattern. For example: | |||
is not `Catastrophic`. The format of the `handler` pointcut designator | |||
in AspectJ 5 is `'handler' '(' OptionalParensTypePattern ')'`. | |||
==== Runtime type matching and context exposure | |||
=== Runtime type matching and context exposure | |||
AspectJ 5 supports a set of "@" pointcut designators which can be used | |||
both to match based on the presence of an annotation at runtime, and to | |||
@@ -617,7 +617,7 @@ be used to match against annotations that have at least class-file | |||
retention, and if used in the binding form the annotation must have | |||
runtime retention. | |||
==== Package and Parameter Annotations | |||
=== Package and Parameter Annotations | |||
_Matching on package annotations is not supported in AspectJ. Support | |||
for this capability may be considered in a future release._ | |||
@@ -677,7 +677,7 @@ The parentheses are grouping @SomeOtherAnnotation with the * to form the | |||
type pattern for the parameter, then the type @SomeAnnotation will be | |||
treated as a parameter annotation pattern. | |||
==== Annotation Inheritance and pointcut matching | |||
=== Annotation Inheritance and pointcut matching | |||
According to the Java 5 specification, non-type annotations are not | |||
inherited, and annotations on types are only inherited if they have the | |||
@@ -722,7 +722,7 @@ throws clause) is based on the subject of the join point (the method | |||
actually being called). | |||
[[matchingOnAnnotationValues]] | |||
==== Matching based on annotation values | |||
=== Matching based on annotation values | |||
The `if` pointcut designator can be used to write pointcuts that match | |||
based on the values annotation members. For example: | |||
@@ -735,9 +735,9 @@ pointcut txRequiredMethod(Tx transactionAnnotation) : | |||
.... | |||
[[annotations-decp]] | |||
=== Using Annotations with declare statements | |||
== Using Annotations with declare statements | |||
==== Declare error and declare warning | |||
=== Declare error and declare warning | |||
Since pointcut expressions in AspectJ 5 support join point matching | |||
based on annotations, this facility can be exploited when writing | |||
@@ -757,7 +757,7 @@ declare error : call(* org.xyz.model.*.*(..)) && | |||
: "Untrusted code should not call the model classes directly"; | |||
.... | |||
==== declare parents | |||
=== declare parents | |||
The general form of a `declare parents` statement is: | |||
@@ -787,7 +787,7 @@ annotation type is matched by a non-explicit type pattern used in a | |||
declare parents statement it will be ignored (and an XLint warning | |||
issued). | |||
==== declare precedence | |||
=== declare precedence | |||
The general form of a declare precedence statement is: | |||
@@ -805,7 +805,7 @@ information as part of the pattern specification. For example: | |||
security-related aspects take precedence). | |||
[[annotations-declare]] | |||
=== Declare Annotation | |||
== Declare Annotation | |||
AspectJ 5 supports a new kind of declare statement, | |||
`declare annotation`. This takes different forms according to the | |||
@@ -854,6 +854,6 @@ declare @constructor : BankAccount+.new(..) : | |||
annotation. | |||
[[annotations-itds]] | |||
=== Inter-type Declarations | |||
== Inter-type Declarations | |||
An annotation type may not be the target of an inter-type declaration. |
@@ -1,8 +1,8 @@ | |||
[[ataspectj]] | |||
== An Annotation Based Development Style | |||
= An Annotation Based Development Style | |||
[[ataspectj-intro]] | |||
=== Introduction | |||
== Introduction | |||
In addition to the familiar AspectJ code-based style of aspect | |||
declaration, AspectJ 5 also supports an annotation-based style of aspect | |||
@@ -25,7 +25,7 @@ chapter we introduce the @AspectJ annotations and show how they can be | |||
used to declare aspects and aspect members. | |||
[[ataspectj-aspects]] | |||
=== Aspect Declarations | |||
== Aspect Declarations | |||
Aspect declarations are supported by the | |||
`org.aspectj.lang.annotation.Aspect` annotation. The declaration: | |||
@@ -59,18 +59,18 @@ is equivalent to... | |||
public aspect Foo perthis(execution(* abc..*(..))) {} | |||
.... | |||
==== Limitations | |||
=== Limitations | |||
Privileged aspects are not supported by the annotation style. | |||
[[ataspectj-pcadvice]] | |||
=== Pointcuts and Advice | |||
== Pointcuts and Advice | |||
Pointcut and advice declarations can be made using the | |||
`Pointcut, Before, After, AfterReturning, AfterThrowing,` and `Around` | |||
annotations. | |||
==== Pointcuts | |||
=== Pointcuts | |||
Pointcuts are specified using the `org.aspectj.lang.annotation.Pointcut` | |||
annotation on a method declaration. The method should have a `void` | |||
@@ -136,7 +136,7 @@ is equivalent to... | |||
protected abstract pointcut anyCall(); | |||
.... | |||
===== Type references inside @AspectJ annotations | |||
==== Type references inside @AspectJ annotations | |||
Using the code style, types referenced in pointcut expressions are | |||
resolved with respect to the imported types in the compilation unit. | |||
@@ -179,7 +179,7 @@ public class Foo { | |||
} | |||
.... | |||
===== if() pointcut expressions | |||
==== if() pointcut expressions | |||
In code style, it is possible to use the `if(...)` poincut to define a | |||
conditional pointcut expression which will be evaluated at runtime for | |||
@@ -255,7 +255,7 @@ The special forms `if(true)` and `if(false)` can be used in a more | |||
general way and don't imply that the pointcut method must have a body. | |||
You can thus write `@Before("somePoincut() && if(false)")` . | |||
==== Advice | |||
=== Advice | |||
In this section we first discuss the use of annotations for simple | |||
advice declarations. Then we show how `thisJoinPoint` and its siblings | |||
@@ -485,7 +485,7 @@ above aren't obeyed, then it will unfortunately manifest as a runtime | |||
error. | |||
[[ataspectj-itds]] | |||
=== Inter-type Declarations | |||
== Inter-type Declarations | |||
Inter-type declarations are challenging to support using an annotation | |||
style. For code style aspects compiled with the _ajc_ compiler, the entire | |||
@@ -521,7 +521,7 @@ The `defaultImpl` attribute of `@DeclareParents` may become deprecated if | |||
introduce a marker interface. | |||
[[atDeclareParents]] | |||
==== @DeclareParents | |||
=== @DeclareParents | |||
Consider the following aspect: | |||
@@ -641,7 +641,7 @@ If the interface defines one or more operations, and these are not | |||
implemented by the target type, an error will be issued during weaving. | |||
[[atDeclareMixin]] | |||
==== @DeclareMixin | |||
=== @DeclareMixin | |||
Consider the following aspect: | |||
@@ -793,7 +793,7 @@ Any annotations defined on the interface methods are also put upon the | |||
delegate forwarding methods created in the matched target type. | |||
[[ataspectj-declare]] | |||
=== Declare statements | |||
== Declare statements | |||
The previous section on inter-type declarations covered the case of | |||
`declare parents ...` implements. The 1.5.0 release of AspectJ 5 does not | |||
@@ -865,7 +865,7 @@ static String getMessage() { | |||
.... | |||
[[ataspectj-aspectof]] | |||
=== `aspectOf()` and `hasAspect()` methods | |||
== `aspectOf()` and `hasAspect()` methods | |||
A central part of AspectJ's programming model is that aspects written | |||
using the code style and compiled using ajc support `aspectOf` and |
@@ -1,8 +1,8 @@ | |||
[[autoboxing]] | |||
== Autoboxing and Unboxing | |||
= Autoboxing and Unboxing | |||
[[boxing-inJava5]] | |||
=== Autoboxing and Unboxing in Java 5 | |||
== Autoboxing and Unboxing in Java 5 | |||
Java 5 (and hence AspectJ 1.5) supports automatic conversion of | |||
primitive types (`int`, `float`, `double` etc.) to their object equivalents | |||
@@ -23,7 +23,7 @@ Integer i2 = 5; // autoboxing | |||
.... | |||
[[autoboxing-in-aspectj5]] | |||
=== Autoboxing and Join Point matching in AspectJ 5 | |||
== Autoboxing and Join Point matching in AspectJ 5 | |||
Most of the pointcut designators match based on signatures, and hence | |||
are unaffected by autoboxing. For example, a call to a method | |||
@@ -63,7 +63,7 @@ before(Integer i) : foo(i) { | |||
.... | |||
[[autoboxing-and-method-dispatch]] | |||
=== Inter-type method declarations and method dispatch | |||
== Inter-type method declarations and method dispatch | |||
Autoboxing, unboxing, and also varargs all affect the method dispatch | |||
algorithm used in Java 5. In AspectJ 5, the target method of a call is |
@@ -1,7 +1,7 @@ | |||
== Covariance | |||
= Covariance | |||
[[covariance-inJava5]] | |||
=== Covariance in Java 5 | |||
== Covariance in Java 5 | |||
Java 5 (and hence AspectJ 5) allows you to narrow the return type in an | |||
overriding method. For example: | |||
@@ -19,7 +19,7 @@ class B extends A { | |||
.... | |||
[[covariance-and-join-point-matching]] | |||
=== Covariant methods and Join Point matching | |||
== Covariant methods and Join Point matching | |||
The join point matching rules for `call` and `execution` pointcut | |||
designators are extended to match against covariant methods. |
@@ -1,8 +1,8 @@ | |||
[[enumeratedtypes]] | |||
== Enumerated Types | |||
= Enumerated Types | |||
[[enums-in-java5]] | |||
=== Enumerated Types in Java 5 | |||
== Enumerated Types in Java 5 | |||
Java 5 (and hence AspectJ 5) provides explicit support for enumerated | |||
types. In the simplest case, you can declare an enumerated type as | |||
@@ -24,7 +24,7 @@ Enumerated types in Java 5 all implicitly extend the type | |||
class. | |||
[[enums-in-aspectj5]] | |||
=== Enumerated Types in AspectJ 5 | |||
== Enumerated Types in AspectJ 5 | |||
AspectJ 5 supports the declaration of enumerated types just as Java 5 | |||
does. Because of the special restrictions Java 5 places around |
@@ -1,14 +1,14 @@ | |||
== Generics | |||
= Generics | |||
[[generics-inJava5]] | |||
=== Generics in Java 5 | |||
== Generics in Java 5 | |||
This section provides the essential information about generics in Java 5 | |||
needed to understand how generics are treated in AspectJ 5. For a full | |||
introduction to generics in Java, please see the documentation for the | |||
Java 5 SDK. | |||
==== Declaring Generic Types | |||
=== Declaring Generic Types | |||
A generic type is declared with one or more type parameters following | |||
the type name. By convention formal type parameters are named using a | |||
@@ -57,7 +57,7 @@ Some examples follow: | |||
with a type that is a subtype of `Number` and that implements | |||
`Comparable`. | |||
==== Using Generic and Parameterized Types | |||
=== Using Generic and Parameterized Types | |||
You declare a variable (or a method/constructor argument) of a | |||
parameterized type by specifying a concrete type specfication for each | |||
@@ -132,7 +132,7 @@ more parameterized interfaces (for example, | |||
time be a subtype of two interface types which are different | |||
parameterizations of the same interface. | |||
==== Subtypes, Supertypes, and Assignability | |||
=== Subtypes, Supertypes, and Assignability | |||
The supertype of a generic type `C` is the type given in the extends | |||
clause of `C`, or `Object` if no extends clause is present. Given the | |||
@@ -163,7 +163,7 @@ example, `List<String>` can be assigned to a variable of type | |||
`Collection<?>`, and `List<Double>` can be assigned to a variable of | |||
type `List<? extends Number>`. | |||
==== Generic Methods and Constructors | |||
=== Generic Methods and Constructors | |||
A static method may be declared with one or more type parameters as in | |||
the following declaration: | |||
@@ -186,7 +186,7 @@ in a similar fashion: | |||
The same technique can be used to declare a generic constructor. | |||
==== Erasure | |||
=== Erasure | |||
Generics in Java are implemented using a technique called _erasure_. All | |||
type parameter information is erased from the run-time type system. | |||
@@ -196,7 +196,7 @@ of type `List<String>`. A consequence of this is that you cannot at | |||
runtime ask if an object is an `instanceof` a parameterized type. | |||
[[generics-inAspectJ5]] | |||
=== Generics in AspectJ 5 | |||
== Generics in AspectJ 5 | |||
AspectJ 5 provides full support for all of the Java 5 language features, | |||
including generics. Any legal Java 5 program is a legal AspectJ 5 | |||
@@ -205,7 +205,7 @@ parameterized types in pointcuts, inter-type declarations, and declare | |||
statements. Parameterized types may freely be used within aspect | |||
members, and support is also provided for generic _abstract_ aspects. | |||
==== Matching generic and parameterized types in pointcut expressions | |||
=== Matching generic and parameterized types in pointcut expressions | |||
The simplest way to work with generic and parameterized types in | |||
pointcut expressions and type patterns is simply to use the raw type | |||
@@ -273,7 +273,7 @@ respectively. The members of the generic type `G` can be matched by a | |||
signature pattern matching `Object G.myData` and | |||
`public List G.getAllDataItems()` respectively. | |||
===== Restricting matching using parameterized types | |||
==== Restricting matching using parameterized types | |||
Pointcut matching can be further restricted to match only given | |||
parameterizations of parameter types (methods and constructors), return | |||
@@ -337,7 +337,7 @@ The execution of `foo` can be matched by `execution(List foo(List))`, | |||
`execution(List<Object> foo(List<String>>)` since the erasure of | |||
`List<T>` is `List` and not `List<Object>`. | |||
===== Generic wildcards and signature matching | |||
==== Generic wildcards and signature matching | |||
When it comes to signature matching, a type parameterized using a | |||
generic wildcard is a distinct type. For example, `List<?>` is a very | |||
@@ -365,7 +365,7 @@ class C { | |||
matches both the execution of `foo` and the execution of `bar` since | |||
the upper bound of `List<?>` is implicitly `Object`. | |||
===== Treatment of bridge methods | |||
==== Treatment of bridge methods | |||
Under certain circumstances a Java 5 compiler is required to create | |||
_bridge methods_ that support the compilation of programs using raw | |||
@@ -422,7 +422,7 @@ Object n = new Integer(5); | |||
rawType.foo(n); // call to bridge method that would succeed at runtime | |||
.... | |||
===== Runtime type matching with this(), target() and args() | |||
==== Runtime type matching with this(), target() and args() | |||
The `this()`, `target()`, and `args()` pointcut expressions all match | |||
based on the runtime type of their arguments. Because Java 5 implements | |||
@@ -591,7 +591,7 @@ aspect A { | |||
} | |||
.... | |||
===== Binding return values in after returning advice | |||
==== Binding return values in after returning advice | |||
After returning advice can be used to bind the return value from a | |||
matched join point. AspectJ 5 supports the use of a parameterized type | |||
@@ -651,7 +651,7 @@ executes on lists _statically determinable_ to be of the right type by | |||
specifying a return type pattern in the associated pointcut. The | |||
`@SuppressAjWarnings` annotation can also be used if desired. | |||
===== Declaring pointcuts inside generic types | |||
==== Declaring pointcuts inside generic types | |||
Pointcuts can be declared in both classes and aspects. A pointcut | |||
declared in a generic type may use the type variables of the type in | |||
@@ -692,7 +692,7 @@ public aspect A { | |||
} | |||
.... | |||
==== Inter-type Declarations | |||
=== Inter-type Declarations | |||
AspectJ 5 supports the inter-type declaration of generic methods, and of | |||
members on generic types. For generic methods, the syntax is exactly as | |||
@@ -743,7 +743,7 @@ declare a member on behalf of (say) `Bar<String>`, you can only declare | |||
members on the generic type `Bar<T>`. | |||
[[declare-parents-java5]] | |||
==== Declare Parents | |||
=== Declare Parents | |||
Both generic and parameterized types can be used as the parent type in a | |||
`declare parents` statement (as long as the resulting type hierarchy | |||
@@ -758,14 +758,14 @@ statement. | |||
since a type cannot implement multiple parameterizations of the same | |||
generic interface type. | |||
==== Declare Soft | |||
=== Declare Soft | |||
It is an error to use a generic or parameterized type as the softened | |||
exception type in a declare soft statement. Java 5 does not permit a | |||
generic class to be a direct or indirect subtype of `Throwable` (JLS | |||
8.1.2). | |||
==== Generic Aspects | |||
=== Generic Aspects | |||
AspectJ 5 allows an _abstract_ aspect to be declared as a generic type. | |||
Any concrete aspect extending a generic abstract aspect must extend a |
@@ -1,9 +1,9 @@ | |||
[[grammar]] | |||
== A Grammar for the AspectJ 5 Language | |||
= A Grammar for the AspectJ 5 Language | |||
[source, text] | |||
.... | |||
=== type patterns === | |||
== type patterns === | |||
TypePattern := | |||
SimpleTypePattern | | |||
@@ -26,13 +26,13 @@ NotStarNamePattern := | |||
FullyQualifiedName := JavaIdentifierCharacter+ ('.' JavaIdentifierCharacter+)* | |||
=== annotation patterns === | |||
== annotation patterns === | |||
AnnotationPattern := '!'? '@' AnnotationTypePattern AnnotationPattern* | |||
AnnotationTypePattern := FullyQualifiedName | '(' TypePattern ')' | |||
=== signature patterns === | |||
== signature patterns === | |||
-- field -- | |||
@@ -88,7 +88,7 @@ ConstructorModifiersPattern := | |||
ConstructorModifier := 'public' | 'private' | 'protected' | |||
=== Pointcuts === | |||
== Pointcuts === | |||
PointcutPrimitive := | |||
Call | Execution | Get | Set | Handler | | |||
@@ -174,19 +174,19 @@ PointcutExpression := | |||
PointcutExpression '&&' PointcutExpression | | |||
PointcutExpression '||' PointcutExpression | |||
=== Advice === | |||
== Advice === | |||
to be written... | |||
=== Inter-type Declarations === | |||
== Inter-type Declarations === | |||
to be written... | |||
=== Declare Statements === | |||
== Declare Statements === | |||
to be written... | |||
=== Aspects === | |||
== Aspects === | |||
to be written... | |||
.... |
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ 5 Development Kit Developer's Notebook | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -1,5 +1,5 @@ | |||
[[jpsigs]] | |||
== Join Point Signatures | |||
= Join Point Signatures | |||
Many of the extensions to the AspectJ language to address the new | |||
features of Java 5 are derived from a simple set of principles for join | |||
@@ -7,7 +7,7 @@ point matching. In this section, we outline these principles as a | |||
foundation for understanding the matching rules in the presence of | |||
annotations, generics, covariance, varargs, and autoboxing. | |||
=== Join Point Matching | |||
== Join Point Matching | |||
AspectJ supports 11 different kinds of join points. These are the | |||
`method call, method execution, constructor call, constructor execution, field get, | |||
@@ -48,7 +48,7 @@ describe what the signature(s) of a join point are, and what the | |||
subjects of join points are. | |||
[[join-point-signatures]] | |||
=== Join Point Signatures | |||
== Join Point Signatures | |||
Call, execution, get, and set join points may potentially have multiple | |||
signatures. All other join points have exactly one signature. The | |||
@@ -88,7 +88,7 @@ has the same id and field type, but the declaring type may vary. | |||
The following sections examine signatures for these join points in more | |||
detail. | |||
==== Method call join point signatures | |||
=== Method call join point signatures | |||
For a call join point where a call is made to a method | |||
`m(parameter_types)` on a target type `T` (where `T` is the static type | |||
@@ -147,7 +147,7 @@ call `t.m("hello")`. Thus this call join point has four signatures in | |||
total. Every signature has the same id and parameter types, and a | |||
different declaring type. | |||
==== Method execution join point signatures | |||
=== Method execution join point signatures | |||
Join point signatures for execution join points are defined in a similar | |||
manner to signatures for call join points. Given the hierarchy: | |||
@@ -190,7 +190,7 @@ own declaration of the method. Hence in this example there is no | |||
signature `R' T.m(String)` as `T` does not provide its own declaration | |||
of the method. | |||
==== Field get and set join point signatures | |||
=== Field get and set join point signatures | |||
For a field get join point where an access is made to a field `f` of | |||
type `F` on a object with declared type `T`, then `F T.f` is a signature | |||
@@ -226,7 +226,7 @@ F T.f | |||
The signatures for a field set join point are derived in an identical | |||
manner. | |||
=== Join Point Modifiers | |||
== Join Point Modifiers | |||
Every join point has a single set of modifiers - these include the | |||
standard Java modifiers such as `public, private, | |||
@@ -280,11 +280,11 @@ public class Y extends X { | |||
} | |||
.... | |||
Then the modifiers for a call to `(Y y) y.doIt()` are simply `{public}`. | |||
The modifiers for a call to `(X x) x.doIt()` are `{@Foo,protected}`. | |||
Then the modifiers for a call to `(Y y) y.doIt()` are simply `{ public }`. | |||
The modifiers for a call to `(X x) x.doIt()` are `{ @Foo, protected }`. | |||
[[join-point-matching-summary]] | |||
=== Summary of Join Point Matching | |||
== Summary of Join Point Matching | |||
A join point has potentially multiple signatures, but only one set of | |||
modifiers. _A kinded primitive pointcut matches a particular join point |
@@ -1,8 +1,8 @@ | |||
[[ltw]] | |||
== Load-Time Weaving | |||
= Load-Time Weaving | |||
[[ltw-introduction]] | |||
=== Introduction | |||
== Introduction | |||
See xref:../devguide/ltw.adoc#ltw[Developer's Guide] for information on | |||
load-time weaving support in AspectJ 5. |
@@ -1,8 +1,8 @@ | |||
[[miscellaneous]] | |||
== Other Changes in AspectJ 5 | |||
= Other Changes in AspectJ 5 | |||
[[pointcuts-change]] | |||
=== Pointcuts | |||
== Pointcuts | |||
AspectJ 5 is more liberal than AspectJ 1.2.1 in accepting pointcut | |||
expressions that bind context variables in more than one location. For | |||
@@ -22,7 +22,7 @@ for instance, no join point can be both an execution join point and a | |||
set join point so the two branches are mutually exclusive. | |||
[[declare-soft-change]] | |||
=== Declare Soft | |||
== Declare Soft | |||
The semantics of the `declare soft` statement have been refined in | |||
AspectJ 5 to only soften exceptions that are not already runtime |
@@ -1,5 +1,5 @@ | |||
[[pertypewithin]] | |||
== The `pertypewithin` Aspect Instantiation Model | |||
= The `pertypewithin` Aspect Instantiation Model | |||
AspectJ 5 defines a new per-clause type for aspect instantiation: | |||
`pertypewithin`. Unlike the other per-clauses, `pertypewithin` takes a |
@@ -1,5 +1,5 @@ | |||
[[reflection]] | |||
== New Reflection Interfaces | |||
= New Reflection Interfaces | |||
AspectJ 5 provides a full set of reflection APIs analogous to the | |||
`java.lang.reflect` package, but fully aware of the AspectJ type system. | |||
@@ -8,7 +8,7 @@ reflection APIs are only supported when running under Java 5 and for | |||
code compiled by the AspectJ 5 compiler at target level 1.5. | |||
[[reflection_api]] | |||
=== Using `AjTypeSystem` | |||
== Using `AjTypeSystem` | |||
The starting point for using the reflection apis is | |||
`org.aspectj.lang.reflect.AjTypeSystem` which provides the method |
@@ -1,7 +1,7 @@ | |||
== Varargs | |||
= Varargs | |||
[[varargs-inJava5]] | |||
=== Variable-length Argument Lists in Java 5 | |||
== Variable-length Argument Lists in Java 5 | |||
Java 5 (and hence AspectJ 5) allows you to specify methods that take a | |||
variable number of arguments of a specified type. This is achieved using | |||
@@ -15,7 +15,7 @@ public void foo(int i, String... strings) {} | |||
A method or constructor may take at most one variable length argument, | |||
and this must always be the last declared argument in the signature. | |||
==== Calling Methods and Constructors with variable-length arguments | |||
=== Calling Methods and Constructors with variable-length arguments | |||
A _varargs_ method may be called with zero or more arguments in the | |||
variable argument position. For example, given the definition of `foo` | |||
@@ -49,7 +49,7 @@ foo(7,new String[] {"One String","Two Strings"}); | |||
.... | |||
[[varargs-in-pcds]] | |||
=== Using Variable-length arguments in advice and pointcut expressions | |||
== Using Variable-length arguments in advice and pointcut expressions | |||
AspectJ 5 allows variable-length arguments to be used for methods | |||
declared within aspects, and for inter-type declared methods and | |||
@@ -59,7 +59,7 @@ section. | |||
AspectJ 5 also allows variable length arguments to be matched by | |||
pointcut expressions and bound as formals in advice. | |||
==== Matching signatures based on variable length argument types | |||
=== Matching signatures based on variable length argument types | |||
Recall from the definition of signature patterns given in the chapter on | |||
annotations (xref:annotations.adoc#signaturePatterns[Signature Patterns]), that `MethodPattern` and | |||
@@ -109,7 +109,7 @@ point for `foo`, but not `bar`. The pointcut | |||
`execution(* *.*(String[]))` matches the execution join point for `bar` | |||
but not `foo`. | |||
==== Exposing variable-length arguments as context in pointcuts and advice | |||
=== Exposing variable-length arguments as context in pointcuts and advice | |||
When a varargs parameter is used within the body of a method, it has an | |||
array type, as discussed in the introduction to this section. We follow |
@@ -113,7 +113,7 @@ Guide. | |||
### Command line | |||
If you wish to install AspectJ in a separate directory and use it from the command line without any extra build tools, | |||
feel free to download the **AspectJ installer**. It is and executable JAR installer. It requires Java and possibly admin | |||
feel free to download the **AspectJ installer**. It is an executable JAR installer, requires Java and possibly admin | |||
rights, if e.g. under Windows you want to install AspectJ to _C:/Program Files/AspectJ_. You execute it from a command | |||
prompt via `java -jar installer-<version>.jar` and select your installation options. Then you add `<ASPECTJ_HOME>/bin` | |||
to your path and are good to go. You can now call tools like the Aspectj compiler `ajc` or the AspectJ documentation |
@@ -1,4 +1,8 @@ | |||
== Guide for Developers of the AspectJ Compiler and Weaver | |||
= Guide for Developers of the AspectJ Compiler and Weaver | |||
:doctype: book | |||
:leveloffset: +1 | |||
= Guide for Developers of the AspectJ Compiler and Weaver | |||
_Latest (non-license) content update: 2004-02-20 by jhugunin_ | |||
@@ -36,7 +40,7 @@ weaving API which can be used to implement ClassLoaders that will weave | |||
advice into classes dynamically as they are loaded by the virtual | |||
machine. | |||
=== Compiler front-end (org.aspectj.ajdt.core) | |||
== Compiler front-end (org.aspectj.ajdt.core) | |||
The front-end of the AspectJ compiler is implemented as an extension of | |||
the Java compiler from eclipse.org. The source-file portion of the | |||
@@ -61,7 +65,7 @@ binding and some AspectJ augmentation | |||
. For each source file do a deep parse, annotation/analysis, and then | |||
code generation | |||
==== Top-level parse tree | |||
=== Top-level parse tree | |||
Let's trace the following example program through the compiler. | |||
@@ -96,7 +100,7 @@ When parsed, this program will produce the following tree. | |||
image:images/top-tree.png[image] | |||
==== PointcutDeclaration processing | |||
=== PointcutDeclaration processing | |||
Let's look more closely at the pointcut declaration: | |||
@@ -112,7 +116,7 @@ declaration. The actual pointcut is parsed by the weaver module. This | |||
parsing happens as part of the shallow parse phase. This is because this | |||
information might be needed to implement a declare soft. | |||
==== AdviceDeclaration processing | |||
=== AdviceDeclaration processing | |||
Next we look at the processing for an advice declaration: | |||
@@ -138,13 +142,13 @@ advice is still null. This field is not filled in until the second stage | |||
of the compiler when full parsing is done on each source file as a | |||
prelude to generating the classfile. | |||
==== Overview of the main classes in org.aspectj.ajdt.core | |||
=== Overview of the main classes in org.aspectj.ajdt.core | |||
The main classes in this module are shown in the following diagram: | |||
image:images/ajdt-uml.png[image] | |||
=== Weaving back-end (weaver) | |||
== Weaving back-end (weaver) | |||
This provides all of the weaving functionality. It has very few | |||
dependencies to keep the code as small as possible for deployment in | |||
@@ -174,7 +178,7 @@ static shadow. If it could match, it inserts a call to the advice’s | |||
implementation method guarded by any dynamic testing needed to ensure | |||
the match. | |||
=== Runtime support library (runtime) | |||
== Runtime support library (runtime) | |||
This library provides classes that are used by the generated code at | |||
runtime. These are the only classes that must be redistributed with a | |||
@@ -191,7 +195,7 @@ There are also several packages all under the header org.aspectj.runtime | |||
that are considered private to the implementation and may only be used | |||
by code generated by the AspectJ compiler. | |||
=== Mappings from AspectJ language to implementation | |||
== Mappings from AspectJ language to implementation | |||
[cols=",,",] | |||
|=== | |||
@@ -222,7 +226,7 @@ patterns.DeclareErrorOrWarning | |||
|pcd |ast.PointcutDesignator |patterns.Pointcut hierarchy | |||
|=== | |||
== Tutorial: implementing a throw join point | |||
= Tutorial: implementing a throw join point | |||
This tutorial will walk step-by-step through the process of adding a new | |||
join point to AspectJ for the moment when an exception is thrown. In | |||
@@ -237,14 +241,14 @@ size of your actual code changes will likely be smaller, but you are | |||
likely to need to be familiar with all of the pieces of the | |||
implementation described below. | |||
=== Part 1: Adding the join point and corresponding pcd | |||
== Part 1: Adding the join point and corresponding pcd | |||
The first part of this tutorial will implement the main features of the | |||
throw join point. We will create a new join point shadow corresponding | |||
to the athrow instruction and also create a new pointcut designator | |||
(pcd) for matching it. | |||
==== Step 1. Synchronize with repository and run the existing test suite | |||
=== Step 1. Synchronize with repository and run the existing test suite | |||
Do a Team->Synchronize With Repository and make sure that your tree is | |||
completely in sync with the existing repository. Make sure to address | |||
@@ -261,7 +265,7 @@ Run the existing test suite. I currently do this in four steps: | |||
There should be no failures when you run these tests. If there are | |||
failures, resolve them with the AspectJ developers before moving on. | |||
==== Step 2. Write a proto test case | |||
=== Step 2. Write a proto test case | |||
{empty}a. Create a new file in tests/design/pcds/Throw.java | |||
@@ -315,7 +319,7 @@ about to execute: call(java.lang.RuntimeException(String)) | |||
PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds | |||
.... | |||
==== Step 3. Implement the new join point shadow kind | |||
=== Step 3. Implement the new join point shadow kind | |||
Modify runtime/org.aspectj.lang/JoinPoint.java to add a name for the | |||
Throw shadow kind. | |||
@@ -362,7 +366,7 @@ Shadow.Kind. | |||
case 12: return Throw; | |||
.... | |||
==== Step 4. Create this new kind of joinpoint for the throw bytecode | |||
=== Step 4. Create this new kind of joinpoint for the throw bytecode | |||
Modify weaver/org.aspectj.weaver.bcel/BcelClassWeaver.java to recognize | |||
this new joinpoint kind. In the method | |||
@@ -450,7 +454,7 @@ we used Member.HANDLER for the kind of the signature of this join point. | |||
That's clearly not correct. We'll fix that at the end of the lesson as | |||
part of the clean-up. For now, let's go on with the interesting parts. | |||
==== Step 5. Extend our proto-test to use a pointcut designator for matching | |||
=== Step 5. Extend our proto-test to use a pointcut designator for matching | |||
Add a second piece of before advice to the test aspect A: | |||
@@ -481,7 +485,7 @@ any existing programs that use throw as the name for a user-defined PCD. | |||
Fortunately because throw is a Java keyword this particular change is | |||
very safe. | |||
==== Step 6. Extend the PCD parser to handle this new primitive PCD | |||
=== Step 6. Extend the PCD parser to handle this new primitive PCD | |||
Modify the parseSinglePointcut method in | |||
weaver/org.aspectj.weaver.patterns/PatternParser.java to add one more | |||
@@ -526,7 +530,7 @@ Make sure that you see the 'about to throw' printed before moving on. | |||
This shows that the throw PCD is now successfully matching the throw | |||
join point shadow we added earlier. | |||
==== Step 7. Check that we're properly providing the single thrown argument (and clean-up the test) | |||
=== Step 7. Check that we're properly providing the single thrown argument (and clean-up the test) | |||
Now that we have a valid pcd for this advice, we can simplify our test | |||
case. Modify our test aspect A to be the following. In addition to | |||
@@ -557,7 +561,7 @@ a new join point to the AspectJ language and a corresponding PCD to | |||
match it. This is a good time to take a break before moving on to part | |||
two. | |||
=== Part 2: Getting the signature of this new join point right | |||
== Part 2: Getting the signature of this new join point right | |||
We know that throw(catch(Throwable)) is not the right thing to be | |||
printing for the signature at this join point. What is the correct | |||
@@ -601,7 +605,7 @@ allow dynamic matching in args to select more specific types. In | |||
general, good AspectJ code should use this dynamic matching anyway to | |||
correspond to good OO designs. | |||
==== Step 1. Change the signature of the throw pcd | |||
=== Step 1. Change the signature of the throw pcd | |||
Since we aren't going to recover the static type of the exception | |||
thrown, we need to fix the parser for the throw pcd to remove this | |||
@@ -683,7 +687,7 @@ passing: | |||
PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds | |||
.... | |||
==== Part 2. Make a real test case | |||
=== Part 2. Make a real test case | |||
The pass result from running our test should worry you. Unlike previous | |||
runs, this test run doesn't show the output from our System.out.println | |||
@@ -734,7 +738,7 @@ we're not matching the throw join point anymore. | |||
FAIL Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 failed) 1 seconds | |||
.... | |||
==== Step 3. Fix signature matching again | |||
=== Step 3. Fix signature matching again | |||
In org.aspectj.weaver.patterns.SignaturePattern.matches, we need to | |||
handle throw signature matching the same way we handle advice signature | |||
@@ -777,7 +781,7 @@ Member.THROW. This problem only shows up when we try to print | |||
thisJoinPoint. It's showing that we haven't updated the reflection API | |||
to understand this new signature kind. | |||
==== Step 4. Extend org.aspectj.lang.reflect to understand throw signatures | |||
=== Step 4. Extend org.aspectj.lang.reflect to understand throw signatures | |||
We need to add a couple of classes to the reflection API to implement | |||
the throw signature. Because we decided at the beginning of this section | |||
@@ -906,7 +910,7 @@ about to throw: 'java.lang.RuntimeException: expected exception' at throw(throw) | |||
PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 1 seconds | |||
.... | |||
==== Step 5. Extend the test for automated coverage of reflection | |||
=== Step 5. Extend the test for automated coverage of reflection | |||
Modify the before advice to include at least minimal checks of the new | |||
reflective information: | |||
@@ -927,14 +931,14 @@ working version of the throw join point and there are no obvious pieces | |||
that we've skipped. Take a break before proceeding to the final phase of | |||
tests. | |||
=== Part 3: More serious testing | |||
== Part 3: More serious testing | |||
Now it's time to get a decent testing story. The test work that we will | |||
do here is probably too little for adding a new join point to the | |||
aspectj language; however, it should at least give you a sense of what's | |||
involved. | |||
==== Step 1. Run the test suite again | |||
=== Step 1. Run the test suite again | |||
Rerun the tests you ran at the beginning of part 1. Any failures that | |||
occur should be resolved at this point. At the time of writing this | |||
@@ -972,7 +976,7 @@ noted in the release notes for any AspectJ release. Since we're not | |||
writing documentation in this tutorial, we will move on an fix the test | |||
case. | |||
==== Step 2. Fix the failing test case | |||
=== Step 2. Fix the failing test case | |||
Now we need to fix this failing test case. The first step is to copy the | |||
test specification into our local myTests.xml file. The easiest way to | |||
@@ -1001,7 +1005,7 @@ new expected event between these two: | |||
Run the test suite again to see that this test now passes. | |||
==== Step 3. Extend test coverage to after advice | |||
=== Step 3. Extend test coverage to after advice | |||
There is a lot we should do now to extend test coverage for this new | |||
kind of join point. For the purpose of this tutorial, we're just going | |||
@@ -1060,7 +1064,7 @@ property of the orthogonality of the implementation of join points and | |||
advice. We never had to do any implementation work to make our new join | |||
point kind work for before and all three kinds of after advice. | |||
==== Step 4. Look at around advice on throw join points | |||
=== Step 4. Look at around advice on throw join points | |||
Let's create a new test case to see how this new join point interacts | |||
with around advice. | |||
@@ -1120,7 +1124,7 @@ best design. For the purpose of this tutorial we're once again going to | |||
make the language design choice that is easiest to implement and press | |||
on. | |||
==== Step 5. Prohibit around advice on this new join point kind | |||
=== Step 5. Prohibit around advice on this new join point kind | |||
The easiest solution to implement is to prohibit around advice on throw | |||
join points. There are already a number of these kinds of rules | |||
@@ -1169,7 +1173,7 @@ following specification: | |||
Run myTests.xml one last time to see both tests passing. | |||
==== Step 6. Final preparations for a commit or patch | |||
=== Step 6. Final preparations for a commit or patch | |||
You probably want to stop here for the purposes of this tutorial. We've | |||
pointed out several language design decisions that would need to be |
@@ -1,5 +1,6 @@ | |||
= AspectJ Design Overview | |||
:doctype: book | |||
:leveloffset: +1 | |||
Here are some sobering words: | |||
@@ -1,5 +1,6 @@ | |||
= AspectJ Design Overview | |||
:doctype: book | |||
:leveloffset: +1 | |||
Here are some sobering words: | |||
@@ -1,6 +1,6 @@ | |||
== AspectJ Language Design | |||
= AspectJ Language Design | |||
=== User-suggested New Language Features | |||
== User-suggested New Language Features | |||
* `-` wildcard | |||
** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00717.html | |||
@@ -13,9 +13,9 @@ | |||
** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00458.html | |||
** https://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00467.html + | |||
=== Key Language Design Properties | |||
== Key Language Design Properties | |||
==== Orthogonal join point model | |||
=== Orthogonal join point model | |||
The different kinds of join | |||
points, the different primitive pointcuts, and the different kinds of | |||
@@ -25,7 +25,7 @@ This was one of the hardest parts of the design to get right, because of | |||
the "constructor must call super" rule in Java. But we finally got this | |||
in 1.0. | |||
==== Pointcuts support composition and abstraction | |||
=== Pointcuts support composition and abstraction | |||
Abelson and Sussman | |||
say that composition and abstraction are the key elements of a real | |||
@@ -45,18 +45,18 @@ pointcut topLevelStateChange(): stateChange() && !cflowbelow(stateChange()); | |||
is what makes it possible for people to really work with crosscutting | |||
structure and make their code more clear. | |||
==== Statically type checked | |||
=== Statically type checked | |||
The efficiency, code quality and programmer | |||
productivity arguments for this have been made elsewhere, so I won't | |||
repeat them. | |||
==== Efficient | |||
=== Efficient | |||
AspectJ code is as fast as the equivalent functionality, | |||
written by hand, in a scattered and tangled way. | |||
==== Simple kernel | |||
=== Simple kernel | |||
I've heard some people say that AspectJ is too big | |||
and too complex. In the most important sense of simple AspectJ is | |||
@@ -69,7 +69,7 @@ the right idea for a standard AOP API | |||
is this kernel, packaged in a way that allows building more | |||
sophisticated tools on top of it. | |||
==== Supports multiple weave times | |||
=== Supports multiple weave times | |||
AspectJ is neutral on whether weaving | |||
happens at pre-process, compile, post-process, load, JIT or runtime. |
@@ -1,10 +1,10 @@ | |||
== AspectJ Modules | |||
= AspectJ Modules | |||
There are a number of different structures [Parnas]: "the module structure, the uses structure, the runtime structure, | |||
..." This document overviews module structure and summarizes what is hidden by each. For detailed documentation refer to | |||
the individual module sources and docs available via CVS. | |||
=== Core Modules | |||
== Core Modules | |||
*CVS Location:* dev.eclipse.org:/cvsroot/technology/org.aspectj/modules | |||
@@ -50,7 +50,7 @@ bytecode toolkit. All advice planning and weaving is done here. Takes an aspect | |||
classfiles as input. | |||
|=== | |||
=== Supporting Modules | |||
== Supporting Modules | |||
*CVS Location:* dev.eclipse.org:/cvsroot/technology/org.aspectj/modules | |||
@@ -66,7 +66,7 @@ classfiles as input. | |||
| tests | AspectJ test suite, including all language tests, regression tests, and test system sources | |||
|=== | |||
=== Eclipse AspectJ Development Tools (AJDT) | |||
== Eclipse AspectJ Development Tools (AJDT) | |||
*CVS Location:* dev.eclipse.org:/cvsroot/technology/org.eclipse.ajdt/plugins/org.eclipse.ajdt | |||
@@ -1,16 +1,16 @@ | |||
== `aj`, the AspectJ load-time weaving launcher | |||
= `aj`, the AspectJ load-time weaving launcher | |||
=== Name | |||
== Name | |||
`aj` - command-line launcher for basic load-time weaving | |||
=== Synopsis | |||
== Synopsis | |||
[subs=+quotes] | |||
aj [_Options_] [_arg_...] | |||
[[aj]] | |||
=== Description | |||
== Description | |||
The `aj` command runs Java programs in Java 1.4 or later by setting up | |||
`WeavingURLClassLoader` as the system class loader, to do load-time | |||
@@ -23,7 +23,7 @@ Users should define the environment variables `CLASSPATH` and | |||
For more information and alternatives for load-time weaving, see | |||
xref:ltw.adoc#ltw[Load-Time Weaving]. | |||
=== Examples | |||
== Examples | |||
Use ajc to build a library, then weave at load time | |||
@@ -1,16 +1,16 @@ | |||
[[ajc]] | |||
== `ajc`, the AspectJ compiler/weaver | |||
= `ajc`, the AspectJ compiler/weaver | |||
=== Name | |||
== Name | |||
`ajc` - compiler and bytecode weaver for the AspectJ and Java languages | |||
=== Synopsis | |||
== Synopsis | |||
[subs=+quotes] | |||
ajc [_option_...] [_file_... | @_file_... | -argfile _file_...] | |||
=== Description | |||
== Description | |||
The `ajc` command compiles and weaves AspectJ and Java source and .class | |||
files, producing .class files compliant with any Java VM (1.1 or later). | |||
@@ -28,7 +28,7 @@ include the source not only for the aspects or pointcuts but also for | |||
any affected types. Specifying all sources is necessary because, unlike | |||
javac, ajc does not search the sourcepath for classes. (For a discussion | |||
of what affected types might be required, see | |||
xref:../progguide/implementation.html[The AspectJ Programming Guide, | |||
xref:../progguide/implementation.adoc[The AspectJ Programming Guide, | |||
Implementation Appendix].) | |||
To specify sources, you can list source files as arguments or use the | |||
@@ -38,7 +38,7 @@ which source is correct. (This happens most often when users include the | |||
destination directory on the inpath and rebuild.) | |||
[[ajc_options]] | |||
==== Options | |||
=== Options | |||
`-injars <JarList>`:: | |||
deprecated: since 1.2, use -inpath, which also takes directories. | |||
@@ -91,7 +91,7 @@ destination directory on the inpath and rebuild.) | |||
Generate .ajesym symbol files for emacs support (deprecated). | |||
`-Xlint`:: | |||
Same as -Xlint:warning (enabled by default) | |||
`-Xlint:{level}`:: | |||
`-Xlint:\{level}`:: | |||
Set default level for messages about potential programming mistakes in | |||
crosscutting code. \{level} may be ignore, warning, or error. This | |||
overrides entries in org/aspectj/weaver/XlintDefault.properties from | |||
@@ -227,7 +227,7 @@ none suppress all compiler warnings | |||
(Experimental) Allows code to be generated that targets a 1.2 or a 1.5 | |||
level AspectJ runtime (default 1.5) | |||
==== File names | |||
=== File names | |||
ajc accepts source files with either the `.java` extension or the `.aj` | |||
extension. We normally use `.java` for all of our files in an AspectJ | |||
@@ -247,7 +247,7 @@ can create an artificial need for privileged aspects. Instead of adding | |||
a sub-package like `aspects` we recommend using the `.aj` extension and | |||
including these files in your existing packages instead. | |||
==== Compatibility | |||
=== Compatibility | |||
AspectJ is a compatible extension to the Java programming language. The | |||
AspectJ compiler adheres to the | |||
@@ -259,7 +259,7 @@ platform. The code it generates runs on any Java 1.1 or later compatible | |||
platform. For more information on compatibility with Java and with | |||
previous releases of AspectJ, see xref:compatibility.adoc#versionCompatibility[Version Compatibility]. | |||
==== Examples | |||
=== Examples | |||
Compile two files: | |||
@@ -413,7 +413,7 @@ Run the application without tracing: | |||
java -classpath "app.jar" tracing.ExampleMain | |||
.... | |||
==== The AspectJ compiler API | |||
=== The AspectJ compiler API | |||
The AspectJ compiler is implemented completely in Java and can be called | |||
as a Java class. The only interface that should be considered public are | |||
@@ -449,7 +449,7 @@ public class WrapAjc { | |||
} | |||
.... | |||
==== Stack Traces and the SourceFile attribute | |||
=== Stack Traces and the SourceFile attribute | |||
Unlike traditional java compilers, the AspectJ compiler may in certain | |||
cases generate classfiles from multiple source files. Unfortunately, the |
@@ -1,15 +1,15 @@ | |||
== `ajdoc`, the AspectJ API documentation generator | |||
= `ajdoc`, the AspectJ API documentation generator | |||
=== Name | |||
== Name | |||
`ajdoc` - generate HTML API documentation, including crosscutting structure | |||
=== Synopsis | |||
== Synopsis | |||
[subs=+quotes] | |||
ajdoc [ -bootclasspath _classpathlist_ ] [ -classpath _classpathlist_ ] [-d _path_] [-help] [-package] [-protected] [-private] [-public] [-overview _overviewFile_] [ -sourcepath _sourcepathlist_ ] [-verbose] [-version] [_sourcefiles_... | _packages_... | @_file_... | -argfile _file_...] [ _ajc options_ ] | |||
=== Description | |||
== Description | |||
`ajdoc` renders HTML documentation for AspectJ constructs as well as the | |||
Java constructs that `javadoc` renders. In addition `ajdoc` displays the | |||
@@ -51,7 +51,7 @@ classpath. Normally the scripts set this up, assuming that your | |||
may need to provide this jar when using a different version of Java or a | |||
JRE. | |||
=== Examples | |||
== Examples | |||
* Change into the `examples` directory. | |||
* Type `mkdir doc` to create the destination directory for the documentation. |
@@ -1,8 +1,8 @@ | |||
[[antTasks]] | |||
== AspectJ Ant Tasks | |||
= AspectJ Ant Tasks | |||
[[antTasks-intro]] | |||
=== Introduction | |||
== Introduction | |||
AspectJ contains a compiler, `ajc`, that can be run from Ant. Included | |||
in the `aspectjtools.jar` are Ant binaries to support three ways of | |||
@@ -22,7 +22,7 @@ This describes how to install and use the tasks and the adapter. For an | |||
example Ant script, see xref:../examples/build.xml[examples/build.xml]. | |||
[[antTasks-install]] | |||
=== Installing Ant Tasks | |||
== Installing Ant Tasks | |||
Install Jakarta Ant 1.5.1: Please see the official Jakarta Ant website | |||
for more information and the 1.5.1 distribution. This release is | |||
@@ -34,7 +34,7 @@ v 2.0 at https://eclipse.org/aspectj. | |||
In Ant 1.5, third-party tasks can be declared using a taskdef entry in | |||
the build script, to identify the name and classes. When declaring a | |||
task, include the `aspectjtools.jar` either in the taskdef classpath or | |||
in `${ANT_HOME}/lib` where it will be added to the system class path by | |||
in `$\{ANT_HOME}/lib` where it will be added to the system class path by | |||
the ant script. You may specify the task script names directly, or use | |||
the "resource" attribute to specify the default names: | |||
@@ -49,7 +49,7 @@ uses "iajc" for the AspectJ post-1.1 task. | |||
In Ant 1.6, third-party tasks are declared in their own namespace using | |||
`antlib.xml`. For example, the following script would build and run the | |||
spacewar example, if you put the script in the examples directory and | |||
`aspectjtools.jar` in the `${ANT_HOME}/lib` directory. | |||
`aspectjtools.jar` in the `$\{ANT_HOME}/lib` directory. | |||
[source, xml] | |||
.... | |||
@@ -71,7 +71,7 @@ For more information on using Ant, please refer to Jakarta's | |||
documentation on integrating user-defined Ant tasks into builds. | |||
[[antTasks-iajc]] | |||
=== AjcTask (iajc) | |||
== AjcTask (iajc) | |||
This task uses the AspectJ post-1.1 compiler ajc. The AspectJ compiler | |||
can be used like Javac to compile Java sources, but it can also compile | |||
@@ -91,7 +91,7 @@ directory. | |||
This task is named iajc to avoid conflict with the 1.0 task ajc. | |||
[[antTasks-iajc-options]] | |||
==== AjcTask (iajc) Options | |||
=== AjcTask (iajc) Options | |||
The following tables list the supported parameters. For any parameter | |||
specified as a Path, a single path can be specified directly as an | |||
@@ -325,7 +325,7 @@ depends on compliance mode. | |||
|=== | |||
[[antTasks-nested-includes]] | |||
==== AjcTask matching parameters specified as nested elements | |||
=== AjcTask matching parameters specified as nested elements | |||
This task forms an implicit FileSet and supports all attributes of | |||
`fileset` (dir becomes srcdir) as well as the nested `include`, | |||
@@ -335,7 +335,7 @@ source directories unless using filters to exclude some files from | |||
compilation. | |||
[[antTasks-iajc-paths]] | |||
==== AjcTask Path-like Structures | |||
=== AjcTask Path-like Structures | |||
Some parameters are path-like structures containing one or more | |||
elements; these are `sourceroots`, `argfiles`, `injars`, `inpath`, | |||
@@ -370,7 +370,7 @@ specified using the refid attribute: | |||
</iajc> | |||
.... | |||
The task also supports an attribute `{name}ref` for each such parameter. | |||
The task also supports an attribute `\{name}ref` for each such parameter. | |||
E.g., for `aspectpath`: | |||
[source, xml] | |||
@@ -379,7 +379,7 @@ E.g., for `aspectpath`: | |||
.... | |||
[[antTasks-iajc-sample]] | |||
==== Sample of iajc task | |||
=== Sample of iajc task | |||
A minimal build script defines the task and runs it, specifying the | |||
sources: | |||
@@ -452,7 +452,7 @@ has quit, then this runs the application. | |||
For an example of a build script, see ../examples/build.xml. | |||
[[antTasks-iajc-uptodate]] | |||
==== Avoiding clean compiles | |||
=== Avoiding clean compiles | |||
Unlike javac, the ajc compiler always processes all input because new | |||
aspects can apply to updated classes and vice-versa. However, in the | |||
@@ -479,7 +479,7 @@ When using this technique, be careful to verify that binary input jars | |||
are themselves up-to-date after they would have been modified by any | |||
build commands. | |||
==== Programmatically handling compiler messages | |||
=== Programmatically handling compiler messages | |||
Users may specify a message holder to which the compiler will pass all | |||
messages as they are generated. This will override all of the normal | |||
@@ -495,7 +495,7 @@ AspectJ testing module (which is not included in the binary | |||
distribution). | |||
[[antTasks-adapter]] | |||
=== Ajc11CompilerAdapter (javac) | |||
== Ajc11CompilerAdapter (javac) | |||
This CompilerAdapter can be used in javac task calls by setting the | |||
`build.compiler` property. This enables users to to easily switch | |||
@@ -507,10 +507,10 @@ possible for any given compile job to restate the Javac task in a way | |||
that can be handled by iajc/ajc. | |||
[[antTasks-adapter-sample]] | |||
==== Sample of compiler adapter | |||
=== Sample of compiler adapter | |||
To build using the adapter, put the `aspectjtools.jar` on the system/ant | |||
classpath (e.g., in `${ANT_HOME}/lib`) and define the `build.compiler` | |||
classpath (e.g., in `$\{ANT_HOME}/lib`) and define the `build.compiler` | |||
property as the fully-qualified name of the class, | |||
`org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter`. | |||
@@ -565,7 +565,7 @@ that source root (without exception or filtering).) To replace source | |||
dir searching in Javac, use an Ant filter to specify the source files. | |||
[[antTasks-adapter-options]] | |||
==== Compiler adapter compilerarg options | |||
=== Compiler adapter compilerarg options | |||
The adapter supports any ajc command-line option passed using | |||
compilerarg, as well as the following options available only in AjcTask. | |||
@@ -580,10 +580,10 @@ in javac). | |||
as the message holder. | |||
* `-Xcopyinjars`: copy resources from any input jars to output (default | |||
behavior since 1.1.1) | |||
* `-Xsourcerootcopyfilter {filter}`: copy resources from source | |||
* `-Xsourcerootcopyfilter \{filter}`: copy resources from source | |||
directories to output (minus files specified in filter) | |||
* `-Xtagfile {file}`: use file to control incremental compilation | |||
* `-Xsrcdir {dir}`: add to list of ajc source roots (all source files | |||
* `-Xtagfile \{file}`: use file to control incremental compilation | |||
* `-Xsrcdir \{dir}`: add to list of ajc source roots (all source files | |||
will be included). | |||
Special considerations when using Javac and compilerarg: | |||
@@ -630,7 +630,7 @@ to the destination directory. | |||
compile. | |||
[[antTasks-ajc]] | |||
=== Ajc10 (ajc) | |||
== Ajc10 (ajc) | |||
This task handles the same arguments as those used by the AspectJ 1.0 | |||
task. This should permit those with existing build scripts using the Ajc | |||
@@ -642,7 +642,7 @@ AspectJ 1.1 only should upgrade their scripts to use AjcTask instead. | |||
This will not work for AspectJ 1.2 or later.) | |||
[[antTasks-ajc-options]] | |||
==== Ajc10 (ajc) Options | |||
=== Ajc10 (ajc) Options | |||
Most attributes and nested elements are optional. The compiler requires | |||
that the same version of `aspectjrt.jar` be specified on the classpath, | |||
@@ -733,9 +733,9 @@ line-delimited list of source file paths (absolute or relative to the | |||
argfile). | |||
|=== | |||
===== argfiles - argument list files | |||
==== argfiles - argument list files | |||
An argument file is a file (usually `{file}.lst`) containing a list of | |||
An argument file is a file (usually `\{file}.lst`) containing a list of | |||
source file paths (absolute or relative to the argfile). You can use it | |||
to specify all source files to be compiled, which ajc requires to avoid | |||
searching every possible source file in the source path when building | |||
@@ -750,7 +750,7 @@ IDE support for such files varies, and Javac does not support them. Be | |||
sure to include exactly one argument on each line. | |||
[[antTasks-ajc-nested]] | |||
==== Ajc10 parameters specified as nested elements | |||
=== Ajc10 parameters specified as nested elements | |||
This task forms an implicit FileSet and supports all attributes of | |||
`fileset` (dir becomes srcdir) as well as the nested `include`, | |||
@@ -763,7 +763,7 @@ attributes are path-like structures and can also be set via nested | |||
elements, respectively. | |||
[[antTasks-ajc-sample]] | |||
==== Sample of ajc task | |||
=== Sample of ajc task | |||
Following is a declaration for the ajc task and a sample invocation that | |||
uses the ajc compiler to compile the files listed in `default.lst` into | |||
@@ -818,15 +818,15 @@ This next example | |||
/> | |||
.... | |||
compiles .java files under the `${src}` directory in the spacewar and | |||
coordination packages, and stores the .class files in the `${build}` | |||
compiles .java files under the `$\{src}` directory in the spacewar and | |||
coordination packages, and stores the .class files in the `$\{build}` | |||
directory. All source files under spacewar/ and coordination/ are used, | |||
except Debug.java. | |||
See ../examples/build.xml for an example build script. | |||
[[antTasks-problems]] | |||
=== Isolating problems running the Ant tasks | |||
== Isolating problems running the Ant tasks | |||
If you have problems with the tasks not solved by the documentation, | |||
please try to see if you have the same problems when running ajc | |||
@@ -842,7 +842,7 @@ building from Ant, then please send a report (including your build file, | |||
if possible). | |||
[[antTasks-knownProblems]] | |||
==== Known issues with the Ant tasks | |||
=== Known issues with the Ant tasks | |||
For the most up-to-date information on known problems, see the | |||
https://bugs.eclipse.org/bugs[bug database] for unresolved | |||
@@ -869,7 +869,7 @@ Ant (see the Ant documentation, searching for ANT_OPTS, the variable | |||
they use in their scripts to pass VM options, e.g., ANT_OPTS=-Xmx128m). | |||
[[antTasks-feedback]] | |||
==== Ant task questions and bugs | |||
=== Ant task questions and bugs | |||
For questions, you can send email to aspectj-users@dev.eclipse.org. (Do | |||
join the list to participate!) We also welcome any bug reports, patches, |
@@ -1,8 +1,8 @@ | |||
[[compatibility]] | |||
== AspectJ version compatibility | |||
= AspectJ version compatibility | |||
[[versionCompatibility]] | |||
=== Version Compatibility | |||
== Version Compatibility | |||
Systems, code, and build tools change over time, often not in step. | |||
Generally, later versions of the build tools understand earlier versions | |||
@@ -10,7 +10,7 @@ of the code, but systems should include versions of the runtime used to | |||
build the AspectJ program. | |||
[[javaCompatibility]] | |||
==== Java compatibility | |||
=== Java compatibility | |||
AspectJ programs can run on any Java VM of the required version. The | |||
AspectJ tools produce Java bytecode .class files that run on Java | |||
@@ -35,7 +35,7 @@ require a more recent version of Java. You might use Java 5 to run the | |||
AspectJ compiler to produce code for Java 1.1.8. | |||
[[runtimeCompatibility]] | |||
==== Runtime library compatibility | |||
=== Runtime library compatibility | |||
When deploying AspectJ programs, include on the classpath the classes, | |||
aspects, and the AspectJ runtime library (`aspectjrt.jar`). Use the | |||
@@ -59,7 +59,7 @@ aspect. To find out if the runtime you deployed is the one actually | |||
being used, log the defining class loader for the aspects and runtime. | |||
[[binaryCompatibility]] | |||
==== Aspect binary compatibility | |||
=== Aspect binary compatibility | |||
Generally, binary aspects can be read by later versions of the weaver if | |||
the aspects were built by version 1.2.1 or later. (Some future weavers | |||
@@ -76,7 +76,7 @@ weaver, be careful to rebuild and redeploy with the next released | |||
version. | |||
[[sourceCompatibility]] | |||
==== Aspect source compatibility | |||
=== Aspect source compatibility | |||
Generally, AspectJ source files can be read by later versions of the | |||
compiler. Language features do not change in dot releases (e.g., from | |||
@@ -91,7 +91,7 @@ xref:../progguide/semantics.html[Semantics appendix to the Programming | |||
Guide]. | |||
[[upgrading]] | |||
==== Problems when upgrading to new AspectJ versions | |||
=== Problems when upgrading to new AspectJ versions | |||
Let's say your program behaves differently after being built with a new | |||
version of the AspectJ tools. It could be a bug that was introduced by |
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ Development Environment Guide | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -8,7 +8,7 @@ _Copyright (c) 1998-2001 Xerox Corporation, 2002 Palo Alto Research Center, Inco | |||
All rights reserved._ | |||
This guide describes how to build and deploy AspectJ programs using the AspectJ tools and facilities. See also the | |||
xref:../progguide/progguide.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support | |||
xref:../progguide/index.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support | |||
available for various integrated development environments (e.g. https://www.eclipse.org/ajdt/[Eclipse AJDT]), and the | |||
most-recent documentation available from the https://eclipse.org/aspectj[AspectJ project page]. | |||
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ Development Environment Guide | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -8,7 +8,7 @@ _Copyright (c) 1998-2001 Xerox Corporation, 2002 Palo Alto Research Center, Inco | |||
All rights reserved._ | |||
This guide describes how to build and deploy AspectJ programs using the AspectJ tools and facilities. See also the | |||
xref:../progguide/progguide.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support | |||
xref:../progguide/index.adoc[AspectJ Programming Guide], the documentation available with the AspectJ support | |||
available for various integrated development environments (e.g. https://www.eclipse.org/ajdt/[Eclipse AJDT]), and the | |||
most-recent documentation available from the https://eclipse.org/aspectj[AspectJ project page]. | |||
@@ -1,8 +1,8 @@ | |||
[[ltw]] | |||
== Load-Time Weaving | |||
= Load-Time Weaving | |||
[[ltw-introduction]] | |||
=== Introduction | |||
== Introduction | |||
The AspectJ weaver takes class files as input and produces class files | |||
as output. The weaving process itself can take place at one of three | |||
@@ -35,7 +35,7 @@ reloading those classes). AspectJ 5 does not provide explicit support | |||
for run-time weaving although simple coding patterns can support | |||
dynamically enabling and disabling advice in aspects. | |||
==== Weaving class files more than once | |||
=== Weaving class files more than once | |||
As of AspectJ 5 aspects (code style or annotation style) and woven | |||
classes are reweavable by default. If you are developing AspectJ | |||
@@ -46,7 +46,7 @@ additional state in the class files that is used to support subsequent | |||
reweaving. | |||
[[ltw-rules]] | |||
=== Load-time Weaving Requirements | |||
== Load-time Weaving Requirements | |||
All load-time weaving is done in the context of a class loader, and | |||
hence the set of aspects used for weaving and the types that can be | |||
@@ -67,7 +67,7 @@ may be extended. | |||
weave classes loaded by a delegate or parent class loader. | |||
[[ltw-configuration]] | |||
=== Configuration | |||
== Configuration | |||
New in AspectJ 5 are a number of mechanisms to make load-time weaving | |||
easy to use. The load-time weaving mechanism is chosen through JVM | |||
@@ -75,7 +75,7 @@ startup options. Configuration files determine the set of aspects to be | |||
used for weaving and which types will be woven. Additional diagnostic | |||
options allow the user to debug the configuration and weaving process. | |||
==== Enabling Load-time Weaving | |||
=== Enabling Load-time Weaving | |||
AspectJ 5 supports several ways of enabling load-time weaving for an | |||
application: agents, a command-line launch script, and a set of | |||
@@ -116,7 +116,7 @@ documentation and source for `WeavingURLClassLoader` and | |||
`WeavingAdapter`. | |||
[[configuring-load-time-weaving-with-aopxml-files]] | |||
==== Configuring Load-time Weaving with aop.xml files | |||
=== Configuring Load-time Weaving with aop.xml files | |||
The weaver is configured using one or more `META-INF/aop.xml` files | |||
located on the class loader search path. Each file may declare a list of | |||
@@ -255,7 +255,7 @@ option a JAR is produced that can be used with the `aj5` command or a | |||
load-time weaving environment. | |||
[[concrete-aspect]] | |||
==== Using Concrete Aspects | |||
=== Using Concrete Aspects | |||
It is possible to make an abstract aspect concrete by means of the | |||
`META-INF/aop.xml` file. This is useful way to implement abstract | |||
@@ -355,7 +355,7 @@ AbstractAspect concreteInstance = Aspects.aspectOf(myConcreteAspectClass); | |||
.... | |||
[[concrete-aspect-precedence]] | |||
==== Using Concrete Aspects to define precedence | |||
=== Using Concrete Aspects to define precedence | |||
As described in the previous section, the `concrete-aspect` element in | |||
`META-INF/aop.xml` gives the option to declare the precedence, just as | |||
@@ -382,7 +382,7 @@ qualified class name that will be then reserved for this concrete-aspect | |||
and must not conflict with other classes you deploy. | |||
[[weaver-options]] | |||
==== Weaver Options | |||
=== Weaver Options | |||
The table below lists the AspectJ options supported by LTW. All other | |||
options will be ignored and a warning issued. | |||
@@ -429,7 +429,7 @@ declared to the same weaver. | |||
|=== | |||
[[ltw-specialcases]] | |||
=== Special cases | |||
== Special cases | |||
The following classes are not exposed to the LTW infrastructure | |||
regardless of the `aop.xml` file(s) used: | |||
@@ -453,7 +453,7 @@ The `adviceDidNotMatch` won't be handled as a warn (as during compile | |||
time) but as an info message. | |||
[[ltw-packaging]] | |||
=== Runtime Requirements for Load-time Weaving | |||
== Runtime Requirements for Load-time Weaving | |||
To use LTW the `aspectjweaver.jar` library must be added to the | |||
classpath. This contains the AspectJ 5 runtime, weaver, weaving class | |||
@@ -461,9 +461,9 @@ loader and weaving agents. It also contains the DTD for parsing XML | |||
weaving configuration files. | |||
[[ltw-agents]] | |||
=== Supported Agents | |||
== Supported Agents | |||
==== JVMTI | |||
=== JVMTI | |||
When using Java 5 the JVMTI agent can be used by starting the JVM with | |||
the following option (adapt according to the path to aspectjweaver.jar): | |||
@@ -474,7 +474,7 @@ the following option (adapt according to the path to aspectjweaver.jar): | |||
.... | |||
[[jrockit]] | |||
==== JRockit with Java 1.3/1.4 (use JVMTI on Java 5) | |||
=== JRockit with Java 1.3/1.4 (use JVMTI on Java 5) | |||
Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no longer | |||
part of AspectJ. JRockit JDK never supported Java versions higher than |
@@ -1,8 +1,8 @@ | |||
[[tools-intro]] | |||
== Introduction to the AspectJ tools | |||
= Introduction to the AspectJ tools | |||
[[eclipse-aspectj]] | |||
=== The Eclipse AspectJ implementation | |||
== The Eclipse AspectJ implementation | |||
The xref:../progguide/index.html[AspectJ Programming Guide] describes | |||
the AspectJ language. This guide describes the AspectJ tools produced by | |||
@@ -41,7 +41,7 @@ text below introduces an implementation detail, it will warn if users | |||
make mistakes by applying it in lieu of the language semantics. | |||
[[bytecode-concepts]] | |||
=== Bytecode weaving, incremental compilation, and memory usage | |||
== Bytecode weaving, incremental compilation, and memory usage | |||
Bytecode weaving takes classes and aspects in .class form and weaves | |||
them together to produce binary-compatible .class files that run in any | |||
@@ -74,7 +74,7 @@ require more memory and more time to recompile than the corresponding | |||
AspectJ program.) | |||
[[classpathInpathAndAspectpath]] | |||
==== Classpath, inpath, and aspectpath | |||
=== Classpath, inpath, and aspectpath | |||
AspectJ introduces two new paths for the binary input to the weaver | |||
which you'll find referenced in xref:ajc.adoc[`ajc`, the AspectJ compiler/weaver], |
@@ -1,5 +1,5 @@ | |||
[[_5]] | |||
== Exploring the Spacewar Example | |||
= Exploring the Spacewar Example | |||
_© Copyright 1997-2001 Xerox Corporation. All rights reserved._ | |||
@@ -19,13 +19,13 @@ the helloworld example first by following the instructions in | |||
xref:../doc/primer/default.html[Primer] section Getting Started. | |||
[[_5_1]] | |||
=== Compiling Spacewar | |||
== Compiling Spacewar | |||
* Change to the `examples` directory. | |||
* Type `ajc -argfile spacewar/demo.lst` to compile the system. | |||
[[_5_2]] | |||
=== Running Spacewar | |||
== Running Spacewar | |||
* In the examples directory, type `java spacewar.Game` | |||
@@ -42,7 +42,7 @@ focus so that your keystrokes are recognized. | |||
You can quit the game with ctl-Q. | |||
[[_5_3]] | |||
=== Exploring the Code | |||
== Exploring the Code | |||
There is one other built-in configurations for the Spacewar game. Try it | |||
by typing `ajc @spacewar\debug.lst`. This compiles in an elaborate |
@@ -2267,7 +2267,7 @@ bug. See #q:bugreports[Q:How do I submit a bug report?]. | |||
specifying the defining signature. Since all overriding methods share | |||
this signature, the advice runs for each method executed. (This happens, | |||
e.g., when one method invokes the same method in the superclass using | |||
`super.{method}(..)`). This is the correct behavior. | |||
`super.\{method}(..)`). This is the correct behavior. | |||
To avoid this, use the `call(..)` pointcut designator, or use | |||
`!cflow(..)` to pick out only the initial method-execution. | |||
@@ -2467,7 +2467,7 @@ Aspect instances will be garbage collected just like regular objects | |||
after there are no more strong references to them. For the default | |||
aspect instantiation model, `issingleton`, the aspect class retains a | |||
reference to the singleton instance, in order to implement | |||
`static {AspectClass} aspectOf()`, so singleton instances will not be | |||
`static \{AspectClass} aspectOf()`, so singleton instances will not be | |||
garbage collected until the class is. For long-running or | |||
memory-critical programs, consider using weak references in singleton | |||
aspects for state that should be garbage collected. | |||
@@ -2586,8 +2586,8 @@ JBuilder, and NetBeans through a common API, AJDE. | |||
*Q:* What are the new features of AspectJ 5? | |||
*A:* All the new features are documented in the | |||
xref:../adk15notebook/adk15notebook.adoc[AspectJ 5 Developer's Notebook] and the | |||
link:devguide/index.html[AspectJ Development Environment Guide]. To | |||
xref:../adk15notebook/index.adoc[AspectJ 5 Developer's Notebook] and the | |||
xref:../devguide/index.adoc[AspectJ Development Environment Guide]. To | |||
summarize: | |||
* Java 5 support: as an extension to Java, AspectJ supports all the new |
@@ -1,5 +1,5 @@ | |||
[[top]] | |||
== AspectJ Documentation and Resources | |||
= AspectJ Documentation and Resources | |||
AspectJ^TM^ is a seamless aspect-oriented extension to Java^TM^. The compiler and development tools are available under | |||
an open-source license, require Java 8 to run, and produce code that runs in JDK 1.3 and later VM's. For the latest | |||
@@ -27,7 +27,7 @@ mailto:aspectj-users@eclipse.org[users] and mailto:aspectj-dev@eclipse.org[devel | |||
|=== | |||
[[documentation]] | |||
=== AspectJ documentation | |||
== AspectJ documentation | |||
[width="100%",cols="50%,50%",options="header",] | |||
|=== | |||
@@ -144,7 +144,7 @@ a|AspectJ Design Overview | |||
[[distributions]] | |||
=== AspectJ distributions | |||
== AspectJ distributions | |||
[cols=",",options="header",] | |||
|=== | |||
@@ -167,7 +167,7 @@ eclipse.org project site https://eclipse.org/ajdt | |||
[[resources]] | |||
=== Other AspectJ resources | |||
== Other AspectJ resources | |||
[cols=",",options="header",] | |||
|=== | |||
@@ -193,7 +193,7 @@ See the xref:faq/faq.adoc#ajcbugs[FAQ entry] for instructions on submitting comp | |||
|=== | |||
[[paths]] | |||
=== Suggested learning paths for those new to AspectJ | |||
== Suggested learning paths for those new to AspectJ | |||
To learn the AspectJ language, read the xref:progguide/index.adoc[Programming Guide], keeping the | |||
xref:progguide/semantics.adoc[Semantics appendix] nearby as the best reference for AspectJ usage. Focus initially on the |
@@ -1,8 +1,8 @@ | |||
[[ajcore]] | |||
== AspectJ Core Files | |||
= AspectJ Core Files | |||
[[ajcore-introduction]] | |||
=== Introduction | |||
== Introduction | |||
When the compiler terminates abnormally, either because a particular | |||
kind of message was issued or an exception was thrown, an AspectJ core | |||
@@ -15,7 +15,7 @@ version. When submitting a bug, include this file whenever it is | |||
available. | |||
[[configuration]] | |||
==== Configuring dump files | |||
=== Configuring dump files | |||
By default AspectJ will only create an `ajcore` file when an unexpected | |||
exception is thrown by the weaver or an `abort` message is issued. | |||
@@ -37,7 +37,7 @@ files. | |||
|=== | |||
[[ajcore-examples]] | |||
==== AJCore File Examples | |||
=== AJCore File Examples | |||
Below is an extract from an `ajcore` file. You will see details of the | |||
dump configuration as well as the exception (with stack trace) that is |
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ Problem Diagnosis Guide | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -1,8 +1,8 @@ | |||
[[ltwdump]] | |||
== Dumping classes during load-time weaving | |||
= Dumping classes during load-time weaving | |||
[[ltwdump-introduction]] | |||
=== Introduction | |||
== Introduction | |||
Very rarely problems may be encountered with classes that have been | |||
load-time woven. Symptoms will include incorrect program function or a | |||
@@ -16,15 +16,15 @@ proxy or has already been instrumented by another agent) you can | |||
configure the weaver to dump the input classes as well. | |||
[[ltw-examples]] | |||
==== Configuring bytecode dumping in load-time weaving | |||
=== Configuring bytecode dumping in load-time weaving | |||
For details of how to configure byte-code dumping, see the AspectJ | |||
Development Environment Guide section on | |||
xref:../devguide/ltw.html#configuring-load-time-weaving-with-aopxml-files[Configuring | |||
xref:../devguide/ltw.adoc#configuring-load-time-weaving-with-aopxml-files[Configuring | |||
Load-time Weaving]. Following is a simple example. | |||
[[ltwdump-examples]] | |||
==== LTW Dump Examples | |||
=== LTW Dump Examples | |||
The following `META-INF/aop.xml` will weave classes in the `com.foo` | |||
package (and subpackages) but not CGLIB generated classes in the |
@@ -1,8 +1,8 @@ | |||
[[messages]] | |||
== Messages | |||
= Messages | |||
[[messages-introduction]] | |||
=== Introduction | |||
== Introduction | |||
Messages point out potential problems in the input program; some are | |||
clearly problems (errors), but many more may depend on what the | |||
@@ -14,7 +14,7 @@ some problem scenarios when compiling or doing load-time weaving, and | |||
summarizes some of the more relevant messages. | |||
[[messages-introduction-config]] | |||
==== Configuring Messages | |||
=== Configuring Messages | |||
The compiler offers `-verbose`, `-warning`, and `-XLint` options when | |||
invoked using the command-line, Ant, or embedded in an IDE. All options | |||
@@ -85,19 +85,19 @@ warnings associated with the next line of code. | |||
|=== | |||
[[messages-scenarios]] | |||
=== Message scenarios | |||
== Message scenarios | |||
[[messages-scenarios-ct]] | |||
==== Compile-time weaving scenarios | |||
=== Compile-time weaving scenarios | |||
[[messages-scenarios-ct-adviceNotWoven]] | |||
===== Advice not woven | |||
==== Advice not woven | |||
This means that the pointcut for the advice did not match, and it should | |||
be debugged as described in xref:pointcuts.adoc#pointcuts[Debugging Pointcuts]. | |||
[[messages-scenarios-ltw]] | |||
==== Load-time weaving scenarios | |||
=== Load-time weaving scenarios | |||
You can use `META-INF/aop.xml` to control which messages are produced | |||
during LTW. The following example will produce basic informational | |||
@@ -129,7 +129,7 @@ applications each of which will typically have its own class loader. | |||
.... | |||
[[messages-scenarios-ltw-adviceNotWoven]] | |||
===== Advice not woven | |||
==== Advice not woven | |||
It is often difficult to determine, especially when using load-time | |||
weaving (LTW), why advice has not been woven. Here is a quick guide to | |||
@@ -164,7 +164,7 @@ If advice is woven at this join point you should get the corresponding | |||
message. | |||
[[messages-xlint]] | |||
=== Lint messages | |||
== Lint messages | |||
The table below lists some useful `-Xlint` messages. | |||
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ Problem Diagnosis Guide | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -1,8 +1,8 @@ | |||
[[pointcuts]] | |||
== Debugging Pointcuts | |||
= Debugging Pointcuts | |||
[[pointcuts-introduction]] | |||
=== Introduction | |||
== Introduction | |||
This section describes how to write and debug pointcuts using the usual | |||
approach of iteration and decomposition. New users are often stumped | |||
@@ -14,11 +14,11 @@ break it down, particularly into parts that can be checked at | |||
compile-time, can save a lot of time. | |||
[[pointcuts-debugging]] | |||
=== Debugging pointcuts | |||
== Debugging pointcuts | |||
Go at it top-down and then bottom-up. | |||
==== Top-down | |||
=== Top-down | |||
Top-down, draft significant | |||
aspects by first writing the comments to specify responsibilities. | |||
@@ -30,7 +30,7 @@ semantic bridge to the plain-text meaning in a comment, e.g. `// when | |||
the client passes only context into the library`. This gets you to a | |||
point where you can debug the parts of the pointcut independently. | |||
==== Bottom-up | |||
=== Bottom-up | |||
Bottom-up (to build each part), consider each primitive pointcut | |||
designator (PCD), then the composition, and then any implicit | |||
@@ -59,12 +59,12 @@ listed above). If compiles themselves take too long because of all the | |||
AspectJ weaving, then try to only include the debugging aspect with the | |||
prototype pointcut, and limit the scope using `within(..)`. | |||
=== Common pointcut mistakes | |||
== Common pointcut mistakes | |||
There are some typical types of mistakes developers make when designing pointcuts. | |||
Here are a few examples: | |||
==== Mistakes in primitive pointcuts | |||
=== Mistakes in primitive pointcuts | |||
* `this(Foo) && execution(static * *(..))`: There is no `this` in a | |||
static context, so `this()` or `target()` should not be used in a static | |||
@@ -90,7 +90,7 @@ within `Foo`, so this won't pick out any overrides of `bar(..)`. Use | |||
* `within(Foo)`: anonymous types are not known at weave-time to be | |||
within the lexically-enclosing type (a limitation of Java bytecode). | |||
==== Mistakes in composition | |||
=== Mistakes in composition | |||
* `call(* foo(Bar, Foo)) && args(Foo)`: This will never match. The | |||
parameters in `args(..)` are position-dependent, so `args(Foo)` only | |||
@@ -104,7 +104,7 @@ different kinds of join points (here, call or execution), use `||`. | |||
E.g., to match both method-call and field-get join points, use | |||
`call(* ...) || get(...)`. | |||
==== Mistakes in implicit advice constraints | |||
=== Mistakes in implicit advice constraints | |||
* `after () returning (Foo foo) : ...`: after advice can bind the | |||
returned object or exception thrown. That effectively acts like | |||
@@ -112,7 +112,7 @@ returned object or exception thrown. That effectively acts like | |||
based on the runtime type of the bound object, even though it is not | |||
explicitly part of the pointcut. | |||
==== Mistakes in implementation requirements | |||
=== Mistakes in implementation requirements | |||
* _ajc_ has to control the code for a join point in order to implement | |||
the join point. This translates to an implicit `within({code under the |
@@ -1,8 +1,8 @@ | |||
[[trace]] | |||
== Tracing | |||
= Tracing | |||
[[trace-introduction]] | |||
=== Introduction | |||
== Introduction | |||
The AspectJ developers have instrumented the compiler/weaver with many | |||
"trace" messages for their own debugging use. These remain in the | |||
@@ -22,7 +22,7 @@ produce a trace of the compiler when the problem occurs instead. This | |||
can then be attached to the bug report. | |||
[[trace-configuration]] | |||
==== Configuring Tracing | |||
=== Configuring Tracing | |||
When available (Java 5 or later) AspectJ will use the | |||
http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html[java.util.logging] | |||
@@ -72,7 +72,7 @@ Default: `false`. | |||
|=== | |||
[[trace-examples]] | |||
==== Examples | |||
=== Examples | |||
Using `-Dorg.aspectj.tracing.factory=default` to force AspectJ to use | |||
its internal infrastructure, `-Dorg.aspectj.tracing.enabled=true` to |
@@ -1,8 +1,8 @@ | |||
[[examples]] | |||
== Examples | |||
= Examples | |||
[[examples-intro]] | |||
=== Introduction | |||
== Introduction | |||
This chapter consists entirely of examples of AspectJ use. | |||
@@ -18,7 +18,7 @@ reusable:: | |||
Examples of reuse of aspects and pointcuts | |||
[[examples-howto]] | |||
=== Obtaining, Compiling and Running the Examples | |||
== Obtaining, Compiling and Running the Examples | |||
The examples source code is part of the AspectJ distribution which may | |||
be downloaded from the https://eclipse.org/aspectj[AspectJ project page]. | |||
@@ -51,7 +51,7 @@ java -classpath ".;InstallDir/lib/aspectjrt.jar" telecom.billingSimulation | |||
.... | |||
[[examples-basic]] | |||
=== Basic Techniques | |||
== Basic Techniques | |||
This section presents two basic techniques of using AspectJ, one each | |||
from the two fundamental ways of capturing crosscutting concerns: with | |||
@@ -65,7 +65,7 @@ some advice. The second example, xref:#examples-roles[Roles and Views], | |||
concerns a crosscutting view of an existing class hierarchy. | |||
[[examples-joinPoints]] | |||
==== Join Points and `thisJoinPoint` | |||
=== Join Points and `thisJoinPoint` | |||
(The code for this example is in `InstallDir/examples/tjp`.) | |||
@@ -125,7 +125,7 @@ point | |||
* an object encapsulating the static information about the join point. | |||
This is also available through the special variable `thisJoinPointStaticPart`. | |||
===== The `Demo` class | |||
==== The `Demo` class | |||
The class `tjp.Demo` in `tjp/Demo.java` defines two methods `foo` and | |||
`bar` with different parameter lists and return types. Both are called, | |||
@@ -158,7 +158,7 @@ public class Demo { | |||
} | |||
.... | |||
===== The `GetInfo` aspect | |||
==== The `GetInfo` aspect | |||
This aspect uses around advice to intercept the execution of methods | |||
`foo` and `bar` in `Demo`, and prints out information garnered from | |||
@@ -201,7 +201,7 @@ aspect GetInfo { | |||
} | |||
.... | |||
====== Defining the scope of a pointcut | |||
===== Defining the scope of a pointcut | |||
The pointcut `goCut` is defined as | |||
@@ -216,7 +216,7 @@ execution of `go` itself, so the definition of the around advice | |||
includes `!execution(* go())` to exclude it from the set of executions | |||
advised. | |||
====== Printing the class and method name | |||
===== Printing the class and method name | |||
The name of the method and that method's defining class are available as | |||
parts of the | |||
@@ -224,7 +224,7 @@ xref:../api/org/aspectj/lang/Signature.html[`org.aspectj.lang.Signature`] | |||
object returned by calling `getSignature()` on either `thisJoinPoint` or | |||
`thisJoinPointStaticPart`. | |||
====== Printing the parameters | |||
===== Printing the parameters | |||
The static portions of the parameter details, the name and types of the | |||
parameters, can be accessed through the | |||
@@ -236,7 +236,7 @@ The dynamic portions of the parameter details, the actual values of the | |||
parameters, are accessed directly from the execution join point object. | |||
[[examples-roles]] | |||
==== Roles and Views | |||
=== Roles and Views | |||
(The code for this example is in `InstallDir/examples/introduction`.) | |||
@@ -269,7 +269,7 @@ and polar coordinates. Our inter-type declarations will make the class | |||
are provided by AspectJ without having to modify the code for the class | |||
`Point`. | |||
===== The `Point` class | |||
==== The `Point` class | |||
The `Point` class defines geometric points whose interface includes | |||
polar and rectangular coordinates, plus some simple operations to | |||
@@ -289,7 +289,7 @@ with the class `Point`. | |||
image:images/aspects.png[image] | |||
===== The `CloneablePoint` aspect | |||
==== The `CloneablePoint` aspect | |||
This first aspect is responsible for ``Point``'s implementation of the | |||
`Cloneable` interface. It declares that `Point implements Cloneable` | |||
@@ -336,7 +336,7 @@ public aspect CloneablePoint { | |||
} | |||
.... | |||
===== The `ComparablePoint` aspect | |||
==== The `ComparablePoint` aspect | |||
`ComparablePoint` is responsible for ``Point``'s implementation of the | |||
`Comparable` interface. | |||
@@ -387,7 +387,7 @@ public aspect ComparablePoint { | |||
} | |||
.... | |||
===== The `HashablePoint` aspect | |||
==== The `HashablePoint` aspect | |||
Our third aspect is responsible for ``Point``'s overriding of ``Object``'s | |||
`equals` and `hashCode` methods in order to make ``Point``s hashable. | |||
@@ -450,9 +450,9 @@ public aspect HashablePoint { | |||
.... | |||
[[examples-development]] | |||
=== Development Aspects | |||
== Development Aspects | |||
==== Tracing using aspects | |||
=== Tracing using aspects | |||
(The code for this example is in `InstallDir/examples/tracing`.) | |||
@@ -482,7 +482,7 @@ one of those kind of system aspects that can potentially be plugged in | |||
and unplugged without any side-effects in the basic functionality of the | |||
system. | |||
===== An Example Application | |||
==== An Example Application | |||
Throughout this example we will use a simple application that contains | |||
only four classes. The application is about shapes. The `TwoDShape` | |||
@@ -586,7 +586,7 @@ s1.distance(c1) = 2.23606797749979 | |||
s1.toString(): Square side = 1.0 @ (1.0, 2.0) | |||
.... | |||
===== Tracing - Version 1 | |||
==== Tracing - Version 1 | |||
In a first attempt to insert tracing in this application, we will start | |||
by writing a `Trace` class that is exactly what we would write if we | |||
@@ -707,7 +707,7 @@ s1.toString(): Square side = 1.0 @ (1.0, 2.0) | |||
When `TraceMyClasses.java` is not provided to `ajc`, the aspect does not | |||
have any affect on the system and the tracing is unplugged. | |||
===== Tracing - Version 2 | |||
==== Tracing - Version 2 | |||
Another way to accomplish the same thing would be to write a reusable | |||
tracing aspect that can be used not only for these application classes, | |||
@@ -846,9 +846,9 @@ Abstract methods don't provide the implementation, but you know that the | |||
concrete subclasses will, so you can invoke those methods. | |||
[[examples-production]] | |||
=== Production Aspects | |||
== Production Aspects | |||
==== A Bean Aspect | |||
=== A Bean Aspect | |||
(The code for this example is in `InstallDir/examples/bean`.) | |||
@@ -876,7 +876,7 @@ class is not serializable. Bound is an aspect that makes `Point` a | |||
serializable class and makes its `get` and `set` methods support the | |||
bound property protocol. | |||
===== The `Point` class | |||
==== The `Point` class | |||
The `Point` class is a very simple class with trivial getters and | |||
setters, and a simple vector offset method. | |||
@@ -919,7 +919,7 @@ class Point { | |||
} | |||
.... | |||
===== The `BoundPoint` aspect | |||
==== The `BoundPoint` aspect | |||
The `BoundPoint` aspect is responsible for ``Point``'s "beanness". The | |||
first thing it does is privately declare that each `Point` has a | |||
@@ -1023,7 +1023,7 @@ aspect BoundPoint { | |||
} | |||
.... | |||
===== The Test Program | |||
==== The Test Program | |||
The test program registers itself as a property change listener to a | |||
`Point` object that it creates and then performs simple manipulation of | |||
@@ -1064,7 +1064,7 @@ class Demo implements PropertyChangeListener { | |||
} | |||
.... | |||
===== Compiling and Running the Example | |||
==== Compiling and Running the Example | |||
To compile and run this example, go to the examples directory and type: | |||
@@ -1075,7 +1075,7 @@ java bean.Demo | |||
.... | |||
[[the-subject-observer-protocol]] | |||
==== The Subject/Observer Protocol | |||
=== The Subject/Observer Protocol | |||
(The code for this example is in `InstallDir/examples/observer`.) | |||
@@ -1095,7 +1095,7 @@ The demo is designed and implemented using the Subject/Observer design | |||
pattern. The remainder of this example explains the classes and aspects | |||
of this demo, and tells you how to run it. | |||
===== Generic Components | |||
==== Generic Components | |||
The generic parts of the protocol are the interfaces `Subject` and | |||
`Observer`, and the abstract aspect `SubjectObserverProtocol`. The | |||
@@ -1165,7 +1165,7 @@ after the join points of the pointcut. And it declares an inter-type | |||
field and two inter-type methods so that each `Observer` can hold onto | |||
its `Subject`. | |||
===== Application Classes | |||
==== Application Classes | |||
`Button` objects extend `java.awt.Button`, and all they do is make sure | |||
the `void click()` method is called whenever a button is clicked. | |||
@@ -1255,7 +1255,7 @@ required by those interfaces, and providing a definition for the | |||
abstract `stateChanges` pointcut. Now, every time a `Button` is clicked, | |||
all `ColorLabel` objects observing that button will `colorCycle`. | |||
===== Compiling and Running | |||
==== Compiling and Running | |||
`Demo` is the top class that starts this demo. It instantiates a two | |||
buttons and three observers and links them together as subjects and | |||
@@ -1267,7 +1267,7 @@ ajc -argfile observer/files.lst | |||
java observer.Demo | |||
.... | |||
==== A Simple Telecom Simulation | |||
=== A Simple Telecom Simulation | |||
(The code for this example is in `InstallDir/examples/telecom`.) | |||
@@ -1277,7 +1277,7 @@ model of telephone connections to which timing and billing features are | |||
added using aspects, where the billing feature depends upon the timing | |||
feature. | |||
===== The Application | |||
==== The Application | |||
The example application is a simple simulation of a telephony system in | |||
which customers make, accept, merge and hang-up both local and long | |||
@@ -1303,7 +1303,7 @@ share a common superclass `AbstractSimulation`, which defines the method | |||
run with the simulation itself and the method wait used to simulate | |||
elapsed time. | |||
===== The Basic Objects | |||
==== The Basic Objects | |||
The telecom simulation comprises the classes `Customer`, `Call` and the | |||
abstract class `Connection` with its two concrete subclasses `Local` and | |||
@@ -1316,7 +1316,7 @@ involved in many calls at one time. | |||
image:images/telecom.png[image] | |||
===== The `Customer` class | |||
==== The `Customer` class | |||
`Customer` has methods `call`, `pickup`, `hangup` and `merge` for | |||
managing calls. | |||
@@ -1377,7 +1377,7 @@ public class Customer { | |||
} | |||
.... | |||
===== The `Call` class | |||
==== The `Call` class | |||
Calls are created with a caller and receiver who are customers. If the | |||
caller and receiver have the same area code then the call can be | |||
@@ -1387,7 +1387,7 @@ connections between customers. Initially there is only the connection | |||
between the caller and receiver but additional connections can be added | |||
if calls are merged to form conference calls. | |||
===== The `Connection` class | |||
==== The `Connection` class | |||
The class `Connection` models the physical details of establishing a | |||
connection between customers. It does this with a simple state machine | |||
@@ -1437,7 +1437,7 @@ abstract class Connection { | |||
} | |||
.... | |||
===== The `Local` and `LongDistance` classes | |||
==== The `Local` and `LongDistance` classes | |||
The two kinds of connections supported by our simulation are `Local` and | |||
`LongDistance` connections. | |||
@@ -1466,7 +1466,7 @@ class LongDistance extends Connection { | |||
} | |||
.... | |||
===== Compiling and Running the Basic Simulation | |||
==== Compiling and Running the Basic Simulation | |||
The source files for the basic system are listed in the file | |||
`basic.lst`. To build and run the basic system, in a shell window, type | |||
@@ -1478,13 +1478,13 @@ ajc -argfile telecom/basic.lst | |||
java telecom.BasicSimulation | |||
.... | |||
===== The Timing aspect | |||
==== The Timing aspect | |||
The `Timing` aspect keeps track of total connection time for each | |||
`Customer` by starting and stopping a timer associated with each | |||
connection. It uses some helper classes: | |||
====== The `Timer` class | |||
===== The `Timer` class | |||
A `Timer` object simply records the current time when it is started and | |||
stopped, and returns their difference when asked for the elapsed time. | |||
@@ -1511,7 +1511,7 @@ class Timer { | |||
} | |||
.... | |||
===== The `TimerLog` aspect | |||
==== The `TimerLog` aspect | |||
The `TimerLog` aspect can be included in a build to get the timer to | |||
announce when it is started and stopped. | |||
@@ -1530,7 +1530,7 @@ public aspect TimerLog { | |||
} | |||
.... | |||
===== The `Timing` aspect | |||
==== The `Timing` aspect | |||
The `Timing` aspect is declares an inter-type field `totalConnectTime` | |||
for `Customer` to store the accumulated connection time per `Customer`. | |||
@@ -1573,7 +1573,7 @@ public aspect Timing { | |||
} | |||
.... | |||
===== The `Billing` aspect | |||
==== The `Billing` aspect | |||
The Billing system adds billing functionality to the telecom application | |||
on top of timing. | |||
@@ -1627,7 +1627,7 @@ public aspect Billing { | |||
} | |||
.... | |||
===== Accessing the inter-type state | |||
==== Accessing the inter-type state | |||
Both the aspects `Timing` and `Billing` contain the definition of | |||
operations that the rest of the system may want to access. For example, | |||
@@ -1651,7 +1651,7 @@ protected void report(Customer c){ | |||
} | |||
.... | |||
===== Compiling and Running | |||
==== Compiling and Running | |||
The files timing.lst and billing.lst contain file lists for the timing | |||
and billing configurations. To build and run the application with only | |||
@@ -1672,7 +1672,7 @@ ajc -argfile telecom/billing.lst | |||
java telecom.BillingSimulation | |||
.... | |||
===== Discussion | |||
==== Discussion | |||
There are some explicit dependencies between the aspects `Billing` and | |||
`Timing`: | |||
@@ -1683,13 +1683,13 @@ advice runs after that of `Timing` when they are on the same join point. | |||
* `Billing` needs access to the timer associated with a connection. | |||
[[examples-reusable]] | |||
=== Reusable Aspects | |||
== Reusable Aspects | |||
==== Tracing using Aspects, Revisited | |||
=== Tracing using Aspects, Revisited | |||
(The code for this example is in `InstallDir/examples/tracing`.) | |||
===== Tracing - Version 3 | |||
==== Tracing - Version 3 | |||
One advantage of not exposing the methods `traceEntry` and `traceExit` as | |||
public operations is that we can easily change their interface without |
@@ -1,8 +1,8 @@ | |||
[[starting]] | |||
== Getting Started with AspectJ | |||
= Getting Started with AspectJ | |||
[[starting-intro]] | |||
=== Introduction | |||
== Introduction | |||
Many software developers are attracted to the idea of aspect-oriented | |||
programming (AOP) but unsure about how to begin using the technology. | |||
@@ -48,7 +48,7 @@ is one ordering that allows developers to get experience with (and | |||
benefit from) AOP technology quickly, while also minimizing risk. | |||
[[starting-aspectj]] | |||
=== Introduction to AspectJ | |||
== Introduction to AspectJ | |||
This section presents a brief introduction to the features of AspectJ | |||
used later in this chapter. These features are at the core of the | |||
@@ -114,7 +114,7 @@ inheritable unit of modularity. Lastly, we will look at how to use | |||
inter-type declarations to deal with crosscutting concerns of a | |||
program's class structure. | |||
==== The Dynamic Join Point Model | |||
=== The Dynamic Join Point Model | |||
A critical element in the design of any aspect-oriented language is the | |||
join point model. The join point model provides the common frame of | |||
@@ -138,7 +138,7 @@ from the body. We say that these join points execute in the _dynamic | |||
context_ of the original call join point. | |||
[[pointcuts-starting]] | |||
==== Pointcuts | |||
=== Pointcuts | |||
In AspectJ, _pointcuts_ pick out certain join points in the program | |||
flow. For example, the pointcut | |||
@@ -239,7 +239,7 @@ called and when it returns (either normally or by throwing an | |||
exception). | |||
[[advice-starting]] | |||
==== Advice | |||
=== Advice | |||
So pointcuts pick out join points. But they don't _do_ anything apart | |||
from picking out join points. To actually implement crosscutting | |||
@@ -279,7 +279,7 @@ _Around advice_ on a join point runs as the join point is reached, and | |||
has explicit control over whether the program proceeds with the join | |||
point. Around advice is not discussed in this section. | |||
===== Exposing Context in Pointcuts | |||
==== Exposing Context in Pointcuts | |||
Pointcuts not only pick out join points, they can also expose part of | |||
the execution context at their join points. Values exposed by a pointcut | |||
@@ -353,7 +353,7 @@ after(FigureElement fe, int x, int y) returning: setXY(fe, x, y) { | |||
} | |||
.... | |||
==== Inter-type declarations | |||
=== Inter-type declarations | |||
Inter-type declarations in AspectJ are declarations that cut across | |||
classes and their hierarchies. They may declare members that cut across | |||
@@ -440,7 +440,7 @@ Note that neither ``Screen``'s nor ``Point``'s code has to be modified, and | |||
that all the changes needed to support this new capability are local to | |||
this aspect. | |||
==== Aspects | |||
=== Aspects | |||
Aspects wrap up pointcuts, advice, and inter-type declarations in a a | |||
modular unit of crosscutting implementation. It is defined very much | |||
@@ -469,7 +469,7 @@ Aspects may also have more complicated rules for instantiation, but | |||
these will be described in a later chapter. | |||
[[starting-development]] | |||
=== Development Aspects | |||
== Development Aspects | |||
The next two sections present the use of aspects in increasingly | |||
sophisticated ways. Development aspects are easily removed from | |||
@@ -484,7 +484,7 @@ consistency within the application. Using AspectJ makes it possible to | |||
cleanly modularize this kind of functionality, thereby making it | |||
possible to easily enable and disable the functionality when desired. | |||
==== Tracing | |||
=== Tracing | |||
This first example shows how to increase the visibility of the internal | |||
workings of a program. It is a simple tracing aspect that prints a | |||
@@ -537,7 +537,7 @@ that have proven useful in the past is a direct result of AspectJ | |||
modularizing a crosscutting design element the set of methods that are | |||
appropriate to trace when looking for a given kind of information. | |||
==== Profiling and Logging | |||
=== Profiling and Logging | |||
Our second example shows you how to do some very specific profiling. | |||
Although many sophisticated profiling tools are available, and these can | |||
@@ -588,7 +588,7 @@ Such questions may be difficult to express using standard profiling or | |||
logging tools. | |||
[[pre-and-post-conditions]] | |||
==== Pre- and Post-Conditions | |||
=== Pre- and Post-Conditions | |||
Many programmers use the "Design by Contract" style popularized by | |||
Bertand Meyer in Object-Oriented Software Construction, 2/e. In this | |||
@@ -637,7 +637,7 @@ in the production build as well. Again, because AspectJ makes it | |||
possible to modularize these crosscutting concerns cleanly, it gives | |||
developers good control over this decision. | |||
==== Contract Enforcement | |||
=== Contract Enforcement | |||
The property-based crosscutting mechanisms can be very useful in | |||
defining more sophisticated contract enforcement. One very powerful use | |||
@@ -692,7 +692,7 @@ and the `call` pointcut here picks out join points statically). Other | |||
enforcement, such as the precondition enforcement, above, does require | |||
dynamic information such as the runtime value of parameters. | |||
==== Configuration Management | |||
=== Configuration Management | |||
Configuration management for aspects can be handled using a variety of | |||
make-file like techniques. To work with optional aspects, the programmer | |||
@@ -706,7 +706,7 @@ to write such make files, the AspectJ compiler has a command-line | |||
interface that is consistent with ordinary Java compilers. | |||
[[starting-production]] | |||
=== Production Aspects | |||
== Production Aspects | |||
This section presents examples of aspects that are inherently intended | |||
to be included in the production builds of an application. Production | |||
@@ -719,7 +719,7 @@ adopting AspectJ. But even though they tend to be small and simple, they | |||
can often have a significant effect in terms of making the program | |||
easier to understand and maintain. | |||
==== Change Monitoring | |||
=== Change Monitoring | |||
The first example production aspect shows how one might implement some | |||
simple functionality where it is problematic to try and do it | |||
@@ -803,7 +803,7 @@ compelling for property-based aspects (see the section | |||
xref:#starting-production-consistentBehavior[Providing Consistent | |||
Behavior]). | |||
==== Context Passing | |||
=== Context Passing | |||
The crosscutting structure of context passing can be a significant | |||
source of complexity in Java programs. Consider implementing | |||
@@ -844,7 +844,7 @@ aspects while the aspect is short and affects only a modest number of | |||
benefits, the complexity the aspect saves is potentially much larger. | |||
[[starting-production-consistentBehavior]] | |||
==== Providing Consistent Behavior | |||
=== Providing Consistent Behavior | |||
This example shows how a property-based aspect can be used to provide | |||
consistent handling of functionality across a large set of operations. | |||
@@ -935,7 +935,7 @@ crosscutting structure of the aspect explicitly made the code more | |||
concise and eliminated latent bugs. | |||
[[starting-conclusion]] | |||
=== Conclusion | |||
== Conclusion | |||
AspectJ is a simple and practical aspect-oriented extension to Java. | |||
With just a few new constructs, AspectJ provides support for modular |
@@ -1,7 +1,7 @@ | |||
== Idioms | |||
= Idioms | |||
[[idioms-intro]] | |||
=== Introduction | |||
== Introduction | |||
This chapter consists of very short snippets of AspectJ code, typically | |||
pointcuts, that are particularly evocative or useful. This section is a |
@@ -1,7 +1,7 @@ | |||
[[implementation]] | |||
== Implementation Notes | |||
= Implementation Notes | |||
=== Compiler Notes | |||
== Compiler Notes | |||
The initial implementations of AspectJ have all been compiler-based | |||
implementations. Certain elements of AspectJ's semantics are difficult | |||
@@ -108,10 +108,10 @@ used. During your development, you will have to be aware of the | |||
limitations of the _ajc_ compiler you're using, but these limitations | |||
should not drive the design of your aspects. | |||
=== Bytecode Notes | |||
== Bytecode Notes | |||
[[the-class-expression-and-string-plus]] | |||
==== The `.class` expression and `String` `+` | |||
=== The `.class` expression and `String` `+` | |||
The java language form `Foo.class` is implemented in bytecode with a | |||
call to `Class.forName` guarded by an exception handler catching a | |||
@@ -140,7 +140,7 @@ class Test { | |||
In short, the join point model of the current AspectJ compiler considers | |||
these as valid join points. | |||
==== The `handler()` join point | |||
=== The `handler()` join point | |||
The end of exception handlers cannot reliably be found in Java bytecode. | |||
Instead of removing the `handler` join point entirely, the current AspectJ | |||
@@ -185,7 +185,7 @@ A source-code implementation of AspectJ (such as AspectJ 1.0.6) is able | |||
to detect the endpoint of a handler join point, and as such will likely | |||
have fewer such restrictions. | |||
==== Initializers and Inter-type Constructors | |||
=== Initializers and Inter-type Constructors | |||
The code for Java initializers, such as the assignment to the field `d` in | |||
@@ -221,7 +221,7 @@ aspect A { | |||
It is the job of an inter-type constructor to do all the required | |||
initialization, or to delegate to a `this` constructor if necessary. | |||
=== Annotation-style Notes | |||
== Annotation-style Notes | |||
Writing aspects in annotation-style is subject to the same bytecode | |||
limitations since the binary aspects take the same form and are woven in | |||
@@ -229,7 +229,7 @@ the same way. However, the implementation differences (e.g., the | |||
mechanism for implementing `around` advice) may be apparent at runtime. | |||
See the documentation on annotation-style for more information. | |||
=== Summary of implementation requirements | |||
== Summary of implementation requirements | |||
This summarizes the requirements of our implementation of AspectJ. For | |||
more details, see the relevant sections of this guide. |
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ Programming Guide | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -1,8 +1,8 @@ | |||
[[language]] | |||
== The AspectJ Language | |||
= The AspectJ Language | |||
[[language-intro]] | |||
=== Introduction | |||
== Introduction | |||
The previous chapter, xref:gettingstarted.adoc#starting[Getting Started with AspectJ], was a brief overview of the | |||
AspectJ language. You should read this chapter to understand AspectJ's | |||
@@ -14,13 +14,13 @@ of a pointcut, an introduction, and two pieces of advice. This example | |||
aspect will gives us something concrete to talk about. | |||
[[language-anatomy]] | |||
=== The Anatomy of an Aspect | |||
== The Anatomy of an Aspect | |||
This lesson explains the parts of AspectJ's aspects. By reading this | |||
lesson you will have an overview of what's in an aspect and you will be | |||
exposed to the new terminology introduced by AspectJ. | |||
==== An Example Aspect | |||
=== An Example Aspect | |||
Here's an example of an aspect definition in AspectJ: | |||
@@ -61,7 +61,7 @@ and methods, pointcut definitions, inter-type declarations, and advice, | |||
where advice may be before, after or around advice. The remainder of | |||
this lesson focuses on those crosscut-related constructs. | |||
==== Pointcuts | |||
=== Pointcuts | |||
AspectJ's pointcut definitions give names to pointcuts. Pointcuts | |||
themselves pick out join points, i.e. interesting points in the | |||
@@ -109,7 +109,7 @@ execution, and field access. Each kind of join point can be picked out | |||
by its own specialized pointcut that you will learn about in other parts | |||
of this guide. | |||
==== Advice | |||
=== Advice | |||
A piece of advice brings together a pointcut and a body of code to | |||
define aspect implementation that runs at join points picked out by the | |||
@@ -148,7 +148,7 @@ third kind of advice called around. You will see those in other parts of | |||
this guide. | |||
[[language-joinPoints]] | |||
=== Join Points and Pointcuts | |||
== Join Points and Pointcuts | |||
Consider the following Java class: | |||
@@ -221,7 +221,7 @@ separated by a colon. The left-hand side consists of the pointcut name | |||
and the pointcut parameters (i.e. the data available when the events | |||
happen). The right-hand side consists of the pointcut itself. | |||
==== Some Example Pointcuts | |||
=== Some Example Pointcuts | |||
Here are examples of pointcuts picking out | |||
@@ -302,7 +302,7 @@ in ``MyInterface``'s signature -- that is, any method defined by | |||
`MyInterface` or inherited by one of its a supertypes. | |||
[[call-vs-execution]] | |||
==== call vs. execution | |||
=== call vs. execution | |||
When methods and constructors run, there are two interesting times | |||
associated with them. That is when they are called, and when they | |||
@@ -335,7 +335,7 @@ use `execution`, but if you want to pick one that runs when a particular | |||
_signature_ is called (as is often the case for production aspects), use | |||
`call`. | |||
==== Pointcut composition | |||
=== Pointcut composition | |||
Pointcuts are put together with the operators and (spelled `&&`), or | |||
(spelled `||`), and not (spelled `!`). This allows the creation of very | |||
@@ -426,7 +426,7 @@ If this was not present a recursive call would result as the pointcut | |||
would apply to its own advice. (See xref:pitfalls.adoc#pitfalls-infiniteLoops[Infinite loops] | |||
for more details.) | |||
==== Pointcut Parameters | |||
=== Pointcut Parameters | |||
Consider again the first pointcut definition in this chapter: | |||
@@ -520,7 +520,7 @@ when calling `setY`, but the pointcut picks out all of these join points | |||
and tries to bind both `p1` and `p2`. | |||
[[example]] | |||
==== Example: `HandleLiveness` | |||
=== Example: `HandleLiveness` | |||
The example below consists of two object classes (plus an exception | |||
class) and one aspect. Handle objects delegate their public, non-static | |||
@@ -561,7 +561,7 @@ class DeadPartnerException extends RuntimeException {} | |||
.... | |||
[[pointcut-best-practice]] | |||
==== Writing good pointcuts | |||
=== Writing good pointcuts | |||
During compilation, AspectJ processes pointcuts in order to try and | |||
optimize matching performance. Examining code and determining if each | |||
@@ -603,7 +603,7 @@ processed - that is why a good pointcut should always include one if | |||
possible. | |||
[[language-advice]] | |||
=== Advice | |||
== Advice | |||
Advice defines pieces of aspect implementation that execute at | |||
well-defined points in the execution of the program. Those points can be | |||
@@ -710,7 +710,7 @@ void around(Point p, int x): | |||
.... | |||
[[language-interType]] | |||
=== Inter-type declarations | |||
== Inter-type declarations | |||
Aspects can declare members (fields, methods, and constructors) that are | |||
owned by other types. These are called inter-type members. Aspects can | |||
@@ -820,7 +820,7 @@ As you can see from the above example, an aspect can declare that | |||
interfaces have fields and methods, even non-constant fields and methods | |||
with bodies. | |||
==== Inter-type Scope | |||
=== Inter-type Scope | |||
AspectJ allows private and package-protected (default) inter-type | |||
declarations in addition to public inter-type declarations. Private | |||
@@ -843,7 +843,7 @@ int Foo.x; | |||
then everything in the aspect's package (which may or may not be ``Foo``'s | |||
package) can access `x`. | |||
==== Example: `PointAssertions` | |||
=== Example: `PointAssertions` | |||
The example below consists of one class and one aspect. The aspect | |||
privately declares the assertion methods of `Point`, `assertX` and | |||
@@ -888,7 +888,7 @@ aspect PointAssertions { | |||
.... | |||
[[language-thisJoinPoint]] | |||
=== `thisJoinPoint` | |||
== `thisJoinPoint` | |||
AspectJ provides a special reference variable, `thisJoinPoint`, that | |||
contains reflective information about the current join point for the |
@@ -1,13 +1,13 @@ | |||
== Pitfalls | |||
= Pitfalls | |||
[[pitfalls-intro]] | |||
=== Introduction | |||
== Introduction | |||
This chapter consists of a few AspectJ programs that may lead to | |||
surprising behavior and how to understand them. | |||
[[pitfalls-infiniteLoops]] | |||
=== Infinite loops | |||
== Infinite loops | |||
Here is a Java program with peculiar behavior | |||
@@ -1,4 +1,4 @@ | |||
== Preface | |||
= Preface | |||
This programming guide does three things. It | |||
@@ -1,6 +1,6 @@ | |||
= The AspectJ^TM^ Programming Guide | |||
:doctype: book | |||
:leveloffset: +1 | |||
_by the AspectJ Team_ | |||
@@ -1,8 +1,8 @@ | |||
[[quick]] | |||
== AspectJ Quick Reference | |||
= AspectJ Quick Reference | |||
[[quick-pointcuts]] | |||
=== Pointcuts | |||
== Pointcuts | |||
[cols=",",] | |||
|=== | |||
@@ -56,7 +56,7 @@ or constructor matching `Signature` | |||
|=== | |||
[[quick-typePatterns]] | |||
=== Type Patterns | |||
== Type Patterns | |||
A type pattern is one of | |||
@@ -90,7 +90,7 @@ An embedded `..` in an identifier matches any sequence of characters | |||
that starts and ends with the package (or inner-type) separator `.`. | |||
[[quick-advice]] | |||
=== Advice | |||
== Advice | |||
Each piece of advice is of the form | |||
@@ -130,7 +130,7 @@ Three special variables are available inside of advice bodies: | |||
the static part of the dynamically enclosing join point | |||
[[quick-interType]] | |||
=== Inter-type member declarations | |||
== Inter-type member declarations | |||
Each inter-type member is one of | |||
@@ -144,7 +144,7 @@ Each inter-type member is one of | |||
a field on `OnType` | |||
[[quick-other]] | |||
=== Other declarations | |||
== Other declarations | |||
`declare parents : TypePattern extends Type ;`:: | |||
the types in `TypePattern` extend `Type` | |||
@@ -164,7 +164,7 @@ Each inter-type member is one of | |||
precedence at that join point is in `TypePatternList` order | |||
[[quick-aspectAssociations]] | |||
=== Aspects | |||
== Aspects | |||
Each aspect is of the form | |||
@@ -1,8 +1,8 @@ | |||
[[semantics]] | |||
== Language Semantics | |||
= Language Semantics | |||
[[semantics-intro]] | |||
=== Introduction | |||
== Introduction | |||
AspectJ extends Java by overlaying a concept of join points onto the | |||
existing Java semantics and adding a few new program elements to Java: | |||
@@ -35,7 +35,7 @@ possible to do reasoning at compile time. Aspects are defined by the | |||
`aspect` declaration. | |||
[[semantics-joinPoints]] | |||
=== Join Points | |||
== Join Points | |||
While aspects define types that crosscut, the AspectJ system does not | |||
allow completely arbitrary crosscutting. Rather, aspects define types | |||
@@ -152,7 +152,7 @@ bodies or static initializers. | |||
methods or fields. | |||
[[semantics-pointcuts]] | |||
=== Pointcuts | |||
== Pointcuts | |||
A pointcut is a program element that picks out join points and exposes | |||
data from the execution context of those join points. Pointcuts are used | |||
@@ -233,7 +233,7 @@ provided by the language are: | |||
`( Pointcut )`:: | |||
Picks out each join points picked out by `_Pointcut_` . | |||
==== Pointcut definition | |||
=== Pointcut definition | |||
Pointcuts are defined and named by the programmer with the `pointcut` | |||
declaration. | |||
@@ -300,7 +300,7 @@ aspect B percflow(publicCall()) { | |||
} | |||
.... | |||
==== Context exposure | |||
=== Context exposure | |||
Pointcuts have an interface; they expose some parts of the execution | |||
context of the join points they pick out. For example, the PublicIntCall | |||
@@ -384,9 +384,9 @@ aspect IntToLong { | |||
The pointcut will match and expose the integer argument, but it will | |||
expose it as an `Integer`, not a `Long`. | |||
==== Primitive pointcuts | |||
=== Primitive pointcuts | |||
===== Method-related pointcuts | |||
==== Method-related pointcuts | |||
AspectJ provides two primitive pointcut designators designed to capture | |||
method call and execution join points. | |||
@@ -394,7 +394,7 @@ method call and execution join points. | |||
* `call( MethodPattern )` | |||
* `execution( MethodPattern )` | |||
===== Field-related pointcuts | |||
==== Field-related pointcuts | |||
AspectJ provides two primitive pointcut designators designed to capture | |||
field reference and set join points: | |||
@@ -419,7 +419,7 @@ aspect GuardedX { | |||
} | |||
.... | |||
===== Object creation-related pointcuts | |||
==== Object creation-related pointcuts | |||
AspectJ provides primitive pointcut designators designed to capture the | |||
initializer execution join points of objects. | |||
@@ -429,14 +429,14 @@ initializer execution join points of objects. | |||
* `initialization( ConstructorPattern )` | |||
* `preinitialization( ConstructorPattern )` | |||
===== Class initialization-related pointcuts | |||
==== Class initialization-related pointcuts | |||
AspectJ provides one primitive pointcut designator to pick out static | |||
initializer execution join points. | |||
* `staticinitialization( TypePattern )` | |||
===== Exception handler execution-related pointcuts | |||
==== Exception handler execution-related pointcuts | |||
AspectJ provides one primitive pointcut designator to capture execution | |||
of exception handlers: | |||
@@ -457,7 +457,7 @@ aspect NormalizeFooException { | |||
} | |||
.... | |||
===== Advice execution-related pointcuts | |||
==== Advice execution-related pointcuts | |||
AspectJ provides one primitive pointcut designator to capture execution | |||
of advice | |||
@@ -478,7 +478,7 @@ aspect TraceStuff { | |||
} | |||
.... | |||
===== State-based pointcuts | |||
==== State-based pointcuts | |||
Many concerns cut across the dynamic times when an object of a | |||
particular type is executing, being operated on, or being passed around. | |||
@@ -521,7 +521,7 @@ args(int, .., String) | |||
will pick out all join points where the first argument is an `int` and | |||
the last is a `String`. | |||
===== Control flow-based pointcuts | |||
==== Control flow-based pointcuts | |||
Some concerns cut across the control flow of the program. The `cflow` | |||
and `cflowbelow` primitive pointcut designators capture join points | |||
@@ -540,7 +540,7 @@ entry and exit of each join point `P` picked out by `Pointcut`, but not | |||
including `P` itself. Hence, it picks out the join points _below_ the | |||
control flow of the join points picked out by `Pointcut`. | |||
====== Context exposure from control flows | |||
===== Context exposure from control flows | |||
The `cflow` and `cflowbelow` pointcuts may expose context state through | |||
enclosed `this`, `target`, and `args` pointcuts. | |||
@@ -577,7 +577,7 @@ aspect A { | |||
It is an error to expose such state through _negated_ control flow | |||
pointcuts, such as within `!cflowbelow(P)`. | |||
===== Program text-based pointcuts | |||
==== Program text-based pointcuts | |||
While many concerns cut across the runtime structure of the program, | |||
some must deal with the lexical structure. AspectJ allows aspects to | |||
@@ -603,7 +603,7 @@ expressions of the method or constructor. It also includes any join | |||
points that are associated with code in a method or constructor's local | |||
or anonymous types. | |||
===== Expression-based pointcuts | |||
==== Expression-based pointcuts | |||
* `if( BooleanExpression )` | |||
@@ -623,13 +623,13 @@ a join point is undefined. Writing `if` pointcuts that have side-effects | |||
is considered bad style and may also lead to potentially confusing or | |||
even changing behavior with regard to when or if the test code will run. | |||
==== Signatures | |||
=== Signatures | |||
One very important property of a join point is its signature, which is | |||
used by many of AspectJ's pointcut designators to select particular join | |||
points. | |||
===== Methods | |||
==== Methods | |||
Join points associated with methods typically have method signatures, | |||
consisting of a method name, parameter types, return type, the types of | |||
@@ -645,7 +645,7 @@ means that the signature for the join point created from the call | |||
At a method execution join point, the signature is a method signature | |||
whose qualifying type is the declaring type of the method. | |||
===== Fields | |||
==== Fields | |||
Join points associated with fields typically have field signatures, | |||
consisting of a field name and a field type. A field reference join | |||
@@ -653,7 +653,7 @@ point has such a signature, and no parameters. A field set join point | |||
has such a signature, but has a has a single parameter whose type is the | |||
same as the field type. | |||
===== Constructors | |||
==== Constructors | |||
Join points associated with constructors typically have constructor | |||
signatures, consisting of a parameter types, the types of the declared | |||
@@ -669,7 +669,7 @@ signature is the constructor signature for the constructor that started | |||
this initialization: the first constructor entered during this type's | |||
initialization of this object. | |||
===== Others | |||
==== Others | |||
At a handler execution join point, the signature is composed of the | |||
exception type that the handler handles. | |||
@@ -679,7 +679,7 @@ aspect type, the parameter types of the advice, the return type (void | |||
for all but around advice) and the types of the declared (checked) | |||
exceptions. | |||
==== Matching | |||
=== Matching | |||
The `withincode`, `call`, `execution`, `get`, and `set` primitive | |||
pointcut designators all use signature patterns to determine the join | |||
@@ -796,7 +796,7 @@ private null constructor of a class `C` defined to throw an | |||
execution(private C.new() throws ArithmeticException) | |||
.... | |||
===== Matching based on the declaring type | |||
==== Matching based on the declaring type | |||
The signature-matching pointcuts all specify a declaring type, but the | |||
meaning varies slightly for each join point signature, in line with Java | |||
@@ -869,7 +869,7 @@ class Sub extends Middle { | |||
} | |||
.... | |||
===== Matching based on the `throws` clause | |||
==== Matching based on the `throws` clause | |||
Type patterns may be used to pick out methods and constructors based on | |||
their `throws` clauses. This allows the following two kinds of extremely | |||
@@ -927,13 +927,13 @@ declares that it `throws IOException`. | |||
[2] *will* match the method `m()`, because ``m``'s throws clause declares that | |||
it throws some exception which does not match `IOException`, i.e. `RuntimeException`. | |||
==== Type patterns | |||
=== Type patterns | |||
Type patterns are a way to pick out collections of types and use them in | |||
places where you would otherwise use only one type. The rules for using | |||
type patterns are simple. | |||
===== Exact type pattern | |||
==== Exact type pattern | |||
First, all type names are also type patterns. So `Object`, | |||
`java.util.HashMap`, `Map.Entry`, `int` are all type patterns. | |||
@@ -953,7 +953,7 @@ then the matching works just like normal type lookup in Java: | |||
So exact type patterns match based on usual Java scope rules. | |||
===== Type name patterns | |||
==== Type name patterns | |||
There is a special type name, `\*`, which is also a type pattern. `*` picks | |||
out all types, including primitive types. So | |||
@@ -1004,7 +1004,7 @@ Type patterns with wildcards do not depend on Java's usual scope rules - | |||
they match against all types available to the weaver, not just those | |||
that are imported into an Aspect's declaring file. | |||
===== Subtype patterns | |||
==== Subtype patterns | |||
It is possible to pick out all subtypes of a type (or a collection of | |||
types) with the `+` wildcard. The `+` wildcard follows immediately a | |||
@@ -1034,13 +1034,13 @@ call(*Handler+.new()) | |||
picks out all constructor call join points where an instance of any | |||
subtype of any type whose name ends in `Handler` is constructed. | |||
===== Array type patterns | |||
==== Array type patterns | |||
A type name pattern or subtype pattern can be followed by one or more | |||
sets of square brackets to make array type patterns. So `Object[]` is an | |||
array type pattern, and so is `com.xerox..*[][]`, and so is `Object+[]`. | |||
===== Type patterns | |||
==== Type patterns | |||
Type patterns are built up out of type name patterns, subtype patterns, | |||
and array type patterns, and constructed with boolean operators `&&`, | |||
@@ -1062,7 +1062,7 @@ call((Foo+ && ! Foo).new(..)) | |||
picks out the constructor call join points when a subtype of `Foo`, but | |||
not `Foo` itself, is constructed. | |||
==== Pattern Summary | |||
=== Pattern Summary | |||
Here is a summary of the pattern syntax used in AspectJ: | |||
@@ -1093,7 +1093,7 @@ ModifiersPattern = | |||
.... | |||
[[semantics-advice]] | |||
=== Advice | |||
== Advice | |||
Each piece of advice is of the form | |||
@@ -1338,13 +1338,13 @@ prove that there won't be a runtime binary-compatible change in the | |||
hierarchy of `LinkedList` or some other advice on the join point that | |||
requires a `LinkedList`. | |||
==== Advice modifiers | |||
=== Advice modifiers | |||
The `strictfp` modifier is the only modifier allowed on advice, and it | |||
has the effect of making all floating-point expressions within the | |||
advice be FP-strict. | |||
==== Advice and checked exceptions | |||
=== Advice and checked exceptions | |||
An advice declaration must include a `throws` clause listing the checked | |||
exceptions the body may throw. This list of checked exceptions must be | |||
@@ -1394,12 +1394,12 @@ pre-initialization and initialization:: | |||
advice execution:: | |||
any exception that is in the `throws` clause of the advice. | |||
==== Advice precedence | |||
=== Advice precedence | |||
Multiple pieces of advice may apply to the same join point. In such | |||
cases, the resolution order of the advice is based on advice precedence. | |||
===== Determining precedence | |||
==== Determining precedence | |||
There are a number of rules that determine whether a particular piece of | |||
advice has precedence over another when they advise the same join point. | |||
@@ -1438,7 +1438,7 @@ aspect A { | |||
such circularities will result in errors signalled by the compiler. | |||
===== Effects of precedence | |||
==== Effects of precedence | |||
At a particular join point, advice is ordered by precedence. | |||
@@ -1466,7 +1466,7 @@ Running `after` advice will run the advice of next precedence, or the | |||
computation under the join point if there is no further advice. Then the | |||
body of the advice will run. | |||
==== Reflective access to the join point | |||
=== Reflective access to the join point | |||
Three special variables are visible within bodies of advice and within | |||
`if()` pointcut expressions: `thisJoinPoint`, `thisJoinPointStaticPart`, | |||
@@ -1503,14 +1503,14 @@ to `thisJoinPoint` is `org.aspectj.lang.JoinPoint`, while | |||
`org.aspectj.lang.JoinPoint.StaticPart`. | |||
[[semantics-declare]] | |||
=== Static crosscutting | |||
== Static crosscutting | |||
Advice declarations change the behavior of classes they crosscut, but do | |||
not change their static type structure. For crosscutting concerns that | |||
do operate over the static structure of type hierarchies, AspectJ | |||
provides inter-type member declarations and other `declare` forms. | |||
==== Inter-type member declarations | |||
=== Inter-type member declarations | |||
AspectJ allows the declaration of members by aspects that are associated | |||
with other types. | |||
@@ -1576,7 +1576,7 @@ inter-type field declaration, refers to the `OnType` object rather than | |||
to the aspect type; it is an error to access `this` in such a position | |||
from a `static` inter-type member declaration. | |||
==== Access modifiers | |||
=== Access modifiers | |||
Inter-type member declarations may be `public` or `private`, or have default | |||
(package-protected) visibility. AspectJ does not provide protected | |||
@@ -1604,7 +1604,7 @@ public interface. This is illegal because it would say that a public | |||
interface has a constraint that only non-public implementors must | |||
fulfill. This would not be compatible with Java's type system. | |||
==== Conflicts | |||
=== Conflicts | |||
Inter-type declarations raise the possibility of conflicts among locally | |||
declared members and inter-type members. For example, assuming | |||
@@ -1663,7 +1663,7 @@ This is true both when the precedence is declared explicitly with | |||
`declare precedence` as well as when when sub-aspects implicitly have | |||
precedence over their super-aspect. | |||
==== Extension and Implementation | |||
=== Extension and Implementation | |||
An aspect may change the inheritance hierarchy of a system by changing | |||
the superclass of a type or adding a superinterface onto a type, with | |||
@@ -1687,7 +1687,7 @@ aspect A { | |||
} | |||
.... | |||
==== Interfaces with members | |||
=== Interfaces with members | |||
Through the use of inter-type members, interfaces may now carry | |||
(non-public-static-final) fields and (non-public-abstract) methods that | |||
@@ -1721,7 +1721,7 @@ when a new `E` is instantiated, the initializers run in this order: | |||
Object M C O N D Q P E | |||
.... | |||
==== Warnings and Errors | |||
=== Warnings and Errors | |||
An aspect may specify that a particular join point should never be | |||
reached. | |||
@@ -1733,7 +1733,7 @@ If the compiler determines that a join point in `Pointcut` could | |||
possibly be reached, then it will signal either an error or warning, as | |||
declared, using the `String` for its message. | |||
==== Softened exceptions | |||
=== Softened exceptions | |||
An aspect may specify that a particular kind of exception, if thrown at | |||
a join point, should bypass Java's usual static exception checking | |||
@@ -1790,7 +1790,7 @@ abstract aspect A { | |||
.... | |||
[[advice-precedence-cross]] | |||
==== Advice Precedence | |||
=== Advice Precedence | |||
An aspect may declare a precedence relationship between concrete aspects | |||
with the `declare precedence` form: | |||
@@ -1844,7 +1844,7 @@ aspect CountEntry { | |||
} | |||
.... | |||
===== Various cycles | |||
==== Various cycles | |||
It is an error for any aspect to be matched by more than one TypePattern | |||
in a single decare precedence, so: | |||
@@ -1868,7 +1868,7 @@ And a system in which both constraints are active may also be legal, so | |||
long as advice from `A` and `B` don't share a join point. So this is an | |||
idiom that can be used to enforce that `A` and `B` are strongly independent. | |||
===== Applies to concrete aspects | |||
==== Applies to concrete aspects | |||
Consider the following library aspects: | |||
@@ -1922,7 +1922,7 @@ declare precedence: Logging+, Profiling+; | |||
are meaningful. | |||
==== Statically determinable pointcuts | |||
=== Statically determinable pointcuts | |||
Pointcuts that appear inside of `declare` forms have certain | |||
restrictions. Like other pointcuts, these pick out join points, but they | |||
@@ -1943,17 +1943,17 @@ defined in terms of | |||
all of which can discriminate on runtime information. | |||
[[semantics-aspects]] | |||
=== Aspects | |||
== Aspects | |||
An aspect is a crosscutting type defined by the `aspect` declaration. | |||
==== Aspect Declaration | |||
=== Aspect Declaration | |||
The `aspect` declaration is similar to the `class` declaration in that | |||
it defines a type and an implementation for that type. It differs in a | |||
number of ways: | |||
===== Aspect implementation can cut across other types | |||
==== Aspect implementation can cut across other types | |||
In addition to normal Java class declarations such as methods and | |||
fields, aspect declarations can include AspectJ declarations such as | |||
@@ -1961,45 +1961,45 @@ advice, pointcuts, and inter-type declarations. Thus, aspects contain | |||
implementation declarations that can can cut across other types | |||
(including those defined by other aspect declarations). | |||
===== Aspects are not directly instantiated | |||
==== Aspects are not directly instantiated | |||
Aspects are not directly instantiated with a new expression, with | |||
cloning, or with serialization. Aspects may have one constructor | |||
definition, but if so it must be of a constructor taking no arguments | |||
and throwing no checked exceptions. | |||
===== Nested aspects must be `static` | |||
==== Nested aspects must be `static` | |||
Aspects may be defined either at the package level, or as a `static` | |||
nested aspect -- that is, a `static` member of a class, interface, or | |||
aspect. If it is not at the package level, the aspect _must_ be defined | |||
with the `static` keyword. Local and anonymous aspects are not allowed. | |||
==== Aspect Extension | |||
=== Aspect Extension | |||
To support abstraction and composition of crosscutting concerns, aspects | |||
can be extended in much the same way that classes can. Aspect extension | |||
adds some new rules, though. | |||
===== Aspects may extend classes and implement interfaces | |||
==== Aspects may extend classes and implement interfaces | |||
An aspect, abstract or concrete, may extend a class and may implement a | |||
set of interfaces. Extending a class does not provide the ability to | |||
instantiate the aspect with a new expression: The aspect may still only | |||
define a null constructor. | |||
===== Classes may not extend aspects | |||
==== Classes may not extend aspects | |||
It is an error for a class to extend or implement an aspect. | |||
===== Aspects extending aspects | |||
==== Aspects extending aspects | |||
Aspects may extend other aspects, in which case not only are fields and | |||
methods inherited but so are pointcuts. However, aspects may only extend | |||
abstract aspects. It is an error for a concrete aspect to extend another | |||
concrete aspect. | |||
==== Aspect instantiation | |||
=== Aspect instantiation | |||
Unlike class expressions, aspects are not instantiated with `new` | |||
expressions. Rather, aspect instances are automatically created to cut | |||
@@ -2015,7 +2015,7 @@ then by default the aspect is a singleton aspect. How an aspect is | |||
instantiated controls the form of the `aspectOf(..)` method defined on | |||
the concrete aspect class. | |||
===== Singleton Aspects | |||
==== Singleton Aspects | |||
* `aspect Id { ... }` | |||
* `aspect Id issingleton() { ... }` | |||
@@ -2035,7 +2035,7 @@ chance to run at all such join points. | |||
the aspect `A`, so there will be one instantiation for each time `A` is | |||
loaded by a different classloader.) | |||
===== Per-object aspects | |||
==== Per-object aspects | |||
* `aspect Id perthis( Pointcut ) { ... }` | |||
* `aspect Id pertarget( Pointcut ) { ... }` | |||
@@ -2062,7 +2062,7 @@ Both `perthis` and `pertarget` aspects may be affected by code the | |||
AspectJ compiler controls, as discussed in the xref:implementation.adoc#implementation[Implementation Notes] | |||
appendix. | |||
===== Per-control-flow aspects | |||
==== Per-control-flow aspects | |||
* `aspect Id percflow( Pointcut ) { ... }` | |||
* `aspect Id percflowbelow( Pointcut ) { ... }` | |||
@@ -2076,7 +2076,7 @@ under that control flow. During each such flow of control, the static | |||
method `A.aspectOf()` will return an object of type `A`. An instance of | |||
the aspect is created upon entry into each such control flow. | |||
===== Aspect instantiation and advice | |||
==== Aspect instantiation and advice | |||
All advice runs in the context of an aspect instance, but it is possible | |||
to write a piece of advice with a pointcut that picks out a join point | |||
@@ -2111,7 +2111,7 @@ compile time. If advice runs before its aspect is instantiated, AspectJ | |||
will throw a | |||
xref:../api/org/aspectj/lang/NoAspectBoundException.html[`org.aspectj.lang.NoAspectBoundException`]. | |||
==== Aspect privilege | |||
=== Aspect privilege | |||
* `privileged aspect Id { ... }` | |||
@@ -1,5 +1,5 @@ | |||
[[readme-1_1]] | |||
== AspectJ 1.1 | |||
= AspectJ 1.1 | |||
_© Copyright 2002 Palo Alto Research Center, Incorporated, 2003 | |||
Contributors. All rights reserved._ | |||
@@ -32,7 +32,7 @@ xref:#knownLimitations[known limitations]. | |||
''''' | |||
[[language]] | |||
=== The Language | |||
== The Language | |||
AspectJ 1.1 is a slightly different language than AspectJ 1.0. In all | |||
but a few cases, programs written in AspectJ 1.0 should compile | |||
@@ -119,7 +119,7 @@ specifier] in this release, but it may well be in a future release. | |||
''''' | |||
[[compiler]] | |||
=== The Compiler | |||
== The Compiler | |||
The compiler for AspectJ 1.1 is different than the compiler for AspectJ | |||
1.0. While this document describes the differences in the compiler, it's | |||
@@ -194,7 +194,7 @@ xref:#ONE_FOUR_METHOD_SIGNATURES[the -1.4 flag]. | |||
''''' | |||
[[tools]] | |||
=== Support Tools | |||
== Support Tools | |||
This release includes an Ant task for old-style 1.0 build scripts, a new | |||
task for all the new compiler options, and a CompilerAdapter to support | |||
@@ -224,7 +224,7 @@ support is available. | |||
''''' | |||
[[runtime]] | |||
=== The Runtime Library | |||
== The Runtime Library | |||
This release has minor additions to the runtime library classes. As with | |||
any release, you should compile and run with the runtime library that | |||
@@ -240,7 +240,7 @@ and will always return 0. | |||
''''' | |||
[[devenv]] | |||
=== The AJDE Tools | |||
== The AJDE Tools | |||
The AspectJ Browser supports incremental compilation and running | |||
programs. AJDE for JBuilder, AJDE for NetBeans, and AJDE for Emacs are | |||
@@ -250,7 +250,7 @@ the batch-build mode of the new compiler. | |||
''''' | |||
[[sources]] | |||
=== The Sources and the Licenses | |||
== The Sources and the Licenses | |||
The AspectJ tools sources are available under the | |||
https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public | |||
@@ -260,7 +260,7 @@ more information, see the FAQ entry on building sources. | |||
''''' | |||
[[distribution]] | |||
=== The AspectJ distribution | |||
== The AspectJ distribution | |||
AspectJ 1.0 had many distributions - for the tools, the documentation, | |||
each IDE support package, their respective sources, and the Ant tasks - | |||
@@ -278,10 +278,10 @@ SourceForge projects. | |||
''''' | |||
[[details]] | |||
=== Details of some language and compiler changes | |||
== Details of some language and compiler changes | |||
[[ASPECT_INSTANTIATION_AND_ADVICE]] | |||
==== Aspect Instantiation and Advice | |||
=== Aspect Instantiation and Advice | |||
In AspectJ 1.0.6, we made an effort to hide some complications with | |||
Aspect instantiation from the user. In particular, the following code | |||
@@ -347,7 +347,7 @@ both of the above programs will throw | |||
org.aspectj.lang.NoAspectBoundException. | |||
[[THROWS_PATTERN]] | |||
==== Matching based on throws | |||
=== Matching based on throws | |||
Type patterns may now be used to pick out methods and constructors based | |||
on their throws clauses. This allows the following two kinds of | |||
@@ -409,7 +409,7 @@ because method m's throws clause declares the it throws some exception | |||
which does not match IOException, i.e. RuntimeException. | |||
[[NEW_PCDS]] | |||
==== New kinded pointcut designators | |||
=== New kinded pointcut designators | |||
AspectJ 1.0 does not provide kinded pointcut designators for two (rarely | |||
used) join points: preinitialization (the code that runs before a super | |||
@@ -427,7 +427,7 @@ join points where the initialization process is entered through | |||
`ConstructorPattern`. | |||
[[PER_TYPE]] | |||
==== New pertype aspect specifier (not in 1.1) | |||
=== New pertype aspect specifier (not in 1.1) | |||
We strongly considered adding a pertype aspect kind to 1.1. This is | |||
somewhat motivated by the new | |||
@@ -471,7 +471,7 @@ the most common uses of this idiom. | |||
In any case, this feature will not be in AspectJ 1.1. | |||
[[SINGLE_INTERCLASS_TARGET]] | |||
==== One target for intertype declarations | |||
=== One target for intertype declarations | |||
Intertype declarations (once called "introductions") in AspectJ 1.1 can | |||
only have one target type. So the following code intended to declare | |||
@@ -506,7 +506,7 @@ xref:#PER_TYPE[pertype proposal] provides this functionality in a much | |||
more usable form. | |||
[[UNAVAILABLE_JOIN_POINTS]] | |||
==== No initializer execution join points | |||
=== No initializer execution join points | |||
AspectJ 1.1 does not consider initializer execution a principled join | |||
point. The collection of initializer code (the code that sets fields | |||
@@ -515,14 +515,14 @@ something that makes sense only in Java source code, not in Java | |||
bytecode. | |||
[[AFTER_HANDLER]] | |||
==== No after or around advice on handler join points | |||
=== No after or around advice on handler join points | |||
The end of an exception handler is underdetermined in bytecode, so ajc | |||
will not implement after or around advice on handler join points, | |||
instead signaling a compile-time error. | |||
[[CONSTRUCTOR_EXECUTION_IS_BIGGER]] | |||
==== Initializers run inside constructor execution join points | |||
=== Initializers run inside constructor execution join points | |||
The code generated by the initializers in Java source code now runs | |||
inside of constructor execution join points. This changes how before | |||
@@ -560,7 +560,7 @@ assume incomplete object initialization, since the constructor has not | |||
yet run. | |||
[[INTER_TYPE_FIELD_INITIALIZERS]] | |||
==== Inter-type field initializers | |||
=== Inter-type field initializers | |||
The initializer, if any, of an inter-type field definition runs before | |||
the class-local initializers of its target class. | |||
@@ -588,7 +588,7 @@ method (thus incrementing the method count) and then the field was reset | |||
to zero after the constructor was done. | |||
[[WITHIN_MEMBER_TYPES]] | |||
==== Small limitations of the within pointcut | |||
=== Small limitations of the within pointcut | |||
Because of the guarantees made (and not made) by the Java classfile | |||
format, there are cases where AspectJ 1.1 cannot guarantee that the | |||
@@ -627,13 +627,13 @@ We believe the non-guarantee is small, and we haven't verified that it | |||
is a problem in practice. | |||
[[WITHIN_CODE]] | |||
==== Small limitations of the withincode pointcut | |||
=== Small limitations of the withincode pointcut | |||
The withincode pointcut has similar issues to those described above for | |||
within. | |||
[[INSTANCEOF_ON_WILD]] | |||
==== Can't do instanceof matching on type patterns with wildcard | |||
=== Can't do instanceof matching on type patterns with wildcard | |||
The pointcut designators this, target and args specify a dynamic test on | |||
their argument. These tests can not be performed on type patterns with | |||
@@ -680,7 +680,7 @@ match any code lexically within one of your classes or a subtype | |||
thereof. This is often a good choice. | |||
[[NO_SOURCE_COLUMN]] | |||
==== SourceLocation.getColumn() | |||
=== SourceLocation.getColumn() | |||
The Java .class file format contains information about the source file | |||
and line numbers of its contents; however, it has no information about | |||
@@ -690,7 +690,7 @@ thisJoinPoint.getSourceLocation().getColumn() will be marked as | |||
deprecated by the compiler, and will always return 0. | |||
[[ASPECT_PRECEDENCE]] | |||
==== Aspect precedence | |||
=== Aspect precedence | |||
AspectJ 1.1 has a new declare form: | |||
@@ -713,7 +713,7 @@ declare precedence: *..*Security*, Logging+, *; | |||
In the TypePatternList, the wildcard * means "any type not matched by | |||
another type in the declare precedence". | |||
===== Various cycles | |||
==== Various cycles | |||
It is an error for any aspect to be matched by more than one TypePattern | |||
in a single declare precedence, so: | |||
@@ -737,7 +737,7 @@ And a system in which both constraints are active may also be legal, so | |||
long as advice from A and B don't share a join point. So this is an | |||
idiom that can be used to enforce that A and B are strongly independent. | |||
===== Applies to concrete aspects | |||
==== Applies to concrete aspects | |||
Consider the following library aspects: | |||
@@ -783,7 +783,7 @@ simple: | |||
declare precedence: MyLogging, MyProfiling; | |||
.... | |||
===== Changing order of advice for sub-aspects | |||
==== Changing order of advice for sub-aspects | |||
By default, advice in a sub-aspect has more precedence than advice in a | |||
super-aspect. One use of the AspectJ 1.0 dominates form was to change | |||
@@ -813,7 +813,7 @@ matters for concrete aspects. Thus, if you want to regain this kind of | |||
precedence change, you will need to refactor your aspects. | |||
[[SOURCEROOT]] | |||
==== The -sourceroots option | |||
=== The -sourceroots option | |||
The AspectJ 1.1 compiler now accepts a -sourceroots option used to pass | |||
all .java files in particular directories to the compiler. It takes | |||
@@ -835,7 +835,7 @@ This option may be used in conjunction with lst files, listing .java | |||
files on the command line, and the -injars option. | |||
[[BYTECODE_WEAVING]] | |||
==== The -injars option | |||
=== The -injars option | |||
The AspectJ 1.1 compiler now accepts an -injars option used to pass all | |||
.class files in a particular jar file to the compiler. It takes either a | |||
@@ -862,7 +862,7 @@ This option may be used in conjunction with lst files, listing .java | |||
files on the command line, and the -sourceroots option. | |||
[[OUTJAR]] | |||
==== The -outjar option | |||
=== The -outjar option | |||
The -outjar option takes the name of a jar file into which the results | |||
of the compilation should be put. For example: | |||
@@ -875,7 +875,7 @@ ajc -injars myBase.jar MyTracing.java -outjar myTracedBase.jar | |||
No meta information is placed in the output jar file. | |||
[[INCREMENTAL]] | |||
==== Incremental compilation | |||
=== Incremental compilation | |||
The AspectJ 1.1 compiler now supports incremental compilation. When ajc | |||
is called with the -incremental option, it must also be passed a | |||
@@ -884,12 +884,12 @@ Once the initial compile is done, ajc waits for console input. Every | |||
time it reads a new line (i.e., every time the user hits return) ajc | |||
recompiles those input files that need recompiling. | |||
===== Limitations | |||
==== Limitations | |||
This new functionality is still only lightly tested. | |||
[[XNOWEAVE]] | |||
==== -XnoWeave, a compiler option to suppress weaving | |||
=== -XnoWeave, a compiler option to suppress weaving | |||
The -XnoWeave option suppresses weaving, and generates classfiles and | |||
that can be passed to ajc again (through the -injars option) to generate | |||
@@ -903,7 +903,7 @@ cases for unwoven classfiles, but we've moved the flag to experimental | |||
status. | |||
[[BINARY_ASPECTS]] | |||
==== -aspectpath, working with aspects in .class/.jar form | |||
=== -aspectpath, working with aspects in .class/.jar form | |||
When aspects are compiled into classfiles, they include all information | |||
necessary for the ajc compiler to weave their advice and deal with their | |||
@@ -914,7 +914,7 @@ and any aspects that are found will be enabled during the compilation. | |||
The binary forms of this aspects will be untouched. | |||
[[NO_CALLEE_SIDE_CALL]] | |||
==== Callee-side call join points | |||
=== Callee-side call join points | |||
The 1.0 implementation of AspectJ, when given: | |||
@@ -1023,7 +1023,7 @@ How will this affect developers? | |||
calling code or use the execution PCD instead. | |||
[[OTHER_X_OPTIONS]] | |||
==== Various -X options | |||
=== Various -X options | |||
The AspectJ 1.0 compiler supported a number of options that started with | |||
X, for "experimental". Some of them will not be supported in 1.1, either | |||
@@ -1042,7 +1042,7 @@ because we're now always using (what we believe to be) safe prefixes. | |||
* -Xlint: Still supported, with xref:#XLINT[various options]. | |||
[[ERROR_MESSAGES]] | |||
==== Some confusing error messages | |||
=== Some confusing error messages | |||
Building on the eclipse compiler has given us access to a very | |||
sophisticated problem reporting system as well as highly optimized error | |||
@@ -1053,7 +1053,7 @@ single small syntax error will produce dozens of other messages. Please | |||
report any very confusing error messages as bugs. | |||
[[MESSAGE_CONTEXT]] | |||
==== Source code context is not shown for errors and warnings detected during bytecode weaving | |||
=== Source code context is not shown for errors and warnings detected during bytecode weaving | |||
For compiler errors and warnings detected during bytecode weaving, | |||
source code context will not be displayed. In particular, for declare | |||
@@ -1064,7 +1064,7 @@ available, we might specify the signature of the offending code. For | |||
more information, see bug 31724. | |||
[[XLINT]] | |||
==== The -Xlint option | |||
=== The -Xlint option | |||
`-Xlint:ignore,error,warning` will set the level for all Xlint warnings. | |||
`-Xlint`, alone, is an abbreviation for `-Xlint:warning`. | |||
@@ -1081,26 +1081,26 @@ potentially unsafe casts used by very polymorphic uses of proceed in | |||
around advice. | |||
[[NO_SOURCE]] | |||
==== Source-specific options | |||
=== Source-specific options | |||
Because AspectJ 1.1 does not generate source code after weaving, the | |||
source-code-specific options -preprocess, -usejavac, -nocomment and | |||
-workingdir options are meaningless and so not supported. | |||
[[NO_STRICT_LENIENT]] | |||
==== The -strict and -lenient options | |||
=== The -strict and -lenient options | |||
Because AspectJ 1.1 uses the Eclipse compiler, which has its own | |||
mechanism for changing strictness, we no longer support the -strict and | |||
-lenient options. | |||
[[NO_PORTING]] | |||
==== The -porting option | |||
=== The -porting option | |||
AspectJ 1.1 does not have a -porting option. | |||
[[_13_REQUIRED]] | |||
==== J2SE 1.3 required | |||
=== J2SE 1.3 required | |||
Because we build on Eclipse, the compiler will no longer run under J2SE | |||
1.2. You must run the compiler (and all tools based on the compiler) | |||
@@ -1109,7 +1109,7 @@ run on Java 1.1 or later VM's if compiled against the correct runtime | |||
libraries. | |||
[[DEFAULT_CONSTRUCTOR_CONFLICT]] | |||
==== Default constructors | |||
=== Default constructors | |||
AspectJ 1.1 does not allow the inter-type definition of a zero-argument | |||
constructor on a class with a visible default constructor. So this is no | |||
@@ -1135,7 +1135,7 @@ classfiles. Therefore, it was an oversight that AspectJ 1.0.6 allowed | |||
such an "overriding" inter-type constructor definition. | |||
[[SUPER_IFACE_INITS]] | |||
==== Initialization join points for super-interfaces | |||
=== Initialization join points for super-interfaces | |||
In AspectJ, interfaces may have non-static members due to inter-type | |||
declarations. Because of this, the semantics of AspectJ defines the | |||
@@ -1182,7 +1182,7 @@ for its superinterfaces. | |||
____ | |||
[[VOID_FIELD_SET]] | |||
==== Field Set Join Points | |||
=== Field Set Join Points | |||
In AspectJ 1.0.6, the join point for setting a field F had, as a return | |||
type, F's type. This was "java compatible" because field assignment in | |||
@@ -1233,7 +1233,7 @@ is the last possibility to make the semantics more useful, we have made | |||
set join points have a void return type in 1.1. | |||
[[XNOINLINE]] | |||
==== The -XnoInline Option | |||
=== The -XnoInline Option | |||
The `-XnoInline` option to indicate that no inlining of any kind should | |||
be done. This is purely a compiler pragma: No program semantics (apart | |||
@@ -1241,7 +1241,7 @@ from stack traces) will be changed by the presence or absence of this | |||
option. | |||
[[TARGET_TYPES_MADE_PUBLIC]] | |||
==== Target types made public | |||
=== Target types made public | |||
Even in 1.0.6, the AspectJ compiler has occasionally needed to convert | |||
the visibility of a package-level class to a public one. This was | |||
@@ -1260,7 +1260,7 @@ not encounter them as such a concern when they were done in the 1.0.6 | |||
implementation. | |||
[[STRINGBUFFER]] | |||
==== String + now advised | |||
=== String + now advised | |||
In Java, the + operator sometimes results in StringBuffer objects being | |||
created, appended to, and used to generate a new String. Thus, | |||
@@ -1319,7 +1319,7 @@ call(* *(int)) && args(i) && !target(StringBuffer) | |||
.... | |||
[[ONE_FOUR_METHOD_SIGNATURES]] | |||
==== The -1.4 flag and method signatures | |||
=== The -1.4 flag and method signatures | |||
Consider the following aspect | |||
@@ -1358,7 +1358,7 @@ a call site, but only want to know the dynamic instanceof behavior which | |||
is what the target matching will handle. | |||
[[knownLimitations]] | |||
=== Known limitations | |||
== Known limitations | |||
The AspectJ 1.1.0 release contains a small number of known limitations | |||
relative to the AspectJ 1.1 language. For the most up-to-date |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.2.1 | |||
= AspectJ 1.2.1 | |||
_© Copyright 2004 Contributors. All rights reserved._ | |||
@@ -25,7 +25,7 @@ of ajc | |||
See the link:changes.html[changes document] for more details, or | |||
xref:#allchanges[all the changes] as detailed in the bugzilla database. | |||
=== Weaver Informational Messages | |||
== Weaver Informational Messages | |||
The AspectJ 1.2.1 compiler can produce informational messages about the | |||
weaving process. To see these messages, use the -showWeaveInfo compiler | |||
@@ -48,7 +48,7 @@ Type 'tjp.Demo' (Demo.java:34) advised by around advice from 'tjp.GetInfo' | |||
(GetInfo.java:26) [RuntimeTest=true] | |||
.... | |||
=== Dump Support | |||
== Dump Support | |||
In the event of a compiler crash, AspectJ 1.2.1 will produce a dump file | |||
giving important information about the state of the compiler at the time | |||
@@ -61,11 +61,11 @@ detected, the AspectJ 1.2.1 compiler can also be requested to create a | |||
dump file on detection of a compilation error. Set the property | |||
org.aspectj.weaver.Dump.condition=error to enable this behaviour. | |||
=== JDT Compiler Version | |||
== JDT Compiler Version | |||
AspectJ 1.2.1 is based on the Eclipse 3.0 final JDT compiler. | |||
=== Line Number Information for Join Points | |||
== Line Number Information for Join Points | |||
For source files compiled by ajc (as opposed to binary inputs to the | |||
compiler compiled with some other java compiler), ajc now emits better | |||
@@ -75,7 +75,7 @@ example by a declare error or declare warning statement), ajc 1.2.1 | |||
reports the first line number of the declaration, as opposed to the line | |||
number of the first line of code in the body. | |||
=== Runtime Performance | |||
== Runtime Performance | |||
AspectJ 1.2.1 contains a small number of runtime performance | |||
optimisations, including optimisations of if(true) and if(false) | |||
@@ -87,7 +87,7 @@ programs compiled under AspectJ 1.2.1 and that make heavy use of cflow | |||
will run significantly faster. Thanks to the abc compiler team for | |||
detecting this performance related bug and for piloting the fix. | |||
=== String Concatentation in Declare Error/Warning Statements | |||
== String Concatentation in Declare Error/Warning Statements | |||
String concatentation in declare error and warning statements is now | |||
supported. For example, you can write: | |||
@@ -99,7 +99,7 @@ declare warning : jdbcCall() && !inDataLayer() | |||
"outside of the data layer."; | |||
.... | |||
=== Load-time Weaving Support | |||
== Load-time Weaving Support | |||
The AspectJ 1.2.1 distribution contains a new jar in the lib directory, | |||
aspectjweaver.jar, that contains the subset of aspectjtools.jar needed | |||
@@ -112,7 +112,7 @@ doc/examples/ltw directory in the 1.2 distribution has been moved into | |||
the regular bin directory. See xref:README-1.2.adoc[README-1.2] for | |||
details of using this script. | |||
=== Binary Compatibility | |||
== Binary Compatibility | |||
AspectJ 1.2.1 introduces a backwards-incompatible change to the class | |||
file format generated by the AspectJ compiler. Classes generated by ajc | |||
@@ -127,7 +127,7 @@ comes with the distribution you used to build your application. | |||
''''' | |||
[[allchanges]] | |||
=== All changes are listed in the bug database | |||
== All changes are listed in the bug database | |||
For a complete list of changes in the 1.2.1 release, search for | |||
`target 1.2.1` in the bug database: |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.2 | |||
= AspectJ 1.2 | |||
_© Copyright 2003,2004 Contributors. All rights reserved._ | |||
@@ -25,7 +25,7 @@ readers to the bug database for xref:#allchanges[all the changes]. | |||
''''' | |||
[[compiler]] | |||
=== The Compiler | |||
== The Compiler | |||
Compared to AspectJ 1.1.1, the AspectJ 1.2 compiler... | |||
@@ -56,7 +56,7 @@ ajc]. | |||
''''' | |||
[[tools]] | |||
=== Support Tools | |||
== Support Tools | |||
AspectJ 1.2 contains two important changes to the supporting tools: | |||
@@ -67,7 +67,7 @@ command-line. | |||
''''' | |||
[[runtime]] | |||
=== The Runtime Library | |||
== The Runtime Library | |||
This release has minor updates to the runtime library classes. As with | |||
any release, you should compile and run with the runtime library that | |||
@@ -86,7 +86,7 @@ heap usage for multi-threaded applications that use cflow. | |||
''''' | |||
[[devenv]] | |||
=== The AJDE Tools | |||
== The AJDE Tools | |||
The AJDE based tools for JBuilder, NetBeans and Emacs continue to be | |||
independent SourceForge projects. The AspectJ 1.2 distribution includes | |||
@@ -104,10 +104,10 @@ https://www.eclipse.org/ajdt[AJDT project website]. | |||
''''' | |||
[[details]] | |||
=== Details of some compiler changes | |||
== Details of some compiler changes | |||
[[WEAVE_TIME]] | |||
==== Compilation (weave) times reduced. | |||
=== Compilation (weave) times reduced. | |||
Our benchmark suite shows that AspectJ 1.2 is at least twice as fast in | |||
the weaving phase as AspectJ 1.1.1 for matches based on a variety of | |||
@@ -123,7 +123,7 @@ performance and memory usage. Experiments forcing GC showed that we can | |||
achieve about a 20% memory usage reduction in this manner if needed. | |||
[[LAZY_TJP]] | |||
==== The -XlazyTjp option. | |||
=== The -XlazyTjp option. | |||
Under AspectJ 1.1.1, if the body of an advice contained a reference to a | |||
non-statically determinable portion of `thisJoinPoint` (such as for | |||
@@ -161,7 +161,7 @@ issues. The optimization is disabled at join points advised by around | |||
advice, and an Xlint warning will be displayed in these cases. | |||
[[INCREMENTAL]] | |||
==== Improvements to incremental compilation. | |||
=== Improvements to incremental compilation. | |||
AspectJ 1.2 provides more complete incremental compilation support than | |||
AspectJ 1.1.1. Firstly, incremental compilation resulting from a change | |||
@@ -179,7 +179,7 @@ detected, but will trigger a full rebuild, as will any change to the | |||
paths used to control compilation. | |||
[[ERROR_MESSAGES]] | |||
==== Improved error messages. | |||
=== Improved error messages. | |||
AspectJ 1.1.1 did not provide source context information for messages | |||
produced during the weaving phase, even in the case where source files | |||
@@ -234,7 +234,7 @@ file called `BadClass.java`, contains a join point | |||
line 5 of the file `DeclareError.java`. | |||
[[LINT]] | |||
==== New lint warnings. | |||
=== New lint warnings. | |||
Consider the program: | |||
@@ -326,7 +326,7 @@ process of weaving makes an incompatible change to a serializable class | |||
(for example, through the addition of an inter-type declared field). | |||
[[REWEAVABLE]] | |||
==== The -Xreweavable option. | |||
=== The -Xreweavable option. | |||
The new `-Xreweavable` option produces class files that contain enough | |||
additional information in them that they can be rewoven. In time we hope | |||
@@ -347,7 +347,7 @@ during weaving be present in the system during a reweave. An error will | |||
be issued if any are missing. | |||
[[INPATH]] | |||
==== The -inpath option. | |||
=== The -inpath option. | |||
The new `-inpath` option replaces the `-injars` option (which is still | |||
supported for backwards compatibility). It allows both directories and | |||
@@ -357,7 +357,7 @@ result of building one project to become binary input to the compilation | |||
of a second project. | |||
[[COMPLIANCE]] | |||
==== The default compliance mode of the compiler has changed from -1.3 to -1.4. | |||
=== The default compliance mode of the compiler has changed from -1.3 to -1.4. | |||
The default AspectJ compiler compliance level is now 1.4 (whereas in | |||
previous releases the default compliance level was 1.3). This has a | |||
@@ -432,7 +432,7 @@ actual type of the receiver. | |||
''''' | |||
[[AJDOC]] | |||
==== The ajdoc tool makes a comeback in the AspectJ 1.2 distribution. | |||
=== The ajdoc tool makes a comeback in the AspectJ 1.2 distribution. | |||
`ajdoc` (the AspectJ replacement for the `javadoc` tool) is once again | |||
included in the AspectJ distribution. The `ajdoc` tool produces regular | |||
@@ -460,7 +460,7 @@ image:images/ajdoc1.JPG[image] | |||
image:images/ajdoc2.JPG[image] | |||
[[LTW]] | |||
==== A sample script is supplied that supports load-time weaving from the command-line | |||
=== A sample script is supplied that supports load-time weaving from the command-line | |||
The AspectJ 1.2 distribution ships with sample scripts for Windows and | |||
Unix platforms that exploit AspectJ's binary weaving capabilities at | |||
@@ -541,7 +541,7 @@ welcome contributions from users to improve these scripts. | |||
''''' | |||
[[SOFTEX]] | |||
==== SoftException now supports getCause() | |||
=== SoftException now supports getCause() | |||
`org.aspectj.lang.SoftException` now supports the `getCause()` method, | |||
which returns the original exception wrapped by the `SoftException`. | |||
@@ -549,7 +549,7 @@ This means that exception chains will print correctly on 1.4 and later | |||
JREs. | |||
[[LTW2]] | |||
==== org.aspectj.weaver.tools package added | |||
=== org.aspectj.weaver.tools package added | |||
A new set of public APIs are exported by the | |||
link:api/index.html[`org.aspectj.weaver.tools`] package that can be used | |||
@@ -561,7 +561,7 @@ example of how to use these APIs, see the | |||
''''' | |||
[[allchanges]] | |||
=== All changes are listed in the bug database | |||
== All changes are listed in the bug database | |||
For a complete list of changes in the 1.2 release, search for | |||
`target 1.2` in the bug database: |
@@ -1,13 +1,13 @@ | |||
== AspectJ 5 | |||
= AspectJ 5 | |||
_© Copyright 2005 Contributors. All rights reserved._ | |||
AspectJ 5 introduces several important changes to the language and tools | |||
in order to support Java 5 and extend the capabilities of AspectJ in | |||
general. For language changes, see xref:../../adk15notebook/adk15notebook.adoc[AspectJ 5 Developer's Notebook]. For tools changes, see the | |||
link:devguide/index.html[AspectJ Development Environment Guide], | |||
especially the section on link:devguide/ltw.html[Load-time weaving]. The | |||
changes are summarized in the faq.html#q:aspectj5features[FAQ entry on | |||
general. For language changes, see xref:../adk15notebook/index.adoc[AspectJ 5 Developer's Notebook]. For tools changes, see the | |||
xref:../devguide/index.adoc[AspectJ Development Environment Guide], | |||
especially the section on xref:../devguide/ltw.adoc[Load-time weaving]. The | |||
changes are summarized in the xref:../faq/faq.adoc#AspectJ5[FAQ entry on | |||
AspectJ 5]. | |||
Some of the other documentation has not been updated for AspectJ 5. For | |||
@@ -16,4 +16,4 @@ https://eclipse.org/aspectj/doc/next/index.html, linked off | |||
https://eclipse.org/aspectj/docs.php[the AspectJ documentation home page]. | |||
For information on bug fixes in AspectJ 5 v1.5.0, see the | |||
link:changes.html[changes] document. | |||
xref:changes.adoc[changes] document. |
@@ -1,4 +1,4 @@ | |||
== AspectJ 5 v1.5.1 Readme | |||
= AspectJ 5 v1.5.1 Readme | |||
_© Copyright 2006 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 5 v1.5.2 Readme | |||
= AspectJ 5 v1.5.2 Readme | |||
_© Copyright 2006 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 5 v1.5.3 Readme | |||
= AspectJ 5 v1.5.3 Readme | |||
_© Copyright 2006 Contributors. All rights reserved._ | |||
@@ -9,7 +9,7 @@ bugzilla query]. | |||
Notable changes since the 1.5.2 release include: + | |||
=== Pipeline compilation - https://bugs.eclipse.org/bugs/show_bug.cgi?id=146781[146781] | |||
== Pipeline compilation - https://bugs.eclipse.org/bugs/show_bug.cgi?id=146781[146781] | |||
Until this release, the memory profile for AspectJ looked like this | |||
(time is along the X axis, memory usage is the Y axis) | |||
@@ -74,7 +74,7 @@ with memory. These savings will affect any code built from source: on | |||
the command line, in Ant, or in AJDT. It will not affect binary weaving | |||
- that is a future enhancement. | |||
=== Serviceability - https://bugs.eclipse.org/bugs/show_bug.cgi?id=150487[150487] | |||
== Serviceability - https://bugs.eclipse.org/bugs/show_bug.cgi?id=150487[150487] | |||
As AspectJ grows in popularity, we find that it is becoming more | |||
difficult for users to come up with the small testcases that recreate | |||
@@ -87,9 +87,9 @@ https://www.eclipse.org/aspectj/doc/released/pdguide/index.html[documentation] | |||
on how to configure these new features. Don't be surprised if you get | |||
asked for an AspectJ trace on a future bug report! | |||
=== LTW enhancements | |||
== LTW enhancements | |||
==== User and System Configuration Files - https://bugs.eclipse.org/bugs/show_bug.cgi?id=149289[149289] | |||
=== User and System Configuration Files - https://bugs.eclipse.org/bugs/show_bug.cgi?id=149289[149289] | |||
The `-outxml` option now generates a file named `META-INF/aop-ajc.xml`. | |||
This no longer clashes with a user defined `META-INF/aop.xml` | |||
@@ -97,11 +97,11 @@ configuration file. Both file names along with an OSGi-friendly | |||
`org/aspectj/aop.xml` (which can also be signed) are used by default to | |||
configure LTW. | |||
==== Weaving Concrete Aspects Defined in aop.xml - https://bugs.eclipse.org/bugs/show_bug.cgi?id=132080[132080] | |||
=== Weaving Concrete Aspects Defined in aop.xml - https://bugs.eclipse.org/bugs/show_bug.cgi?id=132080[132080] | |||
Concrete aspects defined using aop.xml are now exposed for weaving. | |||
=== Pertypewithin enhancement - https://bugs.eclipse.org/bugs/show_bug.cgi?id=123423[123423] | |||
== Pertypewithin enhancement - https://bugs.eclipse.org/bugs/show_bug.cgi?id=123423[123423] | |||
It is now possible to ask an instance of a ptw aspect which type it is | |||
'attached' to. The method: |
@@ -1,4 +1,4 @@ | |||
== AspectJ 5 v1.5.4 Readme | |||
= AspectJ 5 v1.5.4 Readme | |||
_© Copyright 2006 Contributors. All rights reserved._ | |||
@@ -1,8 +1,8 @@ | |||
== AspectJ 1.6.0 | |||
= AspectJ 1.6.0 | |||
_© Copyright 2008 Contributors. All rights reserved._ | |||
=== AspectJ v1.6.0 - 23 Apr 2008 | |||
== AspectJ v1.6.0 - 23 Apr 2008 | |||
For the complete list of every issue addressed since the last full | |||
release, see | |||
@@ -11,12 +11,12 @@ bugzilla link]. | |||
Some of the highlights of 1.6.0 are: | |||
==== Upgrade to a Java 1.6 compiler | |||
=== Upgrade to a Java 1.6 compiler | |||
AspectJ1.6.0 upgrades the internal Eclipse compiler level to version | |||
785_R33x - a Java 1.6 level compiler | |||
==== Better incremental compilation support in the IDE | |||
=== Better incremental compilation support in the IDE | |||
Changes under https://bugs.eclipse.org/bugs/show_bug.cgi?id=221427[bug | |||
221427] mean that the compiler is better able to maintain incremental | |||
@@ -28,7 +28,7 @@ findings can be seen in | |||
https://dev.eclipse.org/mhonarc/lists/aspectj-users/msg09002.html[this | |||
mailing list post]. | |||
==== Parameter annotation matching | |||
=== Parameter annotation matching | |||
Parameter matching is possible for constructors and methods. The use of | |||
parentheses around the parameter types in a method signature determine | |||
@@ -88,7 +88,7 @@ Join point 'method-execution(void C.goo(java.lang.String))' in Type 'C' (A.java: | |||
The first piece of advice matched both methods. The second only matched `goo()`. | |||
==== Annotation Value Matching | |||
=== Annotation Value Matching | |||
This allows static matching of the values of an annotation - if the | |||
matching is done statically at weave time, it is possible to avoid some | |||
@@ -155,13 +155,13 @@ Matching is currently allowed on all annotation value types *except* | |||
class and array. Also it is not currently supported for parameter | |||
annotation values. | |||
==== Changes since release candidate | |||
=== Changes since release candidate | |||
The only fix 1.6.0 final includes beyond the release candidate is a | |||
multi-threading problem in the weaver - | |||
https://bugs.eclipse.org/bugs/show_bug.cgi?id=227029[bug 227029]. | |||
==== Releases leading up to AspectJ 1.6.0 | |||
=== Releases leading up to AspectJ 1.6.0 | |||
AspectJ v1.6.0rc1- 16 Apr 2008 | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.1 | |||
= AspectJ 1.6.1 | |||
_© Copyright 2008 Contributors. All rights reserved._ | |||
@@ -21,14 +21,14 @@ implemented] | |||
''''' | |||
=== Refactored (https://bugs.eclipse.org/bugs/show_bug.cgi?id=231396[bug 231396]) | |||
== Refactored (https://bugs.eclipse.org/bugs/show_bug.cgi?id=231396[bug 231396]) | |||
The bugzilla entry goes into more specifics on what has changed, the end | |||
result is that aspectjweaver.jar has had around 275 classes removed | |||
(about 25%) and has slimmed down by 350k (about 20%). In terms of | |||
performance for different scenarios: | |||
==== Straight compilation | |||
=== Straight compilation | |||
The refactoring effort has been focused on the weaver component, hence | |||
there is limited impact on the performance of source compilation but | |||
@@ -45,7 +45,7 @@ join points) | |||
image:images/perfSourceCompile_161.jpg[image] | |||
==== Binary weaving | |||
=== Binary weaving | |||
Moving on from source compilation to pure binary weaving, the | |||
improvements are more obvious. Here we are using the complete JVM | |||
@@ -62,7 +62,7 @@ aspect (121000 join points) | |||
image:images/perfBinaryWeave_161.jpg[image] | |||
==== Loadtime weaving | |||
=== Loadtime weaving | |||
The loadtime weaving improvements are similar to those seen for binary | |||
weaving (naturally). Here we are using the JDK tools jar 'tools.jar' as | |||
@@ -93,7 +93,7 @@ So in terms of memory required, weaving the insane aspect into tools.jar | |||
created 1.4G of 'stuff' over the entire weaving process, compared to | |||
1.75G with 1.6.0. | |||
==== Loadtime weaving stress | |||
=== Loadtime weaving stress | |||
As well as addressing the memory usage of a single load time weaver, we | |||
have also looked at the use of load time weaving in a larger scale | |||
@@ -119,7 +119,7 @@ And now AspectJ 1.6.1: | |||
image:images/memLtwStress_161.jpg[image] | |||
=== Incremental compilation | |||
== Incremental compilation | |||
Following on from the work done to improve compilation under Eclipse in | |||
AspectJ 1.6.0 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=221427[Bug | |||
@@ -138,9 +138,9 @@ with known errors, and this means AspectJ will more frequently do | |||
incremental builds rather than falling back to full builds because there | |||
was a compilation error. | |||
=== Language changes | |||
== Language changes | |||
==== Optmized syntax for annotation value binding (https://bugs.eclipse.org/bugs/show_bug.cgi?id=234943[Bug234943]) | |||
=== Optmized syntax for annotation value binding (https://bugs.eclipse.org/bugs/show_bug.cgi?id=234943[Bug234943]) | |||
If only binding an annotation at a method-execution join point in order | |||
to access an *enum value* within it, there is a more optimal syntax that |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.10 | |||
= AspectJ 1.6.10 | |||
_© Copyright 2010 Contributors. All rights reserved._ | |||
@@ -7,13 +7,13 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.6.10 available 17-Nov-2010_ | |||
=== Changes | |||
== Changes | |||
1.6.10 is primilarily just bug fixes for AspectJ, mainly in the areas of | |||
ITDs and generic aspects. However, there are a couple of important | |||
changes that users ought to be aware of: | |||
==== AJDT Memory usage | |||
=== AJDT Memory usage | |||
Type demotion has been in use during loadtime weaving for a while now, | |||
this enables the load time weavers to discard state and recover it at a | |||
@@ -34,7 +34,7 @@ If I can get enough positive feedback about this option, it will be made | |||
the default. For a more detailed write up, check out the blog post: | |||
http://andrewclement.blogspot.com/2010/07/ajdt-memory-usage-reduction.html | |||
==== Runtime changes | |||
=== Runtime changes | |||
A big thank you to Abraham Nevado and his team who have been working on | |||
some issues to optimize loadtime weaving and the code generated by |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.11 | |||
= AspectJ 1.6.11 | |||
_© Copyright 2010-2011 Contributors. All rights reserved._ | |||
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.6.11 available 15-Mar-2011_ | |||
=== Notable Changes | |||
== Notable Changes | |||
==== RC1 - Our own XML parser | |||
=== RC1 - Our own XML parser | |||
Due to the way AspectJ loads one of the standard XML parsers (for | |||
processing aop.xml) it was possible to get into a deadlock situation. To | |||
@@ -21,7 +21,7 @@ org.aspectj.weaver.loadtime.configuration.lightxmlparser=true. | |||
''''' | |||
==== M2 - Multithreaded world access | |||
=== M2 - Multithreaded world access | |||
The weaver is backed by a representation of types called a world. | |||
Traditionally the worlds have supported single threads - and that is how | |||
@@ -32,7 +32,7 @@ same time. Under | |||
https://bugs.eclipse.org/bugs/show_bug.cgi?id=337855[bug337855] some | |||
changes have been made to better support this kind of configuration. | |||
==== M2 - various attribute deserialization issues | |||
=== M2 - various attribute deserialization issues | |||
In 1.6.9 we made some radical changes to the serialized form. It turns | |||
out some of the deserialization code wasn't handling these new forms | |||
@@ -40,7 +40,7 @@ quite right. This would manifest as an IllegalStateException or | |||
IndexOutOfBoundsException or similar, during attribute unpacking. These | |||
issues have now all been sorted out in 1.6.11.M2. | |||
==== M2 - further optimizations in model for AJDT | |||
=== M2 - further optimizations in model for AJDT | |||
More changes have been made for users trying out the | |||
-Xset:minimalModel=true option to try and reduce the memory used in | |||
@@ -52,7 +52,7 @@ over), but now it is insensitive to ordering and should always recover | |||
the same amount across builds of the same project. With a bit more | |||
positive feedback on this option, it will become the default under AJDT. | |||
==== M2 - spaces in path names can cause problems | |||
=== M2 - spaces in path names can cause problems | |||
AspectJ had problems if the paths it was being passed (e.g. aspectpath) | |||
included spaces. This is bug | |||
@@ -61,7 +61,7 @@ been fixed. | |||
''''' | |||
==== M1 - Annotation removal | |||
=== M1 - Annotation removal | |||
Traditionally AspectJ has taken an additive approach, where | |||
methods/fields/supertypes/annotations can only be added to types. Now, | |||
@@ -81,7 +81,7 @@ Notice the '-' in front of the annotation, meaning 'removal'. The whole | |||
construct means 'remove the @Anno annotation from the int field called i | |||
in type Foo'. It is not yet supported on the other forms of declare @. | |||
==== M1 - Intertype innertypes | |||
=== M1 - Intertype innertypes | |||
More work has gone into this feature. It was originally added in 1.6.9 | |||
but the inability to use it with binary weaving greatly reduced the |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.12 | |||
= AspectJ 1.6.12 | |||
_© Copyright 2010-2011 Contributors. All rights reserved._ | |||
@@ -12,9 +12,9 @@ _Release info:_ | |||
* _1.6.12.M2 available 18-Aug-2011_ | |||
* _1.6.12.M1 available 7-Jun-2011_ | |||
=== Notable Changes | |||
== Notable Changes | |||
==== RC1 - annotation value matching and != | |||
=== RC1 - annotation value matching and != | |||
Prior to this change it was only possible to specify an annotation match | |||
like this: + | |||
@@ -29,7 +29,7 @@ This can enable a group of annotated elements to be more easily | |||
identified. + | |||
+ | |||
==== RC1 - More flexible pointcut/code wiring in aop.xml | |||
=== RC1 - More flexible pointcut/code wiring in aop.xml | |||
Prior to this version the wiring was quite limited. In order to wire a | |||
pointcut to a piece of code the user needed to write an abstract aspect | |||
@@ -95,7 +95,7 @@ get started! | |||
''''' | |||
==== M2 - thisAspectInstance (https://bugs.eclipse.org/bugs/show_bug.cgi?id=239649[bug239649]) | |||
=== M2 - thisAspectInstance (https://bugs.eclipse.org/bugs/show_bug.cgi?id=239649[bug239649]) | |||
There is now a new well known name that you can use in the if clauses in | |||
your aspects. thisAspectInstance provides access to the aspect instance. | |||
@@ -147,13 +147,13 @@ going to run. *Note:* right now this only works for singleton aspects. | |||
If you have need of it with other instantiation models, please comment | |||
on https://bugs.eclipse.org/bugs/show_bug.cgi?id=239649 | |||
==== M2 - weaving groovy | |||
=== M2 - weaving groovy | |||
Although we have been successfully weaving groovy for a long time, it is | |||
becoming more popular and a few issues have been uncovered when using | |||
non-singleton aspects with groovy code. These have been fixed. | |||
==== M2 - AJDT memory | |||
=== M2 - AJDT memory | |||
The release notes for the last few versions of AspectJ have mentioned | |||
two options (minimalModel and typeDemotion) which can be switched on to | |||
@@ -167,7 +167,7 @@ actively turning them off by specifying | |||
-Xset:minimalModel=false,typeDemotion=false in the project properties | |||
for your AspectJ project. | |||
==== M2 - Java7 weaving support | |||
=== M2 - Java7 weaving support | |||
Some preliminary work has been done to support Java7. Java7 class files | |||
must contain the necessary extra verifier support attributes in order to | |||
@@ -181,7 +181,7 @@ supports Java7 language constructs - that will happen after Eclipse | |||
''''' | |||
==== M1 - synthetic is supported in pointcut modifiers https://bugs.eclipse.org/bugs/show_bug.cgi?id=327867[327867] | |||
=== M1 - synthetic is supported in pointcut modifiers https://bugs.eclipse.org/bugs/show_bug.cgi?id=327867[327867] | |||
It is now possible to specify synthetic in pointcuts: | |||
@@ -190,21 +190,21 @@ It is now possible to specify synthetic in pointcuts: | |||
pointcut p(): execution(!synthetic * *(..)); | |||
.... | |||
==== M1 - respect protection domain when generating types during weaving https://bugs.eclipse.org/bugs/show_bug.cgi?id=328099[328099] | |||
=== M1 - respect protection domain when generating types during weaving https://bugs.eclipse.org/bugs/show_bug.cgi?id=328099[328099] | |||
This enables us to weave signed jars correctly. AspectJ sometimes | |||
generates closure classes during weaving and these must be defined with | |||
the same protection domain as the jar that gave rise to them. In | |||
1.6.12.M1 this should now work correctly. | |||
==== M1 - Suppressions inline with the JDT compiler https://bugs.eclipse.org/bugs/show_bug.cgi?id=335810[335810] | |||
=== M1 - Suppressions inline with the JDT compiler https://bugs.eclipse.org/bugs/show_bug.cgi?id=335810[335810] | |||
Starting with Eclipse 3.6, the Eclipse compiler no longer suppresses raw | |||
type warnings with @SuppressWarnings("unchecked"). You need to use | |||
@SuppressWarnings("rawtypes") for that. AspectJ has now been updated | |||
with this rule too. | |||
==== M1 - Optimized annotation value binding for ints https://bugs.eclipse.org/bugs/show_bug.cgi?id=347684[347684] | |||
=== M1 - Optimized annotation value binding for ints https://bugs.eclipse.org/bugs/show_bug.cgi?id=347684[347684] | |||
The optimized annotation value binding now supports ints - this is for | |||
use when you want to match upon the existence of an annotation but you |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.2 | |||
= AspectJ 1.6.2 | |||
_© Copyright 2008 Contributors. All rights reserved._ | |||
@@ -31,7 +31,7 @@ resolved] | |||
''''' | |||
=== Incremental compilation (https://bugs.eclipse.org/bugs/show_bug.cgi?id=247742[bug 247742], https://bugs.eclipse.org/bugs/show_bug.cgi?id=245566[bug 245566], https://bugs.eclipse.org/bugs/show_bug.cgi?id=243376[bug 243376]) | |||
== Incremental compilation (https://bugs.eclipse.org/bugs/show_bug.cgi?id=247742[bug 247742], https://bugs.eclipse.org/bugs/show_bug.cgi?id=245566[bug 245566], https://bugs.eclipse.org/bugs/show_bug.cgi?id=243376[bug 243376]) | |||
Two main changes in this area. | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.3 | |||
= AspectJ 1.6.3 | |||
_© Copyright 2008 Contributors. All rights reserved._ | |||
@@ -10,7 +10,7 @@ _© Copyright 2008 Contributors. All rights reserved._ | |||
''''' | |||
[[split]] | |||
=== Split matching/weaving | |||
== Split matching/weaving | |||
The main goal of AspectJ 1.6.3 was to make the line between matching and | |||
weaving more explicit and introduce the notion of a matcher artifact. | |||
@@ -43,7 +43,7 @@ and reflection based - both of which require compilation). | |||
''''' | |||
[[bugsfixed]] | |||
=== Bugs fixed | |||
== Bugs fixed | |||
The complete list of issues resolved for AspectJ 1.6.3 (more than 50) | |||
can be found with this bugzilla query: | |||
@@ -57,7 +57,7 @@ issues. | |||
''''' | |||
[[notable]] | |||
=== Notable bug fixes | |||
== Notable bug fixes | |||
* More improvements to the way AspectJ/AJDT communicate (251277, 249216, | |||
258325) | |||
@@ -72,7 +72,7 @@ type (256669) | |||
''''' | |||
[[whatsnext]] | |||
=== What's next? | |||
== What's next? | |||
The JDT World should be completed in the 1.6.4 timeframe and that will | |||
surface as benefits in AJDT, possibly leading to better LTW tooling. |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.4 | |||
= AspectJ 1.6.4 | |||
_© Copyright 2009 Contributors. All rights reserved._ | |||
@@ -10,7 +10,7 @@ _© Copyright 2009 Contributors. All rights reserved._ | |||
''''' | |||
[[compilation]] | |||
=== Compilation times | |||
== Compilation times | |||
In AspectJ 1.6.4 the goal was to improve the IDE experience, through a | |||
combination of improved compilation speed (both full builds and | |||
@@ -107,7 +107,7 @@ AspectJ projects depend upon Java projects and where aspectpath is used. | |||
AJDT 1.6.5 dev builds also include some changes that really speed up | |||
builds. | |||
=== Better editor feedback | |||
== Better editor feedback | |||
Under https://bugs.eclipse.org/bugs/show_bug.cgi?id=246393[bug 246393] | |||
the problem has been addressed where sometimes spurious errors would | |||
@@ -118,7 +118,7 @@ http://andrewclement.blogspot.com/2009/02/aspectj-fixing-reverse-cascade-errors. | |||
''''' | |||
[[language]] | |||
=== Language Enhancements | |||
== Language Enhancements | |||
*Optimizing support for maintaining per join point state* | |||
@@ -169,7 +169,7 @@ advised type. | |||
See related https://bugs.eclipse.org/bugs/show_bug.cgi?id=89009[bug | |||
89009] for the full discussion | |||
=== @DeclareMixin | |||
== @DeclareMixin | |||
The annotation style declare parents support (@DeclareParents) has been | |||
(rightly) criticized because it really does not offer an equivalent to | |||
@@ -208,7 +208,7 @@ deprecated. | |||
''''' | |||
[[bugsfixed]] | |||
=== Bugs fixed | |||
== Bugs fixed | |||
The complete list of issues resolved for AspectJ 1.6.4 (more than 70) | |||
can be found with this bugzilla query: | |||
@@ -219,7 +219,7 @@ resolved] | |||
''''' | |||
[[whatsnext]] | |||
=== What's next? | |||
== What's next? | |||
*More incremental build enhancements* | |||
@@ -1,9 +1,9 @@ | |||
== AspectJ 1.6.5 | |||
= AspectJ 1.6.5 | |||
_© Copyright 2009 Contributors. All rights reserved._ | |||
[[bugsfixed]] | |||
=== Bugs fixed | |||
== Bugs fixed | |||
The complete list of issues resolved for AspectJ 1.6.5 can be found with | |||
this bugzilla query: |
@@ -1,9 +1,9 @@ | |||
== AspectJ 1.6.6 | |||
= AspectJ 1.6.6 | |||
_© Copyright 2009 Contributors. All rights reserved._ | |||
[[bugsfixed]] | |||
=== Bugs fixed | |||
== Bugs fixed | |||
The complete list of issues resolved for AspectJ 1.6.6 can be found with | |||
this bugzilla query: | |||
@@ -13,7 +13,7 @@ resolved] | |||
''''' | |||
=== Changes | |||
== Changes | |||
*Java5* | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.7 | |||
= AspectJ 1.6.7 | |||
_© Copyright 2009 Contributors. All rights reserved._ | |||
@@ -6,7 +6,7 @@ AspectJ 1.6.7 includes some radical internal changes. These improvements | |||
enable faster compilation, faster binary weaving, faster load time | |||
weaving and in some situations faster generated code. | |||
=== Pointcut timers | |||
== Pointcut timers | |||
Until 1.6.7 there has not really been a way to determine if it is just | |||
one of your pointcuts that is hurting your weaving performance. In 1.6.7 | |||
@@ -41,7 +41,7 @@ AJDT. Armed with this information you can optimize your pointcuts or | |||
post on the mailing list asking for help. The timers can even be turned | |||
on for load time weaving. | |||
=== Faster matching | |||
== Faster matching | |||
The changes to enable pointcut profiling enabled some targeted work to | |||
be done on the matching algorithms. These have remained unchanged for a | |||
@@ -61,7 +61,7 @@ as early as possible once they can determine something is a match or is | |||
definetly not a match. This reduces memory usage, speeds up weaving and | |||
reduces the occurrences of those annoying 'cantFindType' messages. | |||
=== aop.xml processing | |||
== aop.xml processing | |||
The processing of include/exclude entries in aop.xml has been rewritten. | |||
It now optimizes for many more common patterns. If a pattern is | |||
@@ -69,7 +69,7 @@ optimized then there is no need to ask the weaver to do an expensive | |||
include/exclude match. More details | |||
http://andrewclement.blogspot.com/2009/12/aspectj-167-and-faster-load-time.html[here]. | |||
=== Less need to tweak options for load time weaving | |||
== Less need to tweak options for load time weaving | |||
A number of options were previously configurable for load time weaving | |||
that were considered experimental. These options have now been tested | |||
@@ -82,7 +82,7 @@ by default in 1.6.7. If you have been using either of these: | |||
then please delete them from your weaver options section, the weaver | |||
will now do the right thing out of the box. | |||
=== Benchmarking memory and performance | |||
== Benchmarking memory and performance | |||
All those changes above, and some additional tweaks, mean we are now | |||
using less memory than ever before and getting things done more quickly. | |||
@@ -98,7 +98,7 @@ image:images/167speed.png[image] | |||
image:images/167Memory.png[image] | |||
=== Annotation binding | |||
== Annotation binding | |||
All those changes affect compilation/weaving but what about the code | |||
that actually runs? One user, Oliver Hoff, raised a query on the | |||
@@ -171,7 +171,7 @@ value. | |||
''''' | |||
[[bugsfixed]] | |||
==== Bugs fixed | |||
=== Bugs fixed | |||
The complete list of issues resolved for AspectJ 1.6.7 can be found with | |||
this bugzilla query: |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.6.8 | |||
= AspectJ 1.6.8 | |||
_© Copyright 2009 Contributors. All rights reserved._ | |||
@@ -9,7 +9,7 @@ Unfortunately not enough testing was done on 1.6.7 and two nasty issues | |||
were found that really needed addressing. Fixes for these issues are all | |||
that is new in 1.6.8. | |||
=== Incorrect treatment of some aop.xml include/exclude patterns | |||
== Incorrect treatment of some aop.xml include/exclude patterns | |||
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298786[Bug 298786] | |||
@@ -39,7 +39,7 @@ right now as it includes multiple wildcards). | |||
With that configuration any types that the include="*" would have | |||
accepted are not accepted. | |||
=== Stack overflow problem in ReferenceType.isAssignableFrom() | |||
== Stack overflow problem in ReferenceType.isAssignableFrom() | |||
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298908[Bug 298908] | |||
@@ -1,13 +1,13 @@ | |||
== AspectJ 1.6.9 | |||
= AspectJ 1.6.9 | |||
_© Copyright 2010 Contributors. All rights reserved._ | |||
The full list of resolved issues in 1.6.9 is available | |||
https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOLVED;bug_status=VERIFIED;bug_status=CLOSED;product=AspectJ;target_milestone=1.6.9;target_milestone=1.6.9M1;target_milestone=1.6.9M2;target_milestone=1.6.9RC1[here] | |||
=== Features | |||
== Features | |||
==== declare annotation supports compound signature patterns: https://bugs.eclipse.org/bugs/show_bug.cgi?id=287613[287613] | |||
=== declare annotation supports compound signature patterns: https://bugs.eclipse.org/bugs/show_bug.cgi?id=287613[287613] | |||
Until now it wasn't possible to express a compound pattern in any of the | |||
declare annotation constructs that take a member signature. For example, | |||
@@ -28,7 +28,7 @@ Now AspectJ allows compound patterns for declare | |||
declare @method: (* is*()) || (* get*()): @FooBar; | |||
.... | |||
==== Intertype declaration of member types | |||
=== Intertype declaration of member types | |||
It is now possible to ITD member types. The syntax is as would be | |||
expected. This example introduces a new member type called Inner into | |||
@@ -53,7 +53,7 @@ aspect Magic { | |||
Only static member types are supported. | |||
==== 'Optional' aspects: https://bugs.eclipse.org/bugs/show_bug.cgi?id=310506[310506] | |||
=== 'Optional' aspects: https://bugs.eclipse.org/bugs/show_bug.cgi?id=310506[310506] | |||
It is not uncommon to ship a library aspect separately to a jar upon | |||
which it depends. In the case of Spring there is an aspect library | |||
@@ -79,7 +79,7 @@ Here is an example, 'AspectA' will switch itself off if the type | |||
<aspect name="AspectA" requires="a.b.c.Anno"/> | |||
.... | |||
==== Reduction in class file sizes: https://bugs.eclipse.org/bugs/show_bug.cgi?id=312839[312839] | |||
=== Reduction in class file sizes: https://bugs.eclipse.org/bugs/show_bug.cgi?id=312839[312839] | |||
More details here: | |||
http://andrewclement.blogspot.com/2010/05/aspectj-size-is-important.html | |||
@@ -88,7 +88,7 @@ aspects. As an example, a compiled Roo petclinic sample (which uses lots | |||
of aspects and ITDs) is down from 1Meg (AspectJ 1.6.9m2) to 630k | |||
(AspectJ 1.6.9rc1). | |||
==== Transparent weaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=309743[309743] | |||
=== Transparent weaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=309743[309743] | |||
In a further step towards transparent weaving, support for the AjType | |||
reflection system is now being made optional. This means if intending to | |||
@@ -101,7 +101,7 @@ standard reflection than are using AjTypeSystem. The related bugzilla | |||
discussing this issue is | |||
https://bugs.eclipse.org/bugs/show_bug.cgi?id=309743[309743]. | |||
==== Overweaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=293450[293450] | |||
=== Overweaving: https://bugs.eclipse.org/bugs/show_bug.cgi?id=293450[293450] | |||
Preliminary support for overweaving was added in AspectJ 1.6.7, but now | |||
in AspectJ 1.6.9m2 it is much more reliable. Basically it is an | |||
@@ -116,7 +116,7 @@ article]. A weaver is switched into overweaving mode by the option | |||
in the weaver options section of aop.xml. There is still more work to be | |||
done on this feature - any feedback is welcome. | |||
==== AOP Scoping: https://bugs.eclipse.org/bugs/show_bug.cgi?id=124460[124460] | |||
=== AOP Scoping: https://bugs.eclipse.org/bugs/show_bug.cgi?id=124460[124460] | |||
Another feature that had preliminary support a while ago is aspect | |||
scoping in aop.xml. This has also been improved in AspectJ1.6.9m2. For | |||
@@ -150,7 +150,7 @@ com..* should be woven and the aspects to be used are X and Y. The new | |||
'scope' setting on aspect Y's definition allows finer control, and | |||
specifies that Y should in fact only be applied to com.foo..* types. | |||
==== Message inserts for declare warning/error messages | |||
=== Message inserts for declare warning/error messages | |||
It is now possible to use joinpoint context in the messages attached to | |||
declare warning and declare error constructs. Some examples: | |||
@@ -173,7 +173,7 @@ The syntax is to enclose the relevant key within curly brackets within | |||
the message. Please raise an enhancement request if you need other keys | |||
- the set supported so far are all those shown in the example above. | |||
==== declare warning/error for type patterns | |||
=== declare warning/error for type patterns | |||
It is now possible to use a type pattern with declare warning and | |||
declare error. For example: | |||
@@ -183,7 +183,7 @@ declare error. For example: | |||
declare warning: I+ && !hasfield(int i): "Implementations of I are expected to have a int field called i"; | |||
.... | |||
==== Type category type patterns | |||
=== Type category type patterns | |||
This is the ability to narrow the types of interest so that interfaces | |||
can be ignored, or inner types, or classes or aspects. There is now a | |||
@@ -218,7 +218,7 @@ surrounding Boo will match it). Bar.foo() will not match | |||
!within(is(InnerType)) because Bar will match the pattern and then the | |||
result of that match will be negated. | |||
==== Intertype fields preserve visibility and name | |||
=== Intertype fields preserve visibility and name | |||
Some users always expect this: | |||
@@ -270,7 +270,7 @@ The name 'someField' is preserved. The visibility is also preserved but | |||
because of that we also need to generate some accessors to get at the | |||
field. | |||
==== AspectJ snapshots in a maven repo | |||
=== AspectJ snapshots in a maven repo | |||
To ease how AspectJ development builds can be consumed, they are now | |||
placed into a maven repo. When a new version of AspectJ is put into AJDT |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.7.0 | |||
= AspectJ 1.7.0 | |||
_© Copyright 2011 Contributors. All rights reserved._ | |||
@@ -11,9 +11,9 @@ _Release info:_ | |||
* _1.7.0.RC1 available 25-May-2012_ | |||
* _1.7.0.M1 available 16-Dec-2011_ | |||
=== Notable Changes | |||
== Notable Changes | |||
==== Java 7 bytecode weaving | |||
=== Java 7 bytecode weaving | |||
The first milestone of 1.7.0 upgraded the compiler but this still left | |||
the weaver with some issues if it had to weave into bytecode containing | |||
@@ -26,7 +26,7 @@ point yet so you cannot write a pointcut to match on it. If you use | |||
execution() pointcuts as opposed to call() then you will still be able | |||
to advise what the invokedynamic actually calls. | |||
==== Bytecode caching for loadtime weaving | |||
=== Bytecode caching for loadtime weaving | |||
Under https://bugs.eclipse.org/bugs/show_bug.cgi?id=367673[bug 367673] | |||
we have had a contribution (thanks John Kew!) that enables a bytecode | |||
@@ -42,7 +42,7 @@ To activate it, use the following system properties: | |||
-Daj.weaving.cache.dir=/tmp/aspectj-cache/ | |||
.... | |||
==== Upgrade to Java 7 | |||
=== Upgrade to Java 7 | |||
For AspectJ 1.7.0, AspectJ moved from Eclipse JDT Core 0.785_R33x | |||
(Eclipse 3.3) to Eclipse JDT Core 0.B79_R37x (Eclipse 3.7). This is a |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.7.1 | |||
= AspectJ 1.7.1 | |||
_© Copyright 2011 Contributors. All rights reserved._ | |||
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.7.1 available 6-Sep-2012_ | |||
=== Changes | |||
== Changes | |||
https://bugs.eclipse.org/bugs/show_bug.cgi?id=388971[388971] Double | |||
Synthetic attributes on some around advice members + |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.7.2 | |||
= AspectJ 1.7.2 | |||
_© Copyright 2011 Contributors. All rights reserved._ | |||
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.7.2 available 13-Feb-2013_ | |||
=== Fixes: | |||
== Fixes: | |||
* Incorrect signature attributes generated into some class files for | |||
complex generics declarations. |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.7.3 | |||
= AspectJ 1.7.3 | |||
_© Copyright 2011 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.7.4 | |||
= AspectJ 1.7.4 | |||
_© Copyright 2013 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.0 | |||
= AspectJ 1.8.0 | |||
_© Copyright 2014 Contributors. All rights reserved._ | |||
@@ -11,9 +11,9 @@ _Release info:_ | |||
* _1.8.0.RC1 available 18-Mar-2014_ | |||
* _1.8.0.M1 available 29-Jul-2013_ | |||
=== Notable changes | |||
== Notable changes | |||
==== Java 8 compilation | |||
=== Java 8 compilation | |||
AspectJ has been updated to the latest available Eclipse Java compiler | |||
version that compiles Java8 code (the version available as a feature |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.1 | |||
= AspectJ 1.8.1 | |||
_© Copyright 2014 Contributors. All rights reserved._ | |||
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.1 available 20-Jun-2014_ | |||
=== Notable changes | |||
== Notable changes | |||
==== Java 8 update | |||
=== Java 8 update | |||
As Eclipse itself nears the 4.4 release, AspectJ has been updated to the | |||
latest Eclipse JDT Core that will be included in it, picking up numerous |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.10 | |||
= AspectJ 1.8.10 | |||
_© Copyright 2016 Contributors. All rights reserved._ | |||
@@ -7,21 +7,21 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.10 available 9-Dec-2016_ | |||
=== Notable changes | |||
== Notable changes | |||
==== JDT Upgrade | |||
=== JDT Upgrade | |||
The JDT compiler inside AspectJ has been upgraded to the Eclipse Neon.2 | |||
level (JDT commit #75dbfad0). | |||
==== Java8 | |||
=== Java8 | |||
The Eclipse JDT compiler embedded inside AspectJ now requires Java 8, so | |||
that is the minimum required level to compile sources with AspectJ. | |||
However, if only doing weaving and no compilation then it is possible to | |||
use Java 7. | |||
==== Annotation style around advice and proceed (https://bugs.eclipse.org/bugs/show_bug.cgi?id=500035[Bug 500035]) | |||
=== Annotation style around advice and proceed (https://bugs.eclipse.org/bugs/show_bug.cgi?id=500035[Bug 500035]) | |||
A long standing issue that has been lurking in the handling of arguments | |||
passed to proceed for annotation style aspects has been fixed. If, at a |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.11 | |||
= AspectJ 1.8.11 | |||
_© Copyright 2017 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.2 | |||
= AspectJ 1.8.2 | |||
_© Copyright 2014 Contributors. All rights reserved._ | |||
@@ -7,31 +7,31 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.2 available 14-Aug-2014_ | |||
=== Notable changes | |||
== Notable changes | |||
Although only a few bugs have been fixed here, they are quite important | |||
ones: | |||
==== Update to more recent Eclipse Compiler | |||
=== Update to more recent Eclipse Compiler | |||
AspectJ is now based on a more up to date Eclipse compiler level (git | |||
hash 2b07958) so includes all the latest fixes | |||
==== Correct handling of RuntimeInvisibleTypeAnnotations (type annotations without runtime visibility) | |||
=== Correct handling of RuntimeInvisibleTypeAnnotations (type annotations without runtime visibility) | |||
For anyone weaving code containing these kind of type annotations, this | |||
is an important fix. Although AspectJ does not currently support | |||
pointcuts matching on these kinds of annotation it was crashing when | |||
they were encountered. That is now fixed. | |||
==== Annotation processing | |||
=== Annotation processing | |||
A very long standing issue, the AspectJ compiler now supports annotation | |||
processors thanks to some work by Sergey Stupin. | |||
Here is a short example, a very basic annotation and application: | |||
===== Marker.java | |||
==== Marker.java | |||
[source, java] | |||
.... | |||
@@ -42,7 +42,7 @@ import java.lang.annotation.RetentionPolicy; | |||
public @interface Marker { } | |||
.... | |||
===== Code.java | |||
==== Code.java | |||
[source, java] | |||
.... | |||
@@ -72,7 +72,7 @@ in the source marked with the annotation Marker and for each one | |||
generate an aspect tailored to advising that method (this *is* a | |||
contrived demo!) | |||
===== DemoProcessor.java | |||
==== DemoProcessor.java | |||
[source, java] | |||
.... |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.3 | |||
= AspectJ 1.8.3 | |||
_© Copyright 2014 Contributors. All rights reserved._ | |||
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.3 available 22-Oct-2014_ | |||
=== Notable changes | |||
== Notable changes | |||
==== Conditional aspect activation with @RequiredTypes - https://bugs.eclipse.org/bugs/show_bug.cgi?id=436653[Issue 436653] | |||
=== Conditional aspect activation with @RequiredTypes - https://bugs.eclipse.org/bugs/show_bug.cgi?id=436653[Issue 436653] | |||
AspectJ is sometimes used to create aspect libraries. These libraries | |||
contain a number of aspects often covering a variety of domains. The | |||
@@ -49,7 +49,7 @@ passed on the aspectpath for compile time weaving, if the type | |||
turned off and the pointcut will have no effect. There will be no | |||
attempt made to match it and so no unhelpful "can't find type" messages. | |||
==== cflow and the pre-initialization joinpoint changes due to Java 7 verifier modifications - https://bugs.eclipse.org/bugs/show_bug.cgi?id=443477[Issue 443477] | |||
=== cflow and the pre-initialization joinpoint changes due to Java 7 verifier modifications - https://bugs.eclipse.org/bugs/show_bug.cgi?id=443477[Issue 443477] | |||
There has been a change in the Java7 verifier in a recent patch release | |||
of Java7 (update 67) that causes a verify error for usage of a | |||
@@ -89,7 +89,7 @@ seems little use in applying it to pre-initialization - that is your cue | |||
to raise an AspectJ bug with a realistic use case inside that proves | |||
this an invalid assumption :) | |||
==== around advice and lambdas - https://bugs.eclipse.org/bugs/show_bug.cgi?id=445395[Issue 445395] | |||
=== around advice and lambdas - https://bugs.eclipse.org/bugs/show_bug.cgi?id=445395[Issue 445395] | |||
For optimal performance, where possible, AspectJ tries to inline around | |||
advice when it applies at a joinpoint. There are few characteristics of |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.4 | |||
= AspectJ 1.8.4 | |||
_© Copyright 2014 Contributors. All rights reserved._ | |||
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.4 available 6-Nov-2014_ | |||
=== Notable changes | |||
== Notable changes | |||
==== Support for is(FinalType) | |||
=== Support for is(FinalType) | |||
AspectJ has had type category type patterns since version 1.6.9, see the | |||
https://www.eclipse.org/aspectj/doc/released/README-1.6.9.html[README]. | |||
@@ -19,7 +19,7 @@ is(InnerType)) means not within innertypes. In 1.8.4 it is now possible | |||
to recognize (for inclusion or exclusion) final types with | |||
is(FinalType). | |||
==== thisAspectInstance correctly handled with -1.8 | |||
=== thisAspectInstance correctly handled with -1.8 | |||
This is the key fix in this release. Some products based on AspectJ were | |||
using the thisAspectInstance feature (see |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.5 | |||
= AspectJ 1.8.5 | |||
_© Copyright 2015 Contributors. All rights reserved._ | |||
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.5 available 28-Jan-2015_ | |||
=== Notable changes | |||
== Notable changes | |||
The most important fixes in 1.8.5 are JDT compiler fixes that it | |||
includes |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.6 | |||
= AspectJ 1.8.6 | |||
_© Copyright 2015 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.7 | |||
= AspectJ 1.8.7 | |||
_© Copyright 2015 Contributors. All rights reserved._ | |||
@@ -7,14 +7,14 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.7 available 9-Sep-2015_ | |||
=== Notable changes | |||
== Notable changes | |||
==== ajdoc | |||
=== ajdoc | |||
The ajdoc tool has been fixed! It is now working again if run on a 1.7 | |||
JDK. | |||
==== Dynamic weaver attachment | |||
=== Dynamic weaver attachment | |||
The AspectJ loadtime weaving agent can now be dynamically attached to a | |||
JVM after it has started (you don't need to use -javaagent). This offers |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.8 | |||
= AspectJ 1.8.8 | |||
_© Copyright 2016 Contributors. All rights reserved._ | |||
@@ -7,9 +7,9 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.8 available 7-Jan-2016_ | |||
=== Notable changes | |||
== Notable changes | |||
==== Around advice on default methods | |||
=== Around advice on default methods | |||
In previous releases attempting to apply around advice to default | |||
methods would create methods with rogue modifiers in the interface |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.8.9 | |||
= AspectJ 1.8.9 | |||
_© Copyright 2016 Contributors. All rights reserved._ | |||
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;bug_status=RESOL | |||
_Release info: 1.8.9 available 14-Mar-2016_ | |||
=== Notable changes | |||
== Notable changes | |||
The JDT compiler inside AspectJ has been upgraded to the Eclipse Mars.2 | |||
level (commit #a7bba8b1). |
@@ -1,4 +1,8 @@ | |||
== AspectJ 1.9.0 | |||
= AspectJ 1.9.0 | |||
:doctype: book | |||
:leveloffset: +1 | |||
= AspectJ 1.9.0 | |||
_© Copyright 2018 Contributors. All rights reserved._ | |||
@@ -7,7 +11,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIE | |||
_Release info: 1.9.0 available 2-Apr-2018_ | |||
=== Improved runtime interface | |||
== Improved runtime interface | |||
New factory methods have been added to the AspectJ runtime. This is an | |||
attempt to more optimally create `thisJoinPoint` and | |||
@@ -48,7 +52,7 @@ export ASPECTJ_OPTS="-Xajruntimetarget:1.9" | |||
And it should get picked up by AspectJ when it runs. | |||
== AspectJ 1.9.0.RC4 | |||
= AspectJ 1.9.0.RC4 | |||
_Release info: 1.9.0.RC4 available 21-Feb-2018_ | |||
@@ -75,14 +79,14 @@ For example, here is an `iajc` usage with `compilerArg` that is passing | |||
</iajc> | |||
.... | |||
== AspectJ 1.9.0.RC3 | |||
= AspectJ 1.9.0.RC3 | |||
_Release info: 1.9.0.RC3 available 5-Feb-2018_ | |||
Primary changes in RC3 are to upgrade JDT and pickup all the fixes for | |||
Java9 that have gone into it over the last few months. | |||
== AspectJ 1.9.0.RC2 | |||
= AspectJ 1.9.0.RC2 | |||
_Release info: 1.9.0.RC2 available 9-Nov-2017_ | |||
@@ -91,7 +95,7 @@ version handling has been somewhat overhauled so AspectJ 9 will behave | |||
better on Java 10 and future JDKs. This should put AspectJ in a better | |||
place if new JDK versions are going to arrive thick and fast. | |||
== AspectJ 1.9.0.RC1 | |||
= AspectJ 1.9.0.RC1 | |||
_Release info: 1.9.0.RC1 available 20-Oct-2017_ | |||
@@ -99,7 +103,7 @@ This is the first release candidate of AspectJ 1.9.0 - the version of | |||
AspectJ to be based on Java9. It includes a recent version of the | |||
Eclipse Java9 compiler (from jdt core, commit #062ac5d7a6bf9). | |||
=== Automatic Modules | |||
== Automatic Modules | |||
AspectJ can now be used with the new module system available in Java9. | |||
The key jars in AspectJ have been given automatic module names. The | |||
@@ -133,7 +137,7 @@ contains org.aspectj.asm.internal | |||
... | |||
.... | |||
=== Building woven modules | |||
== Building woven modules | |||
AspectJ understands `module-info.java` source files and building modules | |||
that include aspects. Here is an example: | |||
@@ -200,7 +204,7 @@ Demo running | |||
That's it! | |||
=== Binary weaving with modules | |||
== Binary weaving with modules | |||
A module is really just a jar with a _module-info_ descriptor. As such, you | |||
can simply pass a module on the _inpath_ and binary-weave it with other | |||
@@ -242,7 +246,7 @@ AnotherAzpect running | |||
Demo running | |||
.... | |||
=== Faster Spring AOP | |||
== Faster Spring AOP | |||
Dave Syer recently created a https://github.com/dsyer/spring-boot-aspectj[series of benchmarks] for checking the speed | |||
of Spring-AspectJ. | |||
@@ -319,7 +323,7 @@ StartupBenchmark.spring a20_100 avgt 10 3.093 ~ 0.098 s/op | |||
Look at the a20_100 case - instead of impacting start time by 9 seconds, | |||
it impacts it by 1 second. | |||
=== More to come... | |||
== More to come... | |||
* Eclipse JDT Java 9 support is still being actively worked on and lots | |||
of fixes will be coming through over the next few months and included in |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.9.1 | |||
= AspectJ 1.9.1 | |||
_© Copyright 2018 Contributors. All rights reserved._ | |||
@@ -7,7 +7,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIE | |||
_Release info: 1.9.1 available 20-Apr-2018_ | |||
=== Java 10 support | |||
== Java 10 support | |||
AspectJ has updated to a recent JDT compiler version (commit | |||
#abe06abe4ce1 - 9-Apr-2018). With this update it now supports Java10. |
@@ -1,8 +1,4 @@ | |||
== AspectJ 1.9.19 | |||
_© Copyright 2022 Contributors. All rights reserved._ | |||
== AspectJ 1.9.19 | |||
= AspectJ 1.9.19 | |||
_© Copyright 2022 Contributors. All rights reserved._ | |||
@@ -15,7 +11,7 @@ here: | |||
* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.19[GitHub 1.9.19] | |||
* https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.19[Bugzilla 1.9.19] | |||
=== New features | |||
== New features | |||
AspectJ 1.9.19 supports https://openjdk.java.net/projects/jdk/19/[Java 19] and its final, preview and incubator | |||
features, such as: | |||
@@ -30,13 +26,13 @@ open issues concerning Java 19 preview feature support, see the list in | |||
https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940[this comment]. AJC therefore inherits the same | |||
problems for the specific cases described in the linked issues. | |||
=== Improvements | |||
== Improvements | |||
* Improve condy (constant dynamic) support. Together with some custom compilation or weaving options, this helps to | |||
avoid a problem when using JaCoCo together with AspectJ, see | |||
https://github.com/eclipse/org.aspectj/issues/170#issuecomment-1214163297[this comment in #170] for more details. | |||
=== Code examples | |||
== Code examples | |||
You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were | |||
first supported (possibly as JVM preview features): | |||
@@ -50,7 +46,7 @@ first supported (possibly as JVM preview features): | |||
concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently like | |||
any other Java API. | |||
=== Other changes and bug fixes | |||
== Other changes and bug fixes | |||
* Fix (or rather work around) an old bug occurring when compiling or weaving code using ITD to declare annotations with | |||
`SOURCE` retention on types, methods, constructors or fields. While declaring such annotations does not make sense to | |||
@@ -62,9 +58,9 @@ first supported (possibly as JVM preview features): | |||
* Remove legacy AspectJ Browser code and documentation. | |||
* Thanks to Andrey Turbanov for several clean code contributions. | |||
=== AspectJ usage hints | |||
== AspectJ usage hints | |||
==== AspectJ compiler build system requirements | |||
=== AspectJ compiler build system requirements | |||
Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The | |||
minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT | |||
@@ -73,7 +69,7 @@ plain Java code or using plain Java ITD constructs which do not require the Aspe | |||
compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time | |||
weaver `aspectjweaver` still only require JRE 8+. | |||
==== Use LTW on Java 16+ | |||
=== Use LTW on Java 16+ | |||
Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with | |||
https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set | |||
@@ -81,7 +77,7 @@ the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enab | |||
fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes | |||
in different classloaders. | |||
==== Compile with Java preview features | |||
=== Compile with Java preview features | |||
For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with | |||
`java --enable-preview` on that JDK. |
@@ -1,11 +1,11 @@ | |||
== AspectJ 1.9.2 | |||
= AspectJ 1.9.2 | |||
_© Copyright 2018 Contributors. All rights reserved._ | |||
The full list of resolved issues in 1.9.2 is available | |||
https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.2[here] | |||
=== Java 11 support | |||
== Java 11 support | |||
AspectJ now supports Java11. It has been updated to a more recent JDT | |||
compiler that supports Java 11 (JDTCore #6373b82afa49b). |
@@ -1,4 +1,9 @@ | |||
== AspectJ 1.9.20.1 | |||
= AspectJ 1.9.20 | |||
:doctype: book | |||
:leveloffset: +1 | |||
= AspectJ 1.9.20.1 | |||
_© Copyright 2023 Contributors. All rights reserved._ | |||
@@ -16,7 +21,7 @@ This is a bugfix release for 1.9.20, fixing two problems: | |||
The list of issues addressed for 1.9.20.1 can be found | |||
https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[here]. | |||
== AspectJ 1.9.20 | |||
= AspectJ 1.9.20 | |||
_© Copyright 2023 Contributors. All rights reserved._ | |||
@@ -30,7 +35,7 @@ here: | |||
* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.20.1[GitHub 1.9.20.1] | |||
* https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.20[Bugzilla 1.9.20] | |||
=== New features | |||
== New features | |||
AspectJ 1.9.20 supports https://openjdk.java.net/projects/jdk/20/[Java 20] and its final, preview and incubator | |||
features, such as: | |||
@@ -45,7 +50,7 @@ some open issues concerning Java 20 preview feature support, see the list in | |||
https://github.com/eclipse/org.aspectj/issues/184#issuecomment-1272254940[this comment]. AJC therefore inherits the same | |||
problems for the specific cases described in the linked issues. | |||
=== Improvements | |||
== Improvements | |||
* Since Java 9 and the introduction of the Java Module System, the upstream Eclipse Java Compiler (ECJ) and Eclipse Java | |||
Development Tools (JDT) had gone through some internal changes, enabling both the compiler and the IDE to handle new | |||
@@ -58,7 +63,7 @@ problems for the specific cases described in the linked issues. | |||
matching has been improved considerably. You can find some examples | |||
https://github.com/eclipse-aspectj/aspectj/tree/master/tests/bugs1920/github_24[here]. | |||
=== Code examples | |||
== Code examples | |||
You can find some sample code in the AspectJ test suite under the respective AspectJ version in which the features were | |||
first supported (possibly as JVM preview features): | |||
@@ -74,14 +79,14 @@ first supported (possibly as JVM preview features): | |||
concurrency features elsewhere, e.g. in the corresponding JEPs. In AspectJ, they should just work transparently like | |||
any other Java API. | |||
=== Other changes and bug fixes | |||
== Other changes and bug fixes | |||
* About a dozen bugs have been fixed, some of them quite old. See "list of issues addressed" further above and follow | |||
the link to GitHub to find out if your issue is among them. | |||
=== AspectJ usage hints | |||
== AspectJ usage hints | |||
==== AspectJ compiler build system requirements | |||
=== AspectJ compiler build system requirements | |||
Since 1.9.8, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 8 to 10. The | |||
minimum compile-time requirement is now JDK 11 due to upstream changes in the Eclipse Java Compiler (subset of JDT | |||
@@ -90,7 +95,7 @@ plain Java code or using plain Java ITD constructs which do not require the Aspe | |||
compiler itself needs JDK 11+. Just like in previous AspectJ versions, both the runtime `aspectjrt` and the load-time | |||
weaver `aspectjweaver` still only require JRE 8+. | |||
==== Use LTW on Java 16+ | |||
=== Use LTW on Java 16+ | |||
Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with | |||
https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to set | |||
@@ -98,7 +103,7 @@ the JVM parameter `--add-opens java.base/java.lang=ALL-UNNAMED` in order to enab | |||
fact that the weaver uses internal APIs for which we have not found an adequate replacement yet when defining classes | |||
in different classloaders. | |||
==== Compile with Java preview features | |||
=== Compile with Java preview features | |||
For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with | |||
`java --enable-preview` on that JDK. |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.9.21 | |||
= AspectJ 1.9.21 | |||
_© Copyright 2023 Contributors. All rights reserved._ | |||
@@ -12,7 +12,7 @@ here: | |||
* https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.21.1[GitHub 1.9.21.1] | |||
* https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&f0=OP&f1=OP&f3=CP&f4=CP&j1=OR&list_id=16866879&product=AspectJ&query_format=advanced&target_milestone=1.9.21[Bugzilla 1.9.21] | |||
=== New features | |||
== New features | |||
AspectJ 1.9.21 supports https://openjdk.java.net/projects/jdk/21/[Java 21], its final features and a subset of preview | |||
features, such as: | |||
@@ -35,18 +35,18 @@ officially supported in Eclipse 2023-12, some preview features are still unimple | |||
As soon as these preview features are part of the upstream ECJ we depend on, we hope to publish another AspectJ release | |||
to support them in the AspectJ Compiler (AJC), too. | |||
=== Improvements | |||
== Improvements | |||
* In https://github.com/eclipse-aspectj/aspectj/issues/266[GitHub issue 266], exception cause reporting has been | |||
improved in `ExtensibleURLClassLoader`. Thanks to Andy Russell (@euclio) for his contribution. | |||
=== Other changes and bug fixes | |||
== Other changes and bug fixes | |||
* No major bug fixes | |||
=== AspectJ usage hints | |||
== AspectJ usage hints | |||
==== AspectJ compiler build system requirements | |||
=== AspectJ compiler build system requirements | |||
Since 1.9.21, the AspectJ compiler `ajc` (contained in the `aspectjtools` library) no longer works on JDKs 11 to 16. The | |||
minimum compile-time requirement is now JDK 17 due to upstream changes in the Eclipse Java Compiler (subset of JDT | |||
@@ -62,7 +62,7 @@ details. | |||
History: Since 1.9.8, the AspectJ compiler ajc needed JDK 11+, before then JDK 8+. | |||
==== Use LTW on Java 16+ | |||
=== Use LTW on Java 16+ | |||
Please note that if you want to use load-time weaving on Java 16+, the weaving agent collides with | |||
https://openjdk.java.net/jeps/396[JEP 396 (Strongly Encapsulate JDK Internals by Default)] and related subsequent | |||
@@ -70,7 +70,7 @@ JEPs. Therefore, you need to set the JVM parameter `--add-opens java.base/java.l | |||
aspect weaving. This is due to the fact that the weaver uses internal APIs for which we have not found an adequate | |||
replacement yet when defining classes in different classloaders. | |||
==== Compile with Java preview features | |||
=== Compile with Java preview features | |||
For features marked as preview on a given JDK, you need to compile with `ajc --enable-preview` and run with | |||
`java --enable-preview` on that JDK. |
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.9.3 | |||
= AspectJ 1.9.3 | |||
_© Copyright 2018 Contributors. All rights reserved._ | |||
@@ -1,4 +1,4 @@ | |||
== AspectJ 1.9.4 | |||
= AspectJ 1.9.4 | |||
_© Copyright 2019 Contributors. All rights reserved._ | |||