From 0dee7d2d97ebe16eb46124f5b8b0e23fbf6f3569 Mon Sep 17 00:00:00 2001 From: Alexander Kriegisch Date: Tue, 30 Jan 2024 13:44:19 +0700 Subject: [PATCH] Headlines per ADOC file should start at level 1, not 2 Signed-off-by: Alexander Kriegisch --- docs/modules/ROOT/pages/LICENSE-AspectJ.adoc | 8 +- docs/modules/ROOT/pages/README-AspectJ.adoc | 14 +- .../ROOT/pages/developer/compiler-weaver.adoc | 62 ++--- .../ROOT/pages/developer/language.adoc | 18 +- .../modules/ROOT/pages/developer/modules.adoc | 8 +- .../ROOT/pages/examples/spacewar/README.adoc | 8 +- docs/modules/ROOT/pages/index.adoc | 10 +- .../ubc-design-patterns/patterns-readme.adoc | 2 +- .../teaching/exercises/plugins/index.adoc | 2 +- .../adk15notebook/pages/annotations.adoc | 48 ++-- .../adk15notebook/pages/ataspectj.adoc | 28 +-- .../adk15notebook/pages/autoboxing.adoc | 8 +- .../adk15notebook/pages/covariance.adoc | 6 +- .../adk15notebook/pages/enumeratedtypes.adoc | 6 +- .../modules/adk15notebook/pages/generics.adoc | 38 +-- docs/modules/adk15notebook/pages/grammar.adoc | 18 +- .../pages/joinpointsignatures.adoc | 16 +- docs/modules/adk15notebook/pages/ltw.adoc | 4 +- .../adk15notebook/pages/miscellaneous.adoc | 6 +- .../adk15notebook/pages/pertypewithin.adoc | 2 +- .../adk15notebook/pages/reflection.adoc | 4 +- docs/modules/adk15notebook/pages/varargs.adoc | 12 +- docs/modules/devguide/pages/aj.adoc | 10 +- docs/modules/devguide/pages/ajc.adoc | 20 +- docs/modules/devguide/pages/ajdb.adoc | 8 +- docs/modules/devguide/pages/ajdoc.adoc | 10 +- docs/modules/devguide/pages/antsupport.adoc | 42 ++-- .../modules/devguide/pages/compatibility.adoc | 14 +- docs/modules/devguide/pages/ltw.adoc | 30 +-- docs/modules/devguide/pages/tools-intro.adoc | 8 +- docs/modules/pdguide/pages/ajcore.adoc | 8 +- docs/modules/pdguide/pages/ltwdump.adoc | 8 +- docs/modules/pdguide/pages/messages.adoc | 18 +- docs/modules/pdguide/pages/pointcuts.adoc | 20 +- docs/modules/pdguide/pages/trace.adoc | 8 +- docs/modules/progguide/pages/examples.adoc | 98 ++++---- .../progguide/pages/gettingstarted.adoc | 40 +-- docs/modules/progguide/pages/idioms.adoc | 4 +- .../progguide/pages/implementation.adoc | 16 +- docs/modules/progguide/pages/language.adoc | 36 +-- docs/modules/progguide/pages/pitfalls.adoc | 6 +- docs/modules/progguide/pages/preface.adoc | 2 +- .../progguide/pages/quickreference.adoc | 14 +- docs/modules/progguide/pages/semantics.adoc | 134 +++++----- docs/modules/release/pages/README-1.1.adoc | 100 ++++---- docs/modules/release/pages/README-1.2.1.adoc | 20 +- docs/modules/release/pages/README-1.2.adoc | 38 +-- docs/modules/release/pages/README-1.5.0.adoc | 2 +- docs/modules/release/pages/README-1.5.1.adoc | 2 +- docs/modules/release/pages/README-1.5.2.adoc | 2 +- docs/modules/release/pages/README-1.5.3.adoc | 14 +- docs/modules/release/pages/README-1.5.4.adoc | 2 +- docs/modules/release/pages/README-1.6.0.adoc | 16 +- docs/modules/release/pages/README-1.6.1.adoc | 18 +- docs/modules/release/pages/README-1.6.10.adoc | 8 +- docs/modules/release/pages/README-1.6.11.adoc | 18 +- docs/modules/release/pages/README-1.6.12.adoc | 24 +- docs/modules/release/pages/README-1.6.2.adoc | 4 +- docs/modules/release/pages/README-1.6.3.adoc | 10 +- docs/modules/release/pages/README-1.6.4.adoc | 14 +- docs/modules/release/pages/README-1.6.5.adoc | 4 +- docs/modules/release/pages/README-1.6.6.adoc | 6 +- docs/modules/release/pages/README-1.6.7.adoc | 16 +- docs/modules/release/pages/README-1.6.8.adoc | 6 +- docs/modules/release/pages/README-1.6.9.adoc | 28 +-- docs/modules/release/pages/README-1.7.0.adoc | 10 +- docs/modules/release/pages/README-1.7.1.adoc | 4 +- docs/modules/release/pages/README-1.7.2.adoc | 4 +- docs/modules/release/pages/README-1.7.3.adoc | 2 +- docs/modules/release/pages/README-1.7.4.adoc | 2 +- docs/modules/release/pages/README-1.8.0.adoc | 6 +- docs/modules/release/pages/README-1.8.1.adoc | 6 +- docs/modules/release/pages/README-1.8.10.adoc | 10 +- docs/modules/release/pages/README-1.8.11.adoc | 2 +- docs/modules/release/pages/README-1.8.2.adoc | 16 +- docs/modules/release/pages/README-1.8.3.adoc | 10 +- docs/modules/release/pages/README-1.8.4.adoc | 8 +- docs/modules/release/pages/README-1.8.5.adoc | 4 +- docs/modules/release/pages/README-1.8.6.adoc | 2 +- docs/modules/release/pages/README-1.8.7.adoc | 8 +- docs/modules/release/pages/README-1.8.8.adoc | 6 +- docs/modules/release/pages/README-1.8.9.adoc | 4 +- docs/modules/release/pages/README-1.9.0.adoc | 22 +- docs/modules/release/pages/README-1.9.1.adoc | 4 +- docs/modules/release/pages/README-1.9.19.adoc | 20 +- docs/modules/release/pages/README-1.9.2.adoc | 4 +- docs/modules/release/pages/README-1.9.20.adoc | 20 +- docs/modules/release/pages/README-1.9.21.adoc | 16 +- docs/modules/release/pages/README-1.9.3.adoc | 2 +- docs/modules/release/pages/README-1.9.4.adoc | 2 +- docs/modules/release/pages/README-1.9.5.adoc | 2 +- docs/modules/release/pages/README-1.9.6.adoc | 2 +- docs/modules/release/pages/README-1.9.7.adoc | 10 +- docs/modules/release/pages/README-1.9.8.adoc | 16 +- docs/modules/release/pages/README-1.9.9.adoc | 20 +- docs/modules/release/pages/changes.adoc | 228 +++++++++--------- docs/modules/release/pages/porting.adoc | 128 +++++----- 97 files changed, 917 insertions(+), 917 deletions(-) diff --git a/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc b/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc index ca18dbede..8f3a4ac30 100644 --- a/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc +++ b/docs/modules/ROOT/pages/LICENSE-AspectJ.adoc @@ -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 @@ -19,7 +19,7 @@ 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]. -=== 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 @@ -29,7 +29,7 @@ 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 +40,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 diff --git a/docs/modules/ROOT/pages/README-AspectJ.adoc b/docs/modules/ROOT/pages/README-AspectJ.adoc index c754f3a44..e8905dfcf 100644 --- a/docs/modules/ROOT/pages/README-AspectJ.adoc +++ b/docs/modules/ROOT/pages/README-AspectJ.adoc @@ -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[`/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 `/lib/aspectjrt.jar` to your classpath +=== 4.1 Adding `/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. diff --git a/docs/modules/ROOT/pages/developer/compiler-weaver.adoc b/docs/modules/ROOT/pages/developer/compiler-weaver.adoc index f5784a983..be3eb0a94 100644 --- a/docs/modules/ROOT/pages/developer/compiler-weaver.adoc +++ b/docs/modules/ROOT/pages/developer/compiler-weaver.adoc @@ -1,4 +1,4 @@ -== Guide for Developers of the AspectJ Compiler and Weaver += Guide for Developers of the AspectJ Compiler and Weaver _Latest (non-license) content update: 2004-02-20 by jhugunin_ @@ -36,7 +36,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 +61,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 +96,7 @@ When parsed, this program will produce the following tree. image:top-tree.png[image] -==== PointcutDeclaration processing +=== PointcutDeclaration processing Let's look more closely at the pointcut declaration: @@ -112,7 +112,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 +138,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: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 +174,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 +191,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 +222,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 +237,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 +261,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 +315,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 +362,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 +450,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 +481,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 +526,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 +557,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 +601,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 +683,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 +734,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 +777,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 +906,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 +927,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 +972,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 +1001,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 +1060,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 +1120,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 +1169,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 diff --git a/docs/modules/ROOT/pages/developer/language.adoc b/docs/modules/ROOT/pages/developer/language.adoc index 28a3f7548..45ee827ad 100644 --- a/docs/modules/ROOT/pages/developer/language.adoc +++ b/docs/modules/ROOT/pages/developer/language.adoc @@ -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. diff --git a/docs/modules/ROOT/pages/developer/modules.adoc b/docs/modules/ROOT/pages/developer/modules.adoc index 74292212b..2cb60910f 100644 --- a/docs/modules/ROOT/pages/developer/modules.adoc +++ b/docs/modules/ROOT/pages/developer/modules.adoc @@ -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 diff --git a/docs/modules/ROOT/pages/examples/spacewar/README.adoc b/docs/modules/ROOT/pages/examples/spacewar/README.adoc index 9991867a3..d39b9b5fc 100644 --- a/docs/modules/ROOT/pages/examples/spacewar/README.adoc +++ b/docs/modules/ROOT/pages/examples/spacewar/README.adoc @@ -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 diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 4daa8ee0a..32a8d2001 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -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 diff --git a/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc b/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc index ade559c2d..7820d8b01 100644 --- a/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc +++ b/docs/modules/ROOT/pages/sandbox/ubc-design-patterns/patterns-readme.adoc @@ -1,4 +1,4 @@ -== AspectJ Patterns += AspectJ Patterns _Last updated: 2004-03-31 by wisberg_ diff --git a/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc b/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc index 1cdf0fbc1..9a70bf6a9 100644 --- a/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc +++ b/docs/modules/ROOT/pages/teaching/exercises/plugins/index.adoc @@ -1,4 +1,4 @@ -== Exercises plugin for the tutorial += Exercises plugin for the tutorial Download the appropriate version and unzip it in your eclipse\plugins directory: diff --git a/docs/modules/adk15notebook/pages/annotations.adoc b/docs/modules/adk15notebook/pages/annotations.adoc index 5fcf74608..24a0d27e5 100644 --- a/docs/modules/adk15notebook/pages/annotations.adoc +++ b/docs/modules/adk15notebook/pages/annotations.adoc @@ -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. diff --git a/docs/modules/adk15notebook/pages/ataspectj.adoc b/docs/modules/adk15notebook/pages/ataspectj.adoc index 3b4d2ae59..028ef4c85 100644 --- a/docs/modules/adk15notebook/pages/ataspectj.adoc +++ b/docs/modules/adk15notebook/pages/ataspectj.adoc @@ -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 diff --git a/docs/modules/adk15notebook/pages/autoboxing.adoc b/docs/modules/adk15notebook/pages/autoboxing.adoc index fa3842950..11803d632 100644 --- a/docs/modules/adk15notebook/pages/autoboxing.adoc +++ b/docs/modules/adk15notebook/pages/autoboxing.adoc @@ -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 diff --git a/docs/modules/adk15notebook/pages/covariance.adoc b/docs/modules/adk15notebook/pages/covariance.adoc index 2349bf52c..fdaa6000d 100644 --- a/docs/modules/adk15notebook/pages/covariance.adoc +++ b/docs/modules/adk15notebook/pages/covariance.adoc @@ -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. diff --git a/docs/modules/adk15notebook/pages/enumeratedtypes.adoc b/docs/modules/adk15notebook/pages/enumeratedtypes.adoc index 64a96d2f6..a8e6b20fd 100644 --- a/docs/modules/adk15notebook/pages/enumeratedtypes.adoc +++ b/docs/modules/adk15notebook/pages/enumeratedtypes.adoc @@ -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 diff --git a/docs/modules/adk15notebook/pages/generics.adoc b/docs/modules/adk15notebook/pages/generics.adoc index 8fc99bdbe..404da5514 100644 --- a/docs/modules/adk15notebook/pages/generics.adoc +++ b/docs/modules/adk15notebook/pages/generics.adoc @@ -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` can be assigned to a variable of type `Collection`, and `List` can be assigned to a variable of type `List`. -==== 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`. 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 foo(List>)` since the erasure of `List` is `List` and not `List`. -===== 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`, you can only declare members on the generic type `Bar`. [[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 diff --git a/docs/modules/adk15notebook/pages/grammar.adoc b/docs/modules/adk15notebook/pages/grammar.adoc index 42b0a0fa5..710f98947 100644 --- a/docs/modules/adk15notebook/pages/grammar.adoc +++ b/docs/modules/adk15notebook/pages/grammar.adoc @@ -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... .... diff --git a/docs/modules/adk15notebook/pages/joinpointsignatures.adoc b/docs/modules/adk15notebook/pages/joinpointsignatures.adoc index 1ed54baa8..9daf279e2 100644 --- a/docs/modules/adk15notebook/pages/joinpointsignatures.adoc +++ b/docs/modules/adk15notebook/pages/joinpointsignatures.adoc @@ -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, @@ -284,7 +284,7 @@ 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 diff --git a/docs/modules/adk15notebook/pages/ltw.adoc b/docs/modules/adk15notebook/pages/ltw.adoc index c6c3e73f4..ddf5af356 100644 --- a/docs/modules/adk15notebook/pages/ltw.adoc +++ b/docs/modules/adk15notebook/pages/ltw.adoc @@ -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. diff --git a/docs/modules/adk15notebook/pages/miscellaneous.adoc b/docs/modules/adk15notebook/pages/miscellaneous.adoc index a61f704b8..eff35ab7c 100644 --- a/docs/modules/adk15notebook/pages/miscellaneous.adoc +++ b/docs/modules/adk15notebook/pages/miscellaneous.adoc @@ -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 diff --git a/docs/modules/adk15notebook/pages/pertypewithin.adoc b/docs/modules/adk15notebook/pages/pertypewithin.adoc index 32295fc1f..8d8abbb66 100644 --- a/docs/modules/adk15notebook/pages/pertypewithin.adoc +++ b/docs/modules/adk15notebook/pages/pertypewithin.adoc @@ -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 diff --git a/docs/modules/adk15notebook/pages/reflection.adoc b/docs/modules/adk15notebook/pages/reflection.adoc index b39919229..fa7934a90 100644 --- a/docs/modules/adk15notebook/pages/reflection.adoc +++ b/docs/modules/adk15notebook/pages/reflection.adoc @@ -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 diff --git a/docs/modules/adk15notebook/pages/varargs.adoc b/docs/modules/adk15notebook/pages/varargs.adoc index 3f13ab31a..d45498b85 100644 --- a/docs/modules/adk15notebook/pages/varargs.adoc +++ b/docs/modules/adk15notebook/pages/varargs.adoc @@ -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 diff --git a/docs/modules/devguide/pages/aj.adoc b/docs/modules/devguide/pages/aj.adoc index 0a7b53108..2aa2c2c6e 100644 --- a/docs/modules/devguide/pages/aj.adoc +++ b/docs/modules/devguide/pages/aj.adoc @@ -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 diff --git a/docs/modules/devguide/pages/ajc.adoc b/docs/modules/devguide/pages/ajc.adoc index 7fbc4053a..078ef5ff4 100644 --- a/docs/modules/devguide/pages/ajc.adoc +++ b/docs/modules/devguide/pages/ajc.adoc @@ -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). @@ -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 `:: deprecated: since 1.2, use -inpath, which also takes directories. @@ -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 diff --git a/docs/modules/devguide/pages/ajdb.adoc b/docs/modules/devguide/pages/ajdb.adoc index 4e45cbc80..120cb498d 100644 --- a/docs/modules/devguide/pages/ajdb.adoc +++ b/docs/modules/devguide/pages/ajdb.adoc @@ -50,7 +50,7 @@ class arguments -== Description += Description The command `ajdb` is used to debug AspectJ and Java programs. In addition to its command line interface, `adjb` also has a standalone, @@ -131,14 +131,14 @@ option Pass a non-standard option to the VM -=== Capabilities +== Capabilities The AspectJ debugger implements all of ``jdb``'s commands. In addition, the command `workingdir` allow you to set the AspectJ working directory, and the breakpoint command, `stop on`, has been extended to allow the setting of breakpoint on a source file line. -=== Examples +== Examples Suppose you want to debug the file spacewar/Ship.java found in the examples directory. At the command line start up the debugger: ` @@ -306,7 +306,7 @@ following message: The application has exited. .... -=== The AspectJ debugger API +== The AspectJ debugger API The AspectJ debugger is implemented completely in Java and can be called as a Java class. The only interface that should be considered public is diff --git a/docs/modules/devguide/pages/ajdoc.adoc b/docs/modules/devguide/pages/ajdoc.adoc index 6bea2ff16..eaa0ee1b5 100644 --- a/docs/modules/devguide/pages/ajdoc.adoc +++ b/docs/modules/devguide/pages/ajdoc.adoc @@ -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. diff --git a/docs/modules/devguide/pages/antsupport.adoc b/docs/modules/devguide/pages/antsupport.adoc index 6c8217930..ba74d32dd 100644 --- a/docs/modules/devguide/pages/antsupport.adoc +++ b/docs/modules/devguide/pages/antsupport.adoc @@ -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 @@ -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`, @@ -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,7 +507,7 @@ 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` @@ -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. @@ -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,7 +733,7 @@ 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 source file paths (absolute or relative to the argfile). You can use it @@ -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 @@ -826,7 +826,7 @@ 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, diff --git a/docs/modules/devguide/pages/compatibility.adoc b/docs/modules/devguide/pages/compatibility.adoc index 63822e003..ea96ebf3c 100644 --- a/docs/modules/devguide/pages/compatibility.adoc +++ b/docs/modules/devguide/pages/compatibility.adoc @@ -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 diff --git a/docs/modules/devguide/pages/ltw.adoc b/docs/modules/devguide/pages/ltw.adoc index 5966ba993..1d1831c92 100644 --- a/docs/modules/devguide/pages/ltw.adoc +++ b/docs/modules/devguide/pages/ltw.adoc @@ -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 diff --git a/docs/modules/devguide/pages/tools-intro.adoc b/docs/modules/devguide/pages/tools-intro.adoc index 7673d3fc5..c9bd34ea5 100644 --- a/docs/modules/devguide/pages/tools-intro.adoc +++ b/docs/modules/devguide/pages/tools-intro.adoc @@ -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], diff --git a/docs/modules/pdguide/pages/ajcore.adoc b/docs/modules/pdguide/pages/ajcore.adoc index 5928d372d..39b727286 100644 --- a/docs/modules/pdguide/pages/ajcore.adoc +++ b/docs/modules/pdguide/pages/ajcore.adoc @@ -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 diff --git a/docs/modules/pdguide/pages/ltwdump.adoc b/docs/modules/pdguide/pages/ltwdump.adoc index 8442a36a3..43d71805f 100644 --- a/docs/modules/pdguide/pages/ltwdump.adoc +++ b/docs/modules/pdguide/pages/ltwdump.adoc @@ -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,7 +16,7 @@ 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 @@ -24,7 +24,7 @@ xref:../devguide/ltw.html#configuring-load-time-weaving-with-aopxml-files[Config 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 diff --git a/docs/modules/pdguide/pages/messages.adoc b/docs/modules/pdguide/pages/messages.adoc index b9b1779d5..c32d07f07 100644 --- a/docs/modules/pdguide/pages/messages.adoc +++ b/docs/modules/pdguide/pages/messages.adoc @@ -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. diff --git a/docs/modules/pdguide/pages/pointcuts.adoc b/docs/modules/pdguide/pages/pointcuts.adoc index ecd964c57..e5199fc95 100644 --- a/docs/modules/pdguide/pages/pointcuts.adoc +++ b/docs/modules/pdguide/pages/pointcuts.adoc @@ -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 diff --git a/docs/modules/pdguide/pages/trace.adoc b/docs/modules/pdguide/pages/trace.adoc index a752e0262..d9c9de1d9 100644 --- a/docs/modules/pdguide/pages/trace.adoc +++ b/docs/modules/pdguide/pages/trace.adoc @@ -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 diff --git a/docs/modules/progguide/pages/examples.adoc b/docs/modules/progguide/pages/examples.adoc index 392db2606..bb438d99d 100644 --- a/docs/modules/progguide/pages/examples.adoc +++ b/docs/modules/progguide/pages/examples.adoc @@ -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: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: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 diff --git a/docs/modules/progguide/pages/gettingstarted.adoc b/docs/modules/progguide/pages/gettingstarted.adoc index 2806d4cad..f76c4fb4e 100644 --- a/docs/modules/progguide/pages/gettingstarted.adoc +++ b/docs/modules/progguide/pages/gettingstarted.adoc @@ -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 diff --git a/docs/modules/progguide/pages/idioms.adoc b/docs/modules/progguide/pages/idioms.adoc index e27395a48..a264084e0 100644 --- a/docs/modules/progguide/pages/idioms.adoc +++ b/docs/modules/progguide/pages/idioms.adoc @@ -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 diff --git a/docs/modules/progguide/pages/implementation.adoc b/docs/modules/progguide/pages/implementation.adoc index 42ee2e37e..03a0e19ae 100644 --- a/docs/modules/progguide/pages/implementation.adoc +++ b/docs/modules/progguide/pages/implementation.adoc @@ -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. diff --git a/docs/modules/progguide/pages/language.adoc b/docs/modules/progguide/pages/language.adoc index 14b662aad..72a49e813 100644 --- a/docs/modules/progguide/pages/language.adoc +++ b/docs/modules/progguide/pages/language.adoc @@ -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 diff --git a/docs/modules/progguide/pages/pitfalls.adoc b/docs/modules/progguide/pages/pitfalls.adoc index eb9e15315..a80460c58 100644 --- a/docs/modules/progguide/pages/pitfalls.adoc +++ b/docs/modules/progguide/pages/pitfalls.adoc @@ -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 diff --git a/docs/modules/progguide/pages/preface.adoc b/docs/modules/progguide/pages/preface.adoc index efeb18637..92f0c1da0 100644 --- a/docs/modules/progguide/pages/preface.adoc +++ b/docs/modules/progguide/pages/preface.adoc @@ -1,4 +1,4 @@ -== Preface += Preface This programming guide does three things. It diff --git a/docs/modules/progguide/pages/quickreference.adoc b/docs/modules/progguide/pages/quickreference.adoc index 3920b5ef2..d1a16066d 100644 --- a/docs/modules/progguide/pages/quickreference.adoc +++ b/docs/modules/progguide/pages/quickreference.adoc @@ -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 diff --git a/docs/modules/progguide/pages/semantics.adoc b/docs/modules/progguide/pages/semantics.adoc index 0cb513ad0..d993d2fcb 100644 --- a/docs/modules/progguide/pages/semantics.adoc +++ b/docs/modules/progguide/pages/semantics.adoc @@ -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 { ... }` diff --git a/docs/modules/release/pages/README-1.1.adoc b/docs/modules/release/pages/README-1.1.adoc index d846cff81..f78e4ce70 100644 --- a/docs/modules/release/pages/README-1.1.adoc +++ b/docs/modules/release/pages/README-1.1.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.2.1.adoc b/docs/modules/release/pages/README-1.2.1.adoc index 04cb6e831..d90d232ed 100644 --- a/docs/modules/release/pages/README-1.2.1.adoc +++ b/docs/modules/release/pages/README-1.2.1.adoc @@ -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: diff --git a/docs/modules/release/pages/README-1.2.adoc b/docs/modules/release/pages/README-1.2.adoc index 9aa8503d8..f57abe83b 100644 --- a/docs/modules/release/pages/README-1.2.adoc +++ b/docs/modules/release/pages/README-1.2.adoc @@ -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:ajdoc1.JPG[image] image: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: diff --git a/docs/modules/release/pages/README-1.5.0.adoc b/docs/modules/release/pages/README-1.5.0.adoc index e3f7c1196..6cab50115 100644 --- a/docs/modules/release/pages/README-1.5.0.adoc +++ b/docs/modules/release/pages/README-1.5.0.adoc @@ -1,4 +1,4 @@ -== AspectJ 5 += AspectJ 5 _© Copyright 2005 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.5.1.adoc b/docs/modules/release/pages/README-1.5.1.adoc index bc513d512..724d4ecbb 100644 --- a/docs/modules/release/pages/README-1.5.1.adoc +++ b/docs/modules/release/pages/README-1.5.1.adoc @@ -1,4 +1,4 @@ -== AspectJ 5 v1.5.1 Readme += AspectJ 5 v1.5.1 Readme _© Copyright 2006 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.5.2.adoc b/docs/modules/release/pages/README-1.5.2.adoc index b903a9841..fa905a0de 100644 --- a/docs/modules/release/pages/README-1.5.2.adoc +++ b/docs/modules/release/pages/README-1.5.2.adoc @@ -1,4 +1,4 @@ -== AspectJ 5 v1.5.2 Readme += AspectJ 5 v1.5.2 Readme _© Copyright 2006 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.5.3.adoc b/docs/modules/release/pages/README-1.5.3.adoc index d5d9a228c..280181aeb 100644 --- a/docs/modules/release/pages/README-1.5.3.adoc +++ b/docs/modules/release/pages/README-1.5.3.adoc @@ -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: diff --git a/docs/modules/release/pages/README-1.5.4.adoc b/docs/modules/release/pages/README-1.5.4.adoc index 7c8fa50cc..f301664c8 100644 --- a/docs/modules/release/pages/README-1.5.4.adoc +++ b/docs/modules/release/pages/README-1.5.4.adoc @@ -1,4 +1,4 @@ -== AspectJ 5 v1.5.4 Readme += AspectJ 5 v1.5.4 Readme _© Copyright 2006 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.6.0.adoc b/docs/modules/release/pages/README-1.6.0.adoc index 5e37c8efb..7ad1d7827 100644 --- a/docs/modules/release/pages/README-1.6.0.adoc +++ b/docs/modules/release/pages/README-1.6.0.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.6.1.adoc b/docs/modules/release/pages/README-1.6.1.adoc index a59e3b0bb..c04fc6eda 100644 --- a/docs/modules/release/pages/README-1.6.1.adoc +++ b/docs/modules/release/pages/README-1.6.1.adoc @@ -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: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: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: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 diff --git a/docs/modules/release/pages/README-1.6.10.adoc b/docs/modules/release/pages/README-1.6.10.adoc index 5f571fce9..31a44ab8f 100644 --- a/docs/modules/release/pages/README-1.6.10.adoc +++ b/docs/modules/release/pages/README-1.6.10.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.6.11.adoc b/docs/modules/release/pages/README-1.6.11.adoc index e5f4226a2..b2e982c71 100644 --- a/docs/modules/release/pages/README-1.6.11.adoc +++ b/docs/modules/release/pages/README-1.6.11.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.6.12.adoc b/docs/modules/release/pages/README-1.6.12.adoc index ed9951d4d..165cd33a2 100644 --- a/docs/modules/release/pages/README-1.6.12.adoc +++ b/docs/modules/release/pages/README-1.6.12.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.6.2.adoc b/docs/modules/release/pages/README-1.6.2.adoc index a6b88ffee..56cc0adc9 100644 --- a/docs/modules/release/pages/README-1.6.2.adoc +++ b/docs/modules/release/pages/README-1.6.2.adoc @@ -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. diff --git a/docs/modules/release/pages/README-1.6.3.adoc b/docs/modules/release/pages/README-1.6.3.adoc index 1609eb35f..3fbb1e249 100644 --- a/docs/modules/release/pages/README-1.6.3.adoc +++ b/docs/modules/release/pages/README-1.6.3.adoc @@ -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. diff --git a/docs/modules/release/pages/README-1.6.4.adoc b/docs/modules/release/pages/README-1.6.4.adoc index dc3a71816..e3d2550df 100644 --- a/docs/modules/release/pages/README-1.6.4.adoc +++ b/docs/modules/release/pages/README-1.6.4.adoc @@ -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* diff --git a/docs/modules/release/pages/README-1.6.5.adoc b/docs/modules/release/pages/README-1.6.5.adoc index 28396df40..1647e73d1 100644 --- a/docs/modules/release/pages/README-1.6.5.adoc +++ b/docs/modules/release/pages/README-1.6.5.adoc @@ -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: diff --git a/docs/modules/release/pages/README-1.6.6.adoc b/docs/modules/release/pages/README-1.6.6.adoc index 940b2cf96..28a1c68a6 100644 --- a/docs/modules/release/pages/README-1.6.6.adoc +++ b/docs/modules/release/pages/README-1.6.6.adoc @@ -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* diff --git a/docs/modules/release/pages/README-1.6.7.adoc b/docs/modules/release/pages/README-1.6.7.adoc index e1abc246f..ba26305b8 100644 --- a/docs/modules/release/pages/README-1.6.7.adoc +++ b/docs/modules/release/pages/README-1.6.7.adoc @@ -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:167speed.png[image] image: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: diff --git a/docs/modules/release/pages/README-1.6.8.adoc b/docs/modules/release/pages/README-1.6.8.adoc index 0adbd557a..42828d99a 100644 --- a/docs/modules/release/pages/README-1.6.8.adoc +++ b/docs/modules/release/pages/README-1.6.8.adoc @@ -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] diff --git a/docs/modules/release/pages/README-1.6.9.adoc b/docs/modules/release/pages/README-1.6.9.adoc index 943cc6d90..a7923cf01 100644 --- a/docs/modules/release/pages/README-1.6.9.adoc +++ b/docs/modules/release/pages/README-1.6.9.adoc @@ -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 .... -==== 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 diff --git a/docs/modules/release/pages/README-1.7.0.adoc b/docs/modules/release/pages/README-1.7.0.adoc index 2437d10ef..6856b161a 100644 --- a/docs/modules/release/pages/README-1.7.0.adoc +++ b/docs/modules/release/pages/README-1.7.0.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.7.1.adoc b/docs/modules/release/pages/README-1.7.1.adoc index 30515f0e2..6910b64e9 100644 --- a/docs/modules/release/pages/README-1.7.1.adoc +++ b/docs/modules/release/pages/README-1.7.1.adoc @@ -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 + diff --git a/docs/modules/release/pages/README-1.7.2.adoc b/docs/modules/release/pages/README-1.7.2.adoc index 52754ad8e..a846f61ea 100644 --- a/docs/modules/release/pages/README-1.7.2.adoc +++ b/docs/modules/release/pages/README-1.7.2.adoc @@ -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. diff --git a/docs/modules/release/pages/README-1.7.3.adoc b/docs/modules/release/pages/README-1.7.3.adoc index 73a0ad320..0ef861cc4 100644 --- a/docs/modules/release/pages/README-1.7.3.adoc +++ b/docs/modules/release/pages/README-1.7.3.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.7.3 += AspectJ 1.7.3 _© Copyright 2011 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.7.4.adoc b/docs/modules/release/pages/README-1.7.4.adoc index 20464744a..c4c084245 100644 --- a/docs/modules/release/pages/README-1.7.4.adoc +++ b/docs/modules/release/pages/README-1.7.4.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.7.4 += AspectJ 1.7.4 _© Copyright 2013 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.8.0.adoc b/docs/modules/release/pages/README-1.8.0.adoc index 9a2ba78be..de5a6a987 100644 --- a/docs/modules/release/pages/README-1.8.0.adoc +++ b/docs/modules/release/pages/README-1.8.0.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.1.adoc b/docs/modules/release/pages/README-1.8.1.adoc index ef0e8a1ee..081820094 100644 --- a/docs/modules/release/pages/README-1.8.1.adoc +++ b/docs/modules/release/pages/README-1.8.1.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.10.adoc b/docs/modules/release/pages/README-1.8.10.adoc index cce5da187..21516350e 100644 --- a/docs/modules/release/pages/README-1.8.10.adoc +++ b/docs/modules/release/pages/README-1.8.10.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.11.adoc b/docs/modules/release/pages/README-1.8.11.adoc index dedbc0463..a8ee63da3 100644 --- a/docs/modules/release/pages/README-1.8.11.adoc +++ b/docs/modules/release/pages/README-1.8.11.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.8.11 += AspectJ 1.8.11 _© Copyright 2017 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.8.2.adoc b/docs/modules/release/pages/README-1.8.2.adoc index a49213617..ee3bbc4b6 100644 --- a/docs/modules/release/pages/README-1.8.2.adoc +++ b/docs/modules/release/pages/README-1.8.2.adoc @@ -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] .... diff --git a/docs/modules/release/pages/README-1.8.3.adoc b/docs/modules/release/pages/README-1.8.3.adoc index 0d114d1f2..e1015d709 100644 --- a/docs/modules/release/pages/README-1.8.3.adoc +++ b/docs/modules/release/pages/README-1.8.3.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.4.adoc b/docs/modules/release/pages/README-1.8.4.adoc index 655d74a85..b70d97240 100644 --- a/docs/modules/release/pages/README-1.8.4.adoc +++ b/docs/modules/release/pages/README-1.8.4.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.5.adoc b/docs/modules/release/pages/README-1.8.5.adoc index 22fdcee3f..6585ee2ec 100644 --- a/docs/modules/release/pages/README-1.8.5.adoc +++ b/docs/modules/release/pages/README-1.8.5.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.6.adoc b/docs/modules/release/pages/README-1.8.6.adoc index 9a2129414..780831ae7 100644 --- a/docs/modules/release/pages/README-1.8.6.adoc +++ b/docs/modules/release/pages/README-1.8.6.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.8.6 += AspectJ 1.8.6 _© Copyright 2015 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.8.7.adoc b/docs/modules/release/pages/README-1.8.7.adoc index 5d4c0de6b..89879236d 100644 --- a/docs/modules/release/pages/README-1.8.7.adoc +++ b/docs/modules/release/pages/README-1.8.7.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.8.adoc b/docs/modules/release/pages/README-1.8.8.adoc index 12b59eeb9..ee86e797e 100644 --- a/docs/modules/release/pages/README-1.8.8.adoc +++ b/docs/modules/release/pages/README-1.8.8.adoc @@ -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 diff --git a/docs/modules/release/pages/README-1.8.9.adoc b/docs/modules/release/pages/README-1.8.9.adoc index f24bb1223..0074a28a5 100644 --- a/docs/modules/release/pages/README-1.8.9.adoc +++ b/docs/modules/release/pages/README-1.8.9.adoc @@ -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). diff --git a/docs/modules/release/pages/README-1.9.0.adoc b/docs/modules/release/pages/README-1.9.0.adoc index 06872691c..1bb02ea33 100644 --- a/docs/modules/release/pages/README-1.9.0.adoc +++ b/docs/modules/release/pages/README-1.9.0.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.0 += AspectJ 1.9.0 _© 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.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 +48,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 +75,14 @@ For example, here is an `iajc` usage with `compilerArg` that is passing .... -== 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 +91,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 +99,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 +133,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 +200,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 +242,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 +319,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 diff --git a/docs/modules/release/pages/README-1.9.1.adoc b/docs/modules/release/pages/README-1.9.1.adoc index e5aeac249..8ffdce948 100644 --- a/docs/modules/release/pages/README-1.9.1.adoc +++ b/docs/modules/release/pages/README-1.9.1.adoc @@ -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. diff --git a/docs/modules/release/pages/README-1.9.19.adoc b/docs/modules/release/pages/README-1.9.19.adoc index 07618a02c..563bf9d0d 100644 --- a/docs/modules/release/pages/README-1.9.19.adoc +++ b/docs/modules/release/pages/README-1.9.19.adoc @@ -1,8 +1,8 @@ -== AspectJ 1.9.19 += 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 +15,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 +30,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 +50,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 +62,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 +73,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 +81,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. diff --git a/docs/modules/release/pages/README-1.9.2.adoc b/docs/modules/release/pages/README-1.9.2.adoc index 94da278bf..a6e1fa550 100644 --- a/docs/modules/release/pages/README-1.9.2.adoc +++ b/docs/modules/release/pages/README-1.9.2.adoc @@ -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). diff --git a/docs/modules/release/pages/README-1.9.20.adoc b/docs/modules/release/pages/README-1.9.20.adoc index 51b9033e9..34ff738ea 100644 --- a/docs/modules/release/pages/README-1.9.20.adoc +++ b/docs/modules/release/pages/README-1.9.20.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.20.1 += AspectJ 1.9.20.1 _© Copyright 2023 Contributors. All rights reserved._ @@ -16,7 +16,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 +30,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 +45,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 +58,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 +74,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 +90,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 +98,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. diff --git a/docs/modules/release/pages/README-1.9.21.adoc b/docs/modules/release/pages/README-1.9.21.adoc index d205ed36d..66a38162e 100644 --- a/docs/modules/release/pages/README-1.9.21.adoc +++ b/docs/modules/release/pages/README-1.9.21.adoc @@ -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. diff --git a/docs/modules/release/pages/README-1.9.3.adoc b/docs/modules/release/pages/README-1.9.3.adoc index aa130dbc5..a242634a0 100644 --- a/docs/modules/release/pages/README-1.9.3.adoc +++ b/docs/modules/release/pages/README-1.9.3.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.3 += AspectJ 1.9.3 _© Copyright 2018 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.9.4.adoc b/docs/modules/release/pages/README-1.9.4.adoc index 72d6ca404..be667957d 100644 --- a/docs/modules/release/pages/README-1.9.4.adoc +++ b/docs/modules/release/pages/README-1.9.4.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.4 += AspectJ 1.9.4 _© Copyright 2019 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.9.5.adoc b/docs/modules/release/pages/README-1.9.5.adoc index 662c561bc..ddc0654a8 100644 --- a/docs/modules/release/pages/README-1.9.5.adoc +++ b/docs/modules/release/pages/README-1.9.5.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.5 += AspectJ 1.9.5 _© Copyright 2019 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.9.6.adoc b/docs/modules/release/pages/README-1.9.6.adoc index 0ecbc8967..3f22fbd3e 100644 --- a/docs/modules/release/pages/README-1.9.6.adoc +++ b/docs/modules/release/pages/README-1.9.6.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.6 += AspectJ 1.9.6 _© Copyright 2020 Contributors. All rights reserved._ diff --git a/docs/modules/release/pages/README-1.9.7.adoc b/docs/modules/release/pages/README-1.9.7.adoc index 1f96cd5bb..c58c78b5d 100644 --- a/docs/modules/release/pages/README-1.9.7.adoc +++ b/docs/modules/release/pages/README-1.9.7.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.7 += AspectJ 1.9.7 _© Copyright 2021 Contributors. All rights reserved._ @@ -17,7 +17,7 @@ for Bugzilla] and https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.7[here for GitHub issues]. -=== New features +== New features AspectJ 1.9.7 supports https://openjdk.java.net/projects/jdk/15/[Java 15] & https://openjdk.java.net/projects/jdk/16/[Java 16] and their @@ -50,7 +50,7 @@ respective AspectJ version in which the features were first supported * https://github.com/eclipse/org.aspectj/tree/master/tests/features197/java15[AspectJ 1.9.7: hidden classes, sealed classes] -=== Using LTW on Java 16+ +== Using 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 @@ -60,7 +60,7 @@ order to enable 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. -=== Organisational and internal changes +== Organisational and internal changes For AspectJ 1.9.7, we implemented a lot of internal changes concerning the build and release process, most of which are not visible in the @@ -86,7 +86,7 @@ enable users to re-test fixed bugs or try new features. This enables developers and contributors to make a choice if they want to work on Linux or on Windows. -=== Other changes and bug fixes +== Other changes and bug fixes * Remove legacy JRockit support. * Support Windows 10 and Windows Server 2016/2019 in installer. Those diff --git a/docs/modules/release/pages/README-1.9.8.adoc b/docs/modules/release/pages/README-1.9.8.adoc index 29b04ef7c..f42916a7b 100644 --- a/docs/modules/release/pages/README-1.9.8.adoc +++ b/docs/modules/release/pages/README-1.9.8.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.8 += AspectJ 1.9.8 _© Copyright 2022 Contributors. All rights reserved._ @@ -9,14 +9,14 @@ https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The list of is 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.8[here for Bugzilla] and https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.8[here for GitHub issues]. -=== New features +== New features AspectJ 1.9.8 supports https://openjdk.java.net/projects/jdk/17/[Java 17] and its final and review features, such as: * Sealed classes (final in Java 17, previews in Java 15, 16 and AspectJ 1.9.7) * Pattern matching for `switch` -=== Improvements +== Improvements The `--release N` compiler option for correct cross-compilation to previous JDK bytecode + API versions is now supported by AJC. Previously, the option existed (inherited by ECJ) but did not work correctly. @@ -32,7 +32,7 @@ feedback is positive and no negative side effects are found. Please try using th questions (to the AspectJ users mailing list) or problems (as a GitHub issue), if any. Thanks to Stefan Starke for his contribution. See also https://github.com/eclipse/org.aspectj/pull/37[PR #37]. -=== 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): @@ -42,7 +42,7 @@ first supported (possibly as JVM preview features): the JDK. Simply `-source 8 -target 8` would not be enough in this case. * https://github.com/eclipse/org.aspectj/tree/master/tests/features198/java17[Pattern matching for `switch`] -=== Other changes and bug fixes +== Other changes and bug fixes * 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 Core), @@ -65,9 +65,9 @@ first supported (possibly as JVM preview features): * Thanks to Andrey Turbanov for several clean code contributions and to Dmitry Mikhaylov for fixing a potential concurrency problem. -=== AspectJ usage hints +== AspectJ usage hints -==== 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 @@ -75,7 +75,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. diff --git a/docs/modules/release/pages/README-1.9.9.adoc b/docs/modules/release/pages/README-1.9.9.adoc index 900f70b89..2404b31f9 100644 --- a/docs/modules/release/pages/README-1.9.9.adoc +++ b/docs/modules/release/pages/README-1.9.9.adoc @@ -1,4 +1,4 @@ -== AspectJ 1.9.9.1 += AspectJ 1.9.9.1 _© Copyright 2022 Contributors. All rights reserved._ @@ -12,7 +12,7 @@ This probably was broken for a long time. AspectJ still is not boasting extensiv this improvement seems substantial enough to justify a minor release, instead of keeping users waiting for the next regular release. -== AspectJ 1.9.9 += AspectJ 1.9.9 _© Copyright 2022 Contributors. All rights reserved._ @@ -26,13 +26,13 @@ here: * https://github.com/eclipse/org.aspectj/issues?q=is%3Aissue+is%3Aclosed++milestone%3A1.9.9.1[GitHub 1.9.9.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.9[Bugzilla 1.9.9] -=== New features +== New features AspectJ 1.9.9 supports https://openjdk.java.net/projects/jdk/18/[Java 18] and its final and preview features, such as: * Pattern matching for `switch` (preview 2) -=== Improvements +== Improvements In annotation style aspects, asynchronous `proceed()` calls in `@Around` advice now works in threads created from within the advice. Previously, this was only working in native syntax aspects. There is still a limitation with regard to @@ -42,7 +42,7 @@ own thread pool. This still is not working in annotation style aspects, only in See https://github.com/eclipse/org.aspectj/issues/128[issue #128] and https://github.com/eclipse/org.aspectj/pull/132[pull request #132] 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): @@ -52,7 +52,7 @@ first supported (possibly as JVM preview features): * https://github.com/eclipse/org.aspectj/tree/master/tests/bugs199/github_128[Asynchronous proceed in native vs. annotation style syntax] -=== Other changes and bug fixes +== Other changes and bug fixes * Fix a bug which led to ``NullPointerException``s, if too many JAR archives were on the classpath. Too many here means the value of system property `org.aspectj.weaver.openarchives` (1,000 by default). The AspectJ compiler is meant to @@ -64,9 +64,9 @@ first supported (possibly as JVM preview features): https://github.com/eclipse/org.aspectj/issues/122[#122]. * 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 @@ -75,7 +75,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 @@ -83,7 +83,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. diff --git a/docs/modules/release/pages/changes.adoc b/docs/modules/release/pages/changes.adoc index 5b08e48ae..9bfcc9cd7 100644 --- a/docs/modules/release/pages/changes.adoc +++ b/docs/modules/release/pages/changes.adoc @@ -1,4 +1,4 @@ -== Changes in AspectJ += Changes in AspectJ _© Copyright 1998-2002 Palo Alto Research Center Incorporated 2003-2008 Contributors. All rights reserved._ @@ -33,7 +33,7 @@ _© Copyright 1998-2002 Palo Alto Research Center Incorporated ''''' [[_1_6_0]] -== 1.6.0 += 1.6.0 This release rebases AspectJ on the Eclipse Compiler version 785_R33X - making it Java6 compliant. @@ -42,7 +42,7 @@ A full list of bugs fixed and enhancements implemented can be found in https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.0+M1&target_milestone=1.6.0+M2&target_milestone=1.6.0+RC1&target_milestone=1.6.0&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=[Bugzilla]. [[_1_5_4]] -== 1.5.4 += 1.5.4 This release contains around 40 bug fixes and enhancements since the 1.5.3 release. @@ -52,7 +52,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ& Bugzilla [[_1_5_3]] -== 1.5.3 += 1.5.3 This release contains around 80 bug fixes and enhancements since the 1.5.2 release. @@ -62,7 +62,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ& Bugzilla [[_1_5_2]] -== 1.5.2 += 1.5.2 This release contains around 60 bug fixes and enhancements since the 1.5.1 release. @@ -72,7 +72,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ& Bugzilla [[_1_5_1]] -== 1.5.1 += 1.5.1 This release contains over 70 bug fixes and enhancements since the 1.5.0 release. @@ -82,7 +82,7 @@ https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ& Bugzilla [[_1_5_0]] -== 1.5.0 += 1.5.0 This release contains nearly 400 bug fixes and enhancements since the 1.2.1 release. Major updates to the language are documented in the @@ -94,7 +94,7 @@ A full list of bugs fixed in AspectJ 5 can be found in https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&product=AspectJ&resolution=FIXED&chfieldfrom=2004-11-06&chfieldto=2005-12-20[bugzilla]. [[_1_2_1]] -== 1.2.1 += 1.2.1 All known P1 and P2 bugs have been fixed in this release. The https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.2.1&bug_status=RESOLVED&resolution=FIXED[full @@ -214,7 +214,7 @@ subset of aspectjtools.jar needed for weaving. The "aj" script is also moved into the bin directory. [[_1_2]] -== 1.2 += 1.2 All known P1 and P2 bugs have been fixed in this release. The https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.2[full @@ -341,7 +341,7 @@ local storage used to manage cflow stacks when available - improves cflow performance when working with a multi-threaded application. [[_1_1_1]] -== 1.1.1 += 1.1.1 All known P1 and P2 bugs have been fixed in this release. The https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.1.1[full @@ -398,12 +398,12 @@ ajc to compile JSP's in Tomcat. Thanks to Ron Bodkin for investigating how to integrate ajc with Tomcat. [[_1_0_6]] -== 1.0.6 += 1.0.6 This release contains mainly bug fixes for ajde and ajdoc. [[_1_0_6compiler]] -=== Compiler +== Compiler We fixed a bug with switch statements, thanks largely to Jason Rimmer's diligence in helping us isolate the problem. Also, to help Log4J parse @@ -411,7 +411,7 @@ stack traces, we changed class file symbolic line references to use [] instead of () for the virtual start lines of each file. [[_1_0_6ajde]] -=== AJDE +== AJDE *AJDE Framework, AJBrowser, and AJDE for Forte/NetBeans* @@ -420,7 +420,7 @@ reduce footprint when working with large systems. Error tolerance has also been improved for dealing with a structure model that is out of synch with resources on disk. -==== AJDE for JBuilder +=== AJDE for JBuilder JBuilder 7 is now supported. All known bugs have been fixed including: @@ -442,7 +442,7 @@ JBuilder OpenTools with AJDE/JBuilder, the OpenTool is now being built with itself. [[_1_0_6ajdoc]] -=== Ajdoc +== Ajdoc * Fixed http://aspectj.org/bugs/resolved?id=790[790] aspect code comments suppressed by fix to bug 710 @@ -451,7 +451,7 @@ comments suppressed by fix to bug 710 ''''' [[_1_0_5]] -== 1.0.5 += 1.0.5 This release includes significant improvements to AspectJ Development Environment (AJDE) support. The entire user interface has been revised @@ -466,7 +466,7 @@ tool. * xref:#_1_0_5anttasks[Ant tasks] [[_1_0_5compiler]] -=== Compiler +== Compiler This was another compiler release primarily concerned with fixing corner cases in the language implementation. Our handling of nested classes, @@ -475,9 +475,9 @@ Thanks to Nicholas Alex Leidenfrost and Patrick Chan for their clear and concise bug reports on some of these issues. [[_1_0_5ajde]] -=== AJDE +== AJDE -==== This release includes significant improvements to AspectJ Development Environment (AJDE) support. All known bugs have been fixed, and the core framework quality has been significantly increased thanks to the adoption of a unit test suite. The following changes apply to all of the AJDE NetBeans/Forte, JBuilder, and the AspectJ Browser support. NetBeans/Forte and JBuilder-specific changes are listed below. +=== This release includes significant improvements to AspectJ Development Environment (AJDE) support. All known bugs have been fixed, and the core framework quality has been significantly increased thanks to the adoption of a unit test suite. The following changes apply to all of the AJDE NetBeans/Forte, JBuilder, and the AspectJ Browser support. NetBeans/Forte and JBuilder-specific changes are listed below. * The entire user interface has been revised and streamlined. * The structure view and browser have a new UI, and offer both a @@ -491,7 +491,7 @@ crosscutting structure. * Error messages have been improved, and the structure views include annotations of nodes with errors and warnings. -==== AJDE for JBuilder +=== AJDE for JBuilder Integration into the JBuilder IDE is more streamlined. In addition: @@ -514,7 +514,7 @@ double-clicking ".lst" files that have been added to the project. * Error messages now match JBuilder's look-and-feel and behavior. Seeking to column numbers now works in addition to line numbers. -==== AJDE for Forte/NetBeans +=== AJDE for Forte/NetBeans Integration into the NetBeans IDE is more streamlined. In addition: @@ -529,7 +529,7 @@ configuration. * Class files are generated beside source files (NetBeans/javac default). There is currently no way to specify a target directory. -==== AJBrowser +=== AJBrowser * The browser now supports main class execution. Set the main class in the options dialog, and make sure that both the Java executable is on @@ -537,7 +537,7 @@ your path, and the class that you expect to execute on your classpath. * The error messages UI has been improved. [[_1_0_5ajdoc]] -=== Ajdoc +== Ajdoc Bug fixes: @@ -552,7 +552,7 @@ docs for methods or constructors declared on other types.] resource] [[_1_0_5anttasks]] -=== Ant tasks +== Ant tasks Bug fixes: @@ -562,7 +562,7 @@ ajc flags] ''''' [[_1_0_4]] -== 1.0.4 += 1.0.4 * xref:#_1_0_4compiler[Compiler] * xref:#_1_0_4ajde[AJDE] @@ -571,7 +571,7 @@ ajc flags] * xref:#_1_0_4doc[Documentation] [[_1_0_4compiler]] -=== Compiler +== Compiler * Over a dozen people independently reported a bug in error handling for the wrong number number of arguments to `proceed`. This has been turned @@ -587,7 +587,7 @@ language spec. Language Spec have been fixed in this release. Thanks to Neal Gafter for reporting many of these. -==== Incompatible changes +=== Incompatible changes Two potentially surprising incompatible changes have been made to ajc in order to bring the compiler into compliance with the 1.0 language @@ -609,19 +609,19 @@ of these changes can be found in the xref:porting.adoc#pre-1_0_4[porting notes]. [[_1_0_4ajde]] -=== AJDE +== AJDE This is the first release of AJDE support with significant external contribution. A big thanks goes out to Phil Sager for porting the AJDE for Forte/NetBeans support to NetBeans 3.3.1 and improving the integration into NetBeans. -==== AJDE for JBuilder +=== AJDE for JBuilder * Updates ** This is a bug fix release only. -==== AJDE for Forte/NetBeans +=== AJDE for Forte/NetBeans * Updates ** NetBeans 3.3.1 is now supported in addition to NetBeans 3.2 and Forte @@ -638,18 +638,18 @@ Explorer, right-click the class and select "Execute". source code. The "AspectJ" Explorer understands the structure of AspectJ projects and should be used for navigating structure instead. -==== AJDE for Emacs +=== AJDE for Emacs * This is a bug fix release only. [[_1_0_4ajdoc]] -=== Ajdoc +== Ajdoc Ajdoc now runs under J2SE 1.4, but still requires the tools.jar from J2SE 1.3 be on the classpath. [[_1_0_4taskdefs]] -=== Ant tasks +== Ant tasks * Repackaged to fit into the AspectJ product directory - e.g., `aspectj-ant.jar` moved to `lib` as expected by `examples/build.xml`. @@ -657,7 +657,7 @@ J2SE 1.3 be on the classpath. BuildException if failonerror and ajdoc detects misconfiguration. [[_1_0_4doc]] -=== Documentation +== Documentation Added a 1-page quick reference guide. Improved javadoc documentation for the org.aspectj.lang package. @@ -665,13 +665,13 @@ the org.aspectj.lang package. ''''' [[_1_0_3]] -== 1.0.3 += 1.0.3 * xref:#_1_0_3compiler[Compiler] * xref:#_1_0_3taskdefs[Ant taskdefs] [[_1_0_3compiler]] -=== Compiler +== Compiler This release fixes a single significant bug in 1.0.2 where ajc could generate unreachable code in `-usejavac` or `-preprocess` mode. This @@ -681,7 +681,7 @@ flow-analysis for this case and generate code that is acceptable to javac. Thanks to Rich Price for reporting this bug. [[_1_0_3taskdefs]] -=== Ant taskdefs +== Ant taskdefs Added support to the Ajc taskdef for the -source 1.4 and -X options generally. @@ -689,7 +689,7 @@ generally. ''''' [[_1_0_2]] -== 1.0.2 += 1.0.2 This release is mainly about keeping up with the Joneses. To keep up with SUN's release candidate for J2SE1.4, we now officially support the @@ -705,7 +705,7 @@ reported in 1.0.1. * xref:#_1_0_2ajdb[AJDB] [[_1_0_2compiler]] -=== Compiler +== Compiler * Official support for `-source 1.4` option to compile new http://java.sun.com/j2se/1.4/docs/guide/lang/assert.html[1.4 @@ -748,7 +748,7 @@ javac]. using the latest `aspectjrt.jar` [[_1_0_2ajde]] -=== AJDE +== AJDE This is a bug fix release only. @@ -760,7 +760,7 @@ view) have been fixed. * Other GUI and usability improvements have been made the AspectJ Browser and core framework. -==== AJDE for JBuilder +=== AJDE for JBuilder * Support has been extended to JBuilder 6, and support for Enterprise version features has been improved. @@ -768,12 +768,12 @@ version features has been improved. not be updated after a recompile. * Keyboard shortcuts were fixed to work with Mac OSX. -==== AJDE for Forte +=== AJDE for Forte * Keyboard shortcuts were fixed to work with Mac OSX. [[_1_0_2ajdb]] -==== AJDB +=== AJDB Some minor bug fixes, but this is still early-access software. Please try using another JPDA-compliant debugger. If it uses JDI correctly, @@ -784,14 +784,14 @@ would appreciate any reports of success or failure. ''''' [[_1_0_1]] -== 1.0.1 += 1.0.1 * xref:#_1_0_1compiler[Compiler] * xref:#_1_0_1ajde[AJDE] * xref:#_1_0_1ajdb[AJDB] [[_1_0_1compiler]] -=== Compiler +== Compiler This release fixes a significant performance issue in the compiler, reported by Rich Price, that could lead to extremely long compiles in @@ -809,7 +809,7 @@ expected that this prefix will either become the default compiler behavior in the future or a non-experimental flag will replace it. [[_1_0_1ajde]] -=== AJDE +== AJDE Minor bug fixes, including: AJDE for JBuilder failed to preserve application parameters from project settings when executing the @@ -818,7 +818,7 @@ application. Source builds were cleaned up for JBuilder and Forte sources. [[_1_0_1ajdb]] -=== AJDB +== AJDB Two bugs were reported and have been fixed in this release. (Note that ajdb is still considered early-access software.) @@ -827,7 +827,7 @@ ajdb is still considered early-access software.) * bug 617: -X and -D options not passed to debug VM correctly [[_1_0_0]] -== 1.0.0 += 1.0.0 * xref:#_1_0_0language[Language] * xref:#_1_0_0compiler[Compiler] @@ -836,12 +836,12 @@ ajdb is still considered early-access software.) * xref:#_1_0_0taskdefs[Ant taskdefs] [[_1_0_0language]] -== Language += Language There were no language changes for this release. [[_1_0_0compiler]] -== Compiler += Compiler Several minor bugs primarily in error handling were reported and have been fixed in this release. The two most serious bugs are described @@ -861,37 +861,37 @@ class overrode introduced methods on an interface implemented by that class. This is now fixed. [[_1_0_0ajde]] -== AJDE += AJDE Numerous user interface refinements were made to the browser and core AJDE functionality. Error handling and reporting has been improved. All of the AJDE tools now support the ".aj" file extension. -=== AJDE for JBuilder +== AJDE for JBuilder * The AspectJ Browser now uses JBuilder's icons and distinguishes nodes by visibility. * Project-setting VM parameters are now supported by the "AJDE Run" button. -=== AJDE for Forte +== AJDE for Forte * The AspectJ Browser now uses Forte's icons and distinguishes nodes by visibility -=== AJBrowser +== AJBrowser * Documentation for the browser is now available at http://aspectj.org/docs -=== Emacs Support: aspectj-mode and AJDEE +== Emacs Support: aspectj-mode and AJDEE * Improved updating of annotations during editing. * Pop-up jump menu now placed (with mouse pointer) near cursor. * [AJDEE only] Improved filtering of legal code completions. [[_1_0_0ajdoc]] -=== AJDoc +== AJDoc * Runs only in J2SE 1.3 - not 1.2 or 1.4. You can document 1.x-reliant programs by using the options to compile using 1.x libraries. @@ -899,15 +899,15 @@ programs by using the options to compile using 1.x libraries. the syntax message. [[_1_0_0taskdefs]] -=== Ant taskdefs +== Ant taskdefs * Fork is not supported in the AJDoc taskdef [[_1_0rc3]] -== 1.0rc3 += 1.0rc3 [[_1_0rc3language]] -== Language += Language There have been several minor clarifications/changes to the language. @@ -921,7 +921,7 @@ to this language feature. http://aspectj.org/pipermail/users/2001/001258.html[More details...] [[_1_0rc3compiler]] -== Compiler += Compiler This release saw several changes to the compiler in order to work-around known bugs in different JVMs, or to otherwise mimic the behavior of @@ -960,7 +960,7 @@ the jikes group, and had added the feature days before getting our first bug report for it not being there. [[_1_0rc3ajde]] -== AJDE += AJDE * The structure view has been improved. * Multiple user-configurable views are supported. @@ -974,7 +974,7 @@ current file or the project root. associations are now navigable. * A depth slider for controlling tree-expansion has been added. -=== AJDE for JBuilder +== AJDE for JBuilder * Changes: * Inline annotations support have been improved and made consistent with @@ -983,27 +983,27 @@ structure). * The current structure view persists across IDE launches. * An enabled AJDE no longer slows down JBuilder shutdown. -=== AJDE for Forte +== AJDE for Forte * Execution remembers main class. * The bug causing an error during a "Mode" and "Explorer" switch has been fixed. -=== AJBrowser +== AJBrowser * AJBrowser is currently an undocumented demonstration application. To use it type: ajbrowser ... * Multiple source locations can be shown by selecting multiple nodes and right-clicking to select the "Display Sources" command. -=== Emacs Support: aspectj-mode and AJDEE +== Emacs Support: aspectj-mode and AJDEE * Numerous jump-menu improvements, including operation of pop-ups. * For AJDEE, compatibility with JDEE 2.2.9beta4. Also, fixes in completion, ajdoc launch, and speedbar. [[_1_0rc3ajdoc]] -=== AJDoc +== AJDoc Some of the more obvious NullPointerException bugs in Ajdoc were fixed, but Ajdoc does not implement all the functionality of Javadoc and has @@ -1024,7 +1024,7 @@ Further, Ajdoc has not been testing on variants of the J2SE (it uses javadoc classes). [[_1_0rc3taskdefs]] -=== Ant taskdefs +== Ant taskdefs The Ajc taskdef was updated to support the new compiler options and the .aj extension, and some NullPointerException bugs were fixed (thanks to @@ -1036,30 +1036,30 @@ $\{ant.home}/lib. ''''' [[_1_0rc2]] -== 1.0rc2 += 1.0rc2 * xref:#_1_0rc2language[Language] * xref:#_1_0rc2compiler[Compiler] * xref:#_1_0rc2ajde[AJDE] [[_1_0rc2language]] -== Language += Language There are no language changes in this release. This is a bug fix release only. [[_1_0rc2compiler]] -== Compiler += Compiler A bug in handling inner type names that conflict with enclosing type names was fixed. Many error messages were improved. [[_1_0rc2ajde]] -== AJDE += AJDE * This is a bug fix release only. -=== AJDE for JBuilder +== AJDE for JBuilder * Changes: ** Fixed bug causing the output path to be ignored and .class files to @@ -1077,7 +1077,7 @@ placed in the project's "Working directory". ** The debugger has not seen much use and it's stability and performance is limited. -=== AJDE for Forte +== AJDE for Forte * Changes: ** Moved the "AspectJ" menu into the "Tools" menu in order to make it @@ -1091,7 +1091,7 @@ Switching to a different tab in the ProjectExplorer has the same effect. ** The debugger has not seen much use and it's stability and performance is limited. -=== AJBrowser +== AJBrowser * Changes: ** ... @@ -1104,7 +1104,7 @@ use it type: ajbrowser ... .... -=== Emacs Support: aspectj-mode and AJDEE +== Emacs Support: aspectj-mode and AJDEE This release now properly displays annotations for call sites and introductions. Robustness has been improved in several dimensions, @@ -1114,14 +1114,14 @@ properly when changing directories. ''''' [[_1_0rc1]] -== 1.0rc1 += 1.0rc1 * xref:#_1_0rc1language[Language] * xref:#_1_0rc1compiler[Compiler] * xref:#_1_0rc1ajde[AJDE] [[_1_0rc1language]] -== Language += Language Some of the details of the specification for perthis and pertarget have changed. These changes make these language constructs implementable on @@ -1138,7 +1138,7 @@ now we've chosen to leave the most room to design them right in a future release. [[_1_0rc1compiler]] -== Compiler += Compiler ajc now directly generates .class files without using javac as a back-end. This should result in improved compiler performance, better @@ -1157,7 +1157,7 @@ release of ajc will run under SUN's jdk1.4beta2. However, we still strongly recommend that most users use the non-beta jdk1.3. [[_1_0rc1ajde]] -== AJDE += AJDE * The structure view can now be configured (using the "Options" dialog) to display different kinds of associations between program elements that @@ -1166,7 +1166,7 @@ appear in the tree. * When navigating links the structure view will stay synchronized with the editor. -=== AJDE for JBuilder +== AJDE for JBuilder * Changes: ** Inline structural navigation annotations appear in the gutter of the @@ -1177,7 +1177,7 @@ introduction. ** The debugger has not seen much use and it's stability and performance is limited. -=== AJDE for Forte +== AJDE for Forte * Changes: ** Support for Forte 3 and Netbeans 3.2 has been added. @@ -1191,7 +1191,7 @@ Switching to a different tab in the ProjectExplorer has the same effect. ** The debugger has not seen much use and it's stability and performance is limited. -=== AJBrowser +== AJBrowser * Changes: ** Build configuration file editor added. @@ -1204,7 +1204,7 @@ use it type: ajbrowser ... .... -=== Aspectj-mode and AJDEE: AspectJ support in Emacs +== Aspectj-mode and AJDEE: AspectJ support in Emacs This release of AspectJ support for Emacs includes corrections to the documentation and the appearance of annotations and jumps in the editing @@ -1215,7 +1215,7 @@ computational overhead. ''''' [[_1_0beta1]] -== 1.0beta1 += 1.0beta1 * xref:#_1_0beta1language[Language] * xref:#_1_0beta1compiler[Compiler] @@ -1223,7 +1223,7 @@ computational overhead. * xref:#_1_0beta1ajde[AJDE] [[_1_0beta1language]] -== Language += Language There is one language change since 1.0alpha1. The static modifier is no longer needed or allowed on pointcut declarations. Name binding for @@ -1237,7 +1237,7 @@ changes in the next release to address issues of implementability on the JVM as well as related issues. [[_1_0beta1compiler]] -== Compiler += Compiler The ajc compiler should now catch all errors in source code and you should no longer see errors coming from files in 'ajworkingdir'. Please @@ -1250,7 +1250,7 @@ very thorough bug report on this broken feature days after the 1.0alpha1 release. [[_1_0beta1ajbrowser]] -== AJBrowser += AJBrowser * Support for executing classes has been added. * .lst can now be passed as arguments on the command line. @@ -1260,7 +1260,7 @@ release. that the browser is launched with. [[_1_0beta1ajde]] -== AJDE += AJDE * The performance and UI of the structure tree has been improved. * Compilation now runs in a separate thread and a progress monitor is @@ -1273,7 +1273,7 @@ the console that the IDE was launched from. No more errors should be passed to javac, so please report this behavior and the corresponding error message as a bug. -=== AJDE for JBuilder +== AJDE for JBuilder * Known bugs have been fixed. * Classpath separator character is no longer hardcoded. @@ -1283,7 +1283,7 @@ have been added. ** The debugger has not seen much use and it's stability and performance is limited. -=== AJDE for Forte +== AJDE for Forte * Known bugs have been fixed. * Limitations: @@ -1294,7 +1294,7 @@ to be restarted for the AspectJ window to show again. ** The debugger has not seen much use and it's stability and performance is limited. -=== Aspectj-mode and AJDEE: AspectJ support in Emacs +== Aspectj-mode and AJDEE: AspectJ support in Emacs AspectJ Development Environment for Emacs has been split into two pieces, aspectj-mode (an extension of java-mode), and AJDEE (an @@ -1305,7 +1305,7 @@ beanshell is no longer required for use of these modes. ''''' [[_1_0alpha1]] -== 1.0alpha1 += 1.0alpha1 This is the first alpha release of the 1.0 language and tools. There have been many changes in the language, and many improvements to the @@ -1321,7 +1321,7 @@ volatility of AspectJ in the push to 1.0. * xref:#_1_0alpha1ajde[AJDE] [[_1_0alpha1language]] -=== Language +== Language There have been many changes to make the 1.0 language both simpler and more powerful. User feedback has driven most of these design changes. @@ -1341,7 +1341,7 @@ pointcuts, more flexible dominates, and many other improvements). Note that entries into the xref:porting.adoc[porting notes] for this release are linked from the various language changes. -==== Pointcuts +=== Pointcuts Perhaps the least interesting -- but most pervasive -- change is that the names of the single-kinded pointcut designators (the ones that pick @@ -1411,7 +1411,7 @@ Non-abstract pointcuts may now be declared `final`. We have finally added an extremely general pointcut, `if(BooleanExpression)`, that picks out join points programatically. -==== Type patterns +=== Type patterns Our treatment of xref:porting.adoc#_1_0a1-new-wildcards[* and ..] in type patterns is cleaner. @@ -1421,7 +1421,7 @@ a new wildcard, +, to pick out all subtypes of a given type. Previously, the subtypes operator was only allowed in introduction, and was xref:porting.adoc#_1_0a1-subtypes-to-plus[spelled differently]. -==== Advice +=== Advice Around advice is treated much more like a method, with a xref:porting.adoc#_1_0a1-around-returns[return value] and an optional @@ -1442,7 +1442,7 @@ xref:porting.adoc#_1_0a1-this-static-join-point[renamed], and the `thisJoinPoint` object hierarchy has been xref:porting.adoc#_1_0a1-this-join-point[simplified]. -==== Introduction and static crosscutting +=== Introduction and static crosscutting On the static side of the language, introduction hasn't changed, but there is now a new keyword, `declare`, that is used to declare various @@ -1462,7 +1462,7 @@ checked exceptions into an unchecked form. This may affect some uses of xref:porting.adoc#_1_0a1-now-use-soft[around advice] that previously mucked with the exception checking system. -==== Aspects +=== Aspects The "of each" modifiers have been xref:porting.adoc#_1_0a1-aspects[renamed]. Apart from the spelling, the @@ -1476,7 +1476,7 @@ dominate the advice of another aspect B as well as its subtypes, with the new + subtypes operator: `aspect A dominates B+`. [[_1_0alpha1compiler]] -=== Compiler +== Compiler The most important change in the compiler is that it supports the new language. In addition, all reported bugs in the last release have been @@ -1487,7 +1487,7 @@ handling source files that are not in standard US-ASCII format. Thanks to Nakamura Tadashi for both suggesting this feature and for submitting a nice patch to implement it. -==== Known Limitations +=== Known Limitations The previous compiler's limitations regarding join points that occurred in anonymous classes have all been eliminated. Unfortunately, @@ -1500,7 +1500,7 @@ Moreover, some errors regarding the initialization of final fields might never show up when using ajc. This will be fixed shortly. [[_1_0alpha1documentation]] -=== Documentation +== Documentation Although we spent much of our time this release cycle updating the documentation to the new language rather than improving its content, we @@ -1511,7 +1511,7 @@ printable versions of both guides (in PDF) are finally included in the documentation package. [[_1_0alpha1ajdoc]] -=== Ajdoc +== Ajdoc Ajdoc was rewritten to conform with the language changes and provide support for other AspectJ/Java compilers. Our doclet is used by default @@ -1520,29 +1520,29 @@ used by passing the '-standard' flag to Ajdoc to produce regular Javadoc documentation (excluding AspectJ-specifics). [[_1_0alpha1ant]] -=== Ant +== Ant An Ajdoc task is now available. The Ajc ant task was improved to be completely back-compatible with the Javac task. [[_1_0alpha1ajbrowser]] -=== AJBrowser +== AJBrowser The "AspectJ Browser" is a new standalone source code browsing application. It will let you compile ".lst" files, view the structure for those files and navigate the corresponding source code. [[_1_0alpha1ajde]] -=== AJDE +== AJDE -==== AJDE for JBuilder +=== AJDE for JBuilder -===== Installation +==== Installation * Use the installer to place the "ajdeForJBuilder.jar" and "aspectjrt.jar" in to JBuilder's lib/ext directory. -===== Key Improvements +==== Key Improvements * The "AspectJ Structure View" replaces JBuilder's structure view instead of being launched in a separate window. @@ -1552,7 +1552,7 @@ removed. * Projects no longer require the manual adding of the "aspectjrt.jar" libarary. -===== Known Bugs & Limitations +==== Known Bugs & Limitations * There is no compiler progress dialog--the way to tell if the compile is finished is to watch the "status" area of the main window. @@ -1564,9 +1564,9 @@ is limited. * There is no ajdoc tool support. * Linux testing has been very limited. -==== AJDE for Forte +=== AJDE for Forte -===== Installation +==== Installation * Use the installer to place the "ajdeForForte.jar" in Forte's modules directory and "aspectjrt.jar" in to Forte's lib/ext directory. @@ -1575,7 +1575,7 @@ directory and "aspectjrt.jar" in to Forte's lib/ext directory. * Find the ajdeForForte.jar in the directory that you installed into (e.g. c:\forte4j\modules) and select it. -===== Key Improvements +==== Key Improvements * AJDE can be toggled on/off with the "AJ" button--when it is turned off all of the menus, resources, and event listeners that it uses will be @@ -1583,7 +1583,7 @@ removed. * The AJDE functionality is now contained within it's own toolbar and menu. -===== Known Bugs & Limitations +==== Known Bugs & Limitations * "Mode" switching is not supported in this version--you must do all of your AspectJ work in the "Editing" mode. If you switch modes the IDE has @@ -1598,7 +1598,7 @@ is limited. * There is no ajdoc tool support. * Linux testing has been very limited. -==== AJDE for Emacs +=== AJDE for Emacs AspectJ-mode now includes a toggle in the AspectJ menu that disables its intrusive functions, enabling easy switching between Java and AspectJ diff --git a/docs/modules/release/pages/porting.adoc b/docs/modules/release/pages/porting.adoc index 31f3016ae..a78b7f2a2 100644 --- a/docs/modules/release/pages/porting.adoc +++ b/docs/modules/release/pages/porting.adoc @@ -1,4 +1,4 @@ -== AspectJ Porting Notes += AspectJ Porting Notes _© Copyright 1998-2002 Palo Alto Research Center Incorporated, 2003-2004 Contributors. All rights reserved._ @@ -15,7 +15,7 @@ _© Copyright 1998-2002 Palo Alto Research Center Incorporated, * xref:#pre07b10[Pre-0.7beta10 code] [[pre-1_2]] -=== Porting pre-1.2 code to AspectJ 1.2 +== Porting pre-1.2 code to AspectJ 1.2 README-1.2.html contains a discussion of the changes between 1.1 and 1.2. The key points are: @@ -190,7 +190,7 @@ https://bugs.eclipse.org/bugs/show_bug.cgi?id=60389[60389], https://bugs.eclipse.org/bugs/show_bug.cgi?id=59921[59921]. [[pre-1_1]] -=== Porting pre-1.1 code to AspectJ 1.1 +== Porting pre-1.1 code to AspectJ 1.1 README-1.1.html contains a discussion of the language changes from 1.0 to 1.1. The high points: @@ -265,7 +265,7 @@ because the end of exception handlers is ambiguous in bytecode. Try to use before advice. (xref:README-1.1.adoc#AFTER_HANDLER[more info]) [[pre-1_0_4]] -=== Porting pre-1.0.4 code +== Porting pre-1.0.4 code In versions of AspectJ prior to 1.0.4, the compiler was not correctly implementing the AspectJ-1.0 language design for some uses of after @@ -321,7 +321,7 @@ Uses of both of these forms are highleted with compiler warnings in the ''''' [[pre-1_0rc1]] -=== Porting pre-1.0rc1 code +== Porting pre-1.0rc1 code Aspects can no longer be declared to implement the `Serializable` or `Cloneable` interfaces. If you previously used serializable or cloneable @@ -331,7 +331,7 @@ serialize or clone in objects associated with the aspects. ''''' [[pre-1_0beta1]] -=== Porting pre-1.0beta1 code +== Porting pre-1.0beta1 code The `static` modifier is no longer allowed on pointcut declarations anywhere. Porting is simple; just remove the static declarations when @@ -345,7 +345,7 @@ now. If you used this feature, now is the right time to remove the ''''' [[pre-1_0alpha1]] -=== Porting pre-1.0alpha1 code +== Porting pre-1.0alpha1 code The release of AspectJ 1.0alpha1 involved sweeping cleanups of the language to bring it to 1.0 status. @@ -358,10 +358,10 @@ crosscutting] * xref:#_1_0a1-aspects[Aspects] [[_1_0a1-pointcuts]] -==== Pointcuts +=== Pointcuts [[_1_0a1-plural-to-singular]] -===== Removing the "s" from pointcuts +==== Removing the "s" from pointcuts One of the most pervasive changes in porting code written before 1.0alpha1 is the change in some of the pointcut names from plural to @@ -401,7 +401,7 @@ Of course, your naming conventions are your own, but throughout these porting notes we will be making these changes in our example ports. [[_1_0a1-remove-receptions]] -===== Removing the receptions pointcut +==== Removing the receptions pointcut Perhaps the largest semantic change in the 1.0 language is the removal of receptions join points. They have been merged with call join points @@ -411,7 +411,7 @@ in AspectJ 1.0, so now a call join point doesn't represent the Changing code that used the `receptions` pointcut should be fairly straightforward, depending on whether the pointcut exposed state or not. -====== Not exposing state +===== Not exposing state Receptions pointcuts that did not expose state can simply be replaced by the new `call` and `target` pointcuts: @@ -423,7 +423,7 @@ receptions(void Foo.m()) target(Foo) && call(void m()) .... -====== Exposing state +===== Exposing state Some receptions pointcuts exposed the receiving object by replacing the receiving type with a pointcut formal. These PCDs should be rewritten to @@ -448,7 +448,7 @@ pointcut intPasser(int i, int j): args(i, j) && target(Foo) && call(void m(int, int)); .... -====== Constructor receptions +===== Constructor receptions There are two issues with constructor receptions in particular. @@ -499,7 +499,7 @@ after() returning (Point p): call(Point+.new(int, int)) { ... } .... [[_1_0a1-fixing-state-access]] -===== Fixing state access +==== Fixing state access In previous versions of AspectJ, state such as the currently executing object or a particular argument of a method call could be accessed from @@ -508,7 +508,7 @@ AspectJ 1.0, all state accesses now use only three pointcuts `args, this, target which pick out argument values, the currently executing object, and the target object of a method call or field operation, respectively. -====== Using args +===== Using args Any time you have a pointcut that has a signature where one of the arguments was a pointcut or advice formal, just replace that formal with @@ -528,7 +528,7 @@ pointcut stringPassers(String s): receptions(void Foo.m(s, ..)); pointcut stringPasser(String s): args(s, ..) && call(void Foo.m(String, ..)); .... -====== Rewriting calls +===== Rewriting calls If a calls pointcut exposed the the receiving object, such as @@ -559,7 +559,7 @@ after(Point p) returning (): calls(p.new(int, int)) { ... } after() returning (Point p): call(Point+.new(int, int)) { ... } .... -====== Rewriting gets and sets +===== Rewriting gets and sets Exposing the target object of a `gets` or `sets` pointcut should be done the same way it was for `calls` pointcuts, with the new `target` @@ -640,7 +640,7 @@ after(Color newColor): args(newColor) && set(Color Frame.color) { ... } Also, if the field was declared private, in order to get at its old value the aspect must be declared `privileged`. -====== Rewriting handlers +===== Rewriting handlers The value of the exception at an exception handler join point is now accessed through the `args` pointcut; all exception handler join points @@ -653,7 +653,7 @@ before(NotFoundException e): handlers(e) { ... } before(NotFoundException e): args(e) && handler(NotFoundException) { ... } .... -====== Rewriting within +===== Rewriting within The `within` pointcut was not typically used to export context. Though it was accidentally possible to do so in versions of AspectJ before 1.0, @@ -670,7 +670,7 @@ pointcut usesFoo(Foo f): this(f) && within(Foo); .... [[_1_0a1-no-subs-in-sigs]] -===== Understanding signatures +==== Understanding signatures Now that we have `this`, `target`, and `args` pointcuts, all of our signatures are composed of just types, names, and wildcards; there are @@ -707,7 +707,7 @@ call(void m(Object+)) .... [[_1_0a1-fixing-instanceof]] -===== Removing the instanceof pointcut +==== Removing the instanceof pointcut The intanceof pointcut has been split into two different pointcuts, `this` and `target`. @@ -746,7 +746,7 @@ pointcut setup(Client c): this(c) && calls(Remote Naming.lookup(String)); .... [[_1_0a1-initializations]] -===== Rewriting the initializations pointcut +==== Rewriting the initializations pointcut Object initialization join points are now more complicated, and more true to Java's execution model. Now they bracket all of the @@ -766,7 +766,7 @@ initialization(A.new(..)) && !execution(A.new(..)) .... [[_1_0a1-constructor-calls]] -===== Understanding constructor calls +==== Understanding constructor calls Previously, constructor call join points were matched by subtypes, so `calls(Foo.new())` would match both calls to create new `Foo` objects, @@ -782,7 +782,7 @@ In both of these cases, think before using the + operator; it may be that you didn't intend subtype matching in the first place. [[_1_0a1-hasaspect]] -===== Removing the hasaspect pointcut +==== Removing the hasaspect pointcut The `hasaspect` pointcut is no longer defined, but you can get the same behaviour using the new `if` pointcut. @@ -828,7 +828,7 @@ before(): if(A.hasAspect()) { .... [[_1_0a1-withinall]] -===== Removing the withinall pointcut +==== Removing the withinall pointcut The withinall poinctut is no longer defined. You can use a combination of within and the xref:#_1_0a1-subtypes-to-plus[new subtypes operator], @@ -843,7 +843,7 @@ within(Foo+) .... [[_1_0a1-user-defined-returns]] -===== Removing returns modifier from pointcuts +==== Removing returns modifier from pointcuts The returns keyword is no longer necessary for user-defined pointcuts. Simply remove it when you find it. @@ -856,7 +856,7 @@ pointcut publicIntCall(): call(public int *(..)); .... [[_1_0a1-static-pointcuts]] -===== Making some pointcuts static +==== Making some pointcuts static In Java, only static members may be accessed by their declaring type name, like the static method `Math.max()` can be accessed. @@ -874,10 +874,10 @@ classes `static`, and make any pointcut with a qualified reference static. [[_1_0a1-type-patterns]] -==== Type patterns +=== Type patterns [[_1_0a1-new-wildcards]] -===== Understanding * and .. in type patterns +==== Understanding * and .. in type patterns Previous versions of AspectJ treated * and .. too cleverly in type patterns, placing restrictions based on what is a package and what is a @@ -908,7 +908,7 @@ pointcut unaryVoidMethod(): call(void *(*)); .... [[_1_0a1-subtypes-to-plus]] -===== Fixing subtypes in introduction +==== Fixing subtypes in introduction The new + operator is used to normalize the many places you want to use subtypes of some types. @@ -931,10 +931,10 @@ public void (Target0+ || Target1+).accept(Visitor v) { .... [[_1_0a1-advice]] -==== Advice +=== Advice [[_1_0a1-around-returns]] -===== Moving the return type of around +==== Moving the return type of around The returns keyword is no longer used for around advice. Instead, the return type is declared as it is for methods. So, @@ -947,7 +947,7 @@ void around(Point p): setter(p) { ... } .... [[_1_0a1-around-throws]] -===== Adding a throws clause to around +==== Adding a throws clause to around Around advice must now declare the checked exceptions it throws with a `throws` clause, much like a method. @@ -966,7 +966,7 @@ char around(char c) throws java.io.CharConversionException: converter(c) { .... [[_1_0a1-advice-precedence]] -===== Understanding advice precedence +==== Understanding advice precedence In previous versions of AspectJ, advice precedence within an aspect was simple: if a piece of advice appeared before another piece, it was more @@ -1022,7 +1022,7 @@ Advice in _different_ aspects is ordered by the normal aspect precedence rules of subtyping and the `dominates` modifier. [[_1_0a1-after-returning]] -===== Fixing after returning +==== Fixing after returning If you use after returning advice and do not need to expose the return value, you no longer need to write an empty set of parentheses to @@ -1044,14 +1044,14 @@ after(Formals) throwing: Pointcut { ... } .... [[_1_0a1-this-static-join-point]] -===== Renaming thisStaticJoinPoint +==== Renaming thisStaticJoinPoint `thisStaticJoinPoint` has been renamed `thisJoinPointStaticPart`, to reflect that it is now exactly the static part of `thisJoinPoint`: It will return the same object as `thisJoinPoint.getStaticPart()`. [[_1_0a1-this-join-point]] -===== Converting access to thisJoinPoint +==== Converting access to thisJoinPoint The `JoinPoint` object hierarchy has been folded into a single class, `org.aspectj.lang.JoinPoint`. A common pattern in logging, for example, @@ -1083,10 +1083,10 @@ before() executions(* myMethod()) { Some of the method names of `JoinPoint` have been reorganized, as well. [[_1_0a1-introduction-and-static]] -==== Introduction and static crosscutting +=== Introduction and static crosscutting [[_1_0a1-plus-implements-extends]] -===== Removing +implements and +extends +==== Removing +implements and +extends The keywords `+implements` and `+extends` no longer exist. Instead, AspectJ uses the `declare` form for exactly the same functionality. @@ -1106,7 +1106,7 @@ declare parents: MyButton extends ButtonAdaptor; .... [[_1_0a1-now-use-soft]] -===== Using declare soft +==== Using declare soft Around advice advice no longer effects the static exception checking of Java. This means that the following code previously compiled: @@ -1156,7 +1156,7 @@ declare soft: IOException: .... [[_1_0a1-aspects]] -==== Aspects +=== Aspects The syntax of "of each" modifiers has changed. For `of eachcflow` and `of eachcflowbelow`, you can simply replace "of each" with "per". So, @@ -1222,7 +1222,7 @@ object at such join points. ''''' [[pre08b3]] -=== Porting pre-0.8beta3 code +== Porting pre-0.8beta3 code * xref:#cflowTerminology[Changing cflow terminology] * xref:#abstractPointcuts[Overriding abstract pointcuts] @@ -1232,18 +1232,18 @@ The following changes are only required when porting code written prior to the 0.8beta3 release of AspectJ. [[cflowTerminology]] -==== Changing cflow terminology +=== Changing cflow terminology Changing pre-0.8beta3 code that uses AspectJ's control-flow-based features only requires rewriting occurrences of `eachcflowroot`, `cflow`, and `cflowtop`. No editing of other aspect code is necessary. -===== eachcflowroot +==== eachcflowroot The aspect modifier "`of eachcflowroot(Pointcut)`" should now be written more as "`percflow(Pointcut)`". -===== cflow +==== cflow In previous versions of AspectJ, the pointcut `cflow(Pointcut)` picked out all join points in the cflow below the join points of `Pointcut`. @@ -1270,7 +1270,7 @@ definitely want to rewrite that as Pointcut && ! cflowbelow(Pointcut) ---- -===== cflowtop +==== cflowtop The primitive pointcut designator `cflowtop(Pointcut)` has been removed from the language, as it is expressible with `cflow` or `cflowbelow`. @@ -1289,7 +1289,7 @@ cflow(Pointcut && ! cflowbelow(Pointcut)) ---- [[abstractPointcuts]] -==== Overriding abstract pointcuts +=== Overriding abstract pointcuts In previous versions of AspectJ, a concrete aspect would implicitly override all of its abstract pointcuts with an empty pointcut. AspectJ @@ -1328,7 +1328,7 @@ aspect B { ---- [[recursiveAdvice]] -==== Limiting recursive advice +=== Limiting recursive advice Previously, the compiler silently refrained from applying a piece of advice to join points within its own advice body. So, for example, in @@ -1401,7 +1401,7 @@ aspect A { ''''' [[pre08b1]] -=== Porting pre-0.8beta1 code +== Porting pre-0.8beta1 code * xref:#introSyntax[Rewriting introductions] * xref:#staticAdvice[Removing static advice] @@ -1412,9 +1412,9 @@ The following changes are only required when porting code written prior to the 0.8beta1 release of AspectJ. [[introSyntax]] -==== Rewriting introductions +=== Rewriting introductions -===== Syntax +==== Syntax The syntax of introduction has changed. Porting most programs should require some simple editing. Anywhere you have an introduction block @@ -1481,7 +1481,7 @@ introduction subtypes(Foo) && !Goo { int (Foo+ && !Goo).x; ---- -===== Access +==== Access If you had an introduction that was referring to private or protected members of the target class, this will no longer work. You will either @@ -1547,7 +1547,7 @@ inherited from a superclass, you will have to make this introduction public. [[staticAdvice]] -==== Removing static advice +=== Removing static advice Static advice has been removed from the language. Now, every piece of advice is non-static, meaning that it will run in the context of an @@ -1610,7 +1610,7 @@ aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) { ---- [[aspect-aspect]] -==== Fixing aspect-aspect inheritance +=== Fixing aspect-aspect inheritance Aspects can now only extend abstract aspects. This restriction may cause some redesign of aspect hierarchies. You will probably find that for the @@ -1670,7 +1670,7 @@ A better way to implement this kind of design aspect is to use private introduction, a new feature of AspectJ. [[usingPrivateIntroduction]] -==== Using private introduction +=== Using private introduction A common pattern for AspectJ programs that need to associate some state with every object of a particular type has been to use aspects that are @@ -1722,7 +1722,7 @@ association may capture the crosscutting concern best. ''''' [[pre07b11]] -=== Porting pre-0.7beta11 code +== Porting pre-0.7beta11 code * xref:#twoArgumentCalls[Removing two-argument calls] * xref:#adviceInClasses[Removing advice from Class declarations] @@ -1731,13 +1731,13 @@ The following changes are only required when porting code written prior to the 0.7beta11 release of AspectJ. [[twoArgumentCalls]] -==== Removing two-argument calls +=== Removing two-argument calls In AspectJ 0.7beta11, the two-argument `calls` primitive pointcut designator was deprecated. Removing these designators will require different cases depending on what the original pointcut did. -===== Calls to static methods +==== Calls to static methods For pointcuts denoting calls to particular static methods, such as @@ -1771,7 +1771,7 @@ should now be written call(static * my.package.*.get*(..)) .... -===== Calls to non-static methods +==== Calls to non-static methods Many pointcuts denoting calls to non-static methods can be fixed the same way that those pointcuts denoting calls to static methods are @@ -1815,7 +1815,7 @@ It will also denote any join points if the Thread type does not define (possibly abstractly) some `int getPriority()` method, though. [[adviceInClasses]] -==== Removing advice from Class declarations +=== Removing advice from Class declarations The simplest way to remove an advice declaration from a class is to simply define the advice declaration in an inner aspect. So, instead of @@ -1860,7 +1860,7 @@ appropriate. ''''' [[pre07b10]] -=== Porting pre-0.7beta10 code +== Porting pre-0.7beta10 code * xref:#joinPoints[Changing access to thisJoinPoint] @@ -1868,7 +1868,7 @@ The following changes are only required when porting code written prior to the 0.7beta10 release of AspectJ. [[joinPoints]] -==== Changing access to thisJoinPoint +=== Changing access to thisJoinPoint In AspectJ 0.7beta10, access to the reflective object `thisJoinPoint` substantially changed. The two parts of this change were the elimination @@ -1876,7 +1876,7 @@ of the `runNext()` static method, and the use of an interface hierarchy represent the join point object. [[proceed]] -===== `thisJoinPoint.runNext()` to `proceed()` +==== `thisJoinPoint.runNext()` to `proceed()` The elimination of the `runNext()` static method requires almost no porting work. An automatic replacement of the string @@ -1901,7 +1901,7 @@ aspect name or `this`, depending on whether the field is static or not). [[thisJoinPoint]] -===== Using `thisJoinPoint` +==== Using `thisJoinPoint` While access to reflective information through `thisJoinPoint` is more powerful and regular through its interface hierarchy, the previous uses -- 2.39.5