Add initial set of AsciiDoc files, converted from HTML/XML

Some originals have been deleted already. Others, especially the user
guides, still exist in both formats because they have not been
proof-read and probably lots of links do not function as expected. But I
want to see what the files look like directly on GitHun.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

51 files changed, 9351 insertions, 82 deletions

diff --git a/docs/dist/doc/README-11.adoc b/docs/dist/doc/README-11.adoc
new file mode 100644
index 000000000..0464ba88b
--- /dev/null
+++ b/docs/dist/doc/README-11.adoc
@@ -0,0 +1,1330 @@
+[.small]#© Copyright 2002 Palo Alto Research Center, Incorporated, 2003
+Contributors. All rights reserved.#
+
+== AspectJ 1.1 Readme
+
+This is the initial release of AspectJ 1.1. It includes a small number
+of new language features as well as major improvements to the
+functionality of the tools.
+
+This document describes the differences between AspectJ versions 1.1 and
+1.0.6. Users new to AspectJ need only read the
+link:progguide/index.html[AspectJ Programming Guide] since it describes
+the 1.1 language. Users familiar with AspectJ 1.0 may find this document
+a quicker way to learn what changed in the language and tools, and
+should use it as a guide for porting programs from 1.0 to 1.1.
+
+This document first summarizes changes from the 1.0 release in
+
+* xref:#language[the language],
+* xref:#compiler[the compiler],
+* xref:#tools[the support tools],
+* xref:#runtime[the runtime],
+* xref:#devenv[the development environment support],
+* xref:#sources[the sources], and
+* xref:#distribution[the distribution],
+
+then xref:#details[details] some of the language and compiler changes,
+and finally points readers to the bug database for any
+xref:#knownLimitations[known limitations].
+
+'''''
+
+=== [#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
+correctly in AspectJ 1.1. In many cases, there are new or preferred
+forms in AspectJ 1.1. However, some AspectJ 1.0 features have changed in
+1.1, so some 1.0 programs will not compile or will run differently in
+1.1. The corresponding features are marked below as compile-time or
+run-time incompatible (_CTI_ or _RTI_, respectively). When the language
+change involves a move in the static shadow effective at run-time but
+also apparent at compile-time (e.g., in declare error or warning
+statements), it is marked _CRTI_. Programs using run-time incompatible
+forms should be verified that they are behaving as expected in 1.1.
+
+Most changes to the language are additions to expressibility requested
+by our users:
+
+* xref:#THROWS_PATTERN[Matching based on throws]: You can now make finer
+discriminations between methods based on declared exceptions.
+* xref:#NEW_PCDS[New kinded pointcut designators]: Now every kind of
+join point has a corresponding kinded pointcut designator.
+
+Some are have different behavior in edge cases but offer improved power
+and clarity:
+
+* xref:#ASPECT_PRECEDENCE[New aspect precedence form]: AspectJ 1.1 has a
+new declare form, `declare     precedence`, that replaces the
+"dominates" clause on aspects. (_CTI_)
+* The order of xref:#SUPER_IFACE_INITS[initialization join points for
+super-interfaces] has been clarified. (_RTI_)
+
+But in order to support weaving into bytecode effectively, several
+incompatible changes had to be made to the language:
+
+* A class's default constructor may
+xref:#DEFAULT_CONSTRUCTOR_CONFLICT[conflict] with an inter-type
+constructor. (_CTI_)
+* xref:#NO_CALLEE_SIDE_CALL[No callee-side call join points]: The
+AspectJ 1.1 compiler does not expose call join points unless it is given
+the calling code. (_CRTI_)
+* xref:#SINGLE_INTERCLASS_TARGET[One target for intertype declarations].
+(_CTI_)
+* xref:#UNAVAILABLE_JOIN_POINTS[No initializer execution join points].
+(_RTI_)
+* xref:#AFTER_HANDLER[No after or around advice on handler join points].
+(_CTI_)
+* xref:#CONSTRUCTOR_EXECUTION_IS_BIGGER[Initializers run inside
+constructor execution join points]. (_RTI_)
+* xref:#INTER_TYPE_FIELD_INITIALIZERS[inter-type field initializers] run
+before class-local field initializers. (_RTI_)
+* xref:#WITHIN_MEMBER_TYPES[Small limitations of the within pointcut.]
+(_CRTI_)
+* xref:#WITHIN_CODE[Small limitations of the withincode pointcut.]
+(_CRTI_)
+* xref:#INSTANCEOF_ON_WILD[Can't do instanceof matching on type patterns
+with wildcards]. (_CTI_)
+* xref:#NO_SOURCE_COLUMN[SourceLocation.getColumn() is deprecated and
+will always return 0]. (_RTI_)
+* The interaction between aspect instantiation and advice has been
+xref:#ASPECT_INSTANTIATION_AND_ADVICE[clarified]. (_RTI_)
+* xref:#STRINGBUFFER[The String + operator is now correctly advised].
+(_CRTI_)
+
+[#NEW_LIMITATIONS]#There# are a couple of language limitations for
+things that are rarely used that make the implementation simpler, so we
+have restricted the language accordingly.
+
+* xref:#VOID_FIELD_SET[Field set join points now have a `void` return
+type.] This will require porting of code that uses the `set` PCD in
+conjunction with after-returning or around advice. (_CTI_)
+* 'declare soft: TYPE: POINTCUT;' - AspectJ 1.1 only accepts TYPE rather
+than a TYPE_PATTERN. This limitation makes declare soft much easier to
+implement efficiently. (_CTI_)
+* Inter-type field declarations only allow a single field per line, i.e.
+this is now illegal 'int C.field1, D.field2;' This must instead be, 'int
+C.field1; int D.field2;' (_CTI_)
+* We did not implement the handling of more than one `..` wildcard in
+args PCD's (rarely encountered in the wild) because we didn't have the
+time. This might be available in later releases if there is significant
+outcry. (_CTI_)
+
+We did not implement the long-awaited xref:#PER_TYPE[new pertype aspect
+specifier] in this release, but it may well be in a future release.
+
+'''''
+
+=== [#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
+worthwhile noting that much effort has been made to make sure that the
+interface to ajc 1.1 is, as much as possible, the same as the interface
+to ajc 1.0. There are two important changes under the hood, however.
+
+First, the 1.1 compiler is implemented on top of the open-source Eclipse
+compiler. This has two benefits: It allows us to concentrate on the
+AspectJ extensions to Java and let the Eclipse team worry about making
+sure the Java edge cases work, and it allows us to piggyback on
+Eclipse's already mature incremental compilation facilities.
+
+Second, ajc now cleanly delineates compilation of source code from
+assembly (or "weaving") of bytecode. The compiler still accepts source
+code, but internally it transforms it into bytecode format before
+weaving.
+
+This new architecture, and other changes to the compiler, allows us to
+implement some features that were defined in the AspectJ 1.0 language
+but not implementable in the 1.1 compiler. It also makes some new
+features available:
+
+* xref:#SOURCEROOT[The -sourceroots option] takes one or more
+directories, and indicates that all the source files in those
+directories should be passed to the compiler.
+* xref:#BYTECODE_WEAVING[The -injars option] takes one or more jar
+files, and indicates that all the classfiles in the jar files should be
+woven into.
+* xref:#BINARY_ASPECTS[The -aspectpath option] takes one or more jar
+files, and weaves any aspects in .class form into the sources.
+* xref:#OUTJAR[The -outjar option] indicates that the result classfiles
+of compiling and weaving should be placed in the specified jar file.
+* xref:#XLINT[The -Xlint option] allows control over warnings.
+* xref:#OTHER_X_OPTIONS[Various -X options] changed.
+* xref:#INCREMENTAL[The -incremental option] tells the AspectJ 1.1
+compiler to recompile only as necessary.
+
+Some other features we wanted to support for 1.1, but did not make it
+into this release:
+
+* xref:#ERROR_MESSAGES[Error messages will sometimes be scary]
+* xref:#MESSAGE_CONTEXT[Source code context is not shown for errors and
+warnings detected during bytecode weaving]
+
+But some features of the 1.0 compiler are not supported in the 1.1
+compiler:
+
+* xref:#NO_SOURCE[The source-related options] -preprocess, -usejavac,
+-nocomment and -workingdir
+* xref:#NO_STRICT_LENIENT[The -strict and -lenient options]
+* xref:#NO_PORTING[The -porting option]
+* xref:#13_REQUIRED[J2SE 1.2 is not supported; J2SE 1.3 or later is
+required.]
+
+A short description of the options ajc accepts is available with
+"`ajc -help`". Longer descriptions are available in the
+link:devguide/ajc-ref.html[Development Environment Guide section on
+ajc].
+
+Some changes to the implementation are almost entirely internal:
+
+* The behavior of the compiler in xref:#TARGET_TYPES_MADE_PUBLIC[lifting
+the visibility] of the target types of some declares and pointcuts to
+public has been clarified.
+
+Also, it is worth noting that because AspectJ now works on bytecode, it
+is somewhat sensitive to how different compilers generate bytecode,
+especially when compiling with and without
+xref:#ONE_FOUR_METHOD_SIGNATURES[the -1.4 flag].
+
+'''''
+
+=== [#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
+running `ajc` with the Javac task by setting the `build.compiler`
+property. The new task can automatically copy input resources to output
+and work in incremental mode using a "tag" file.
+
+This release does not include `ajdoc`, the documentation tool for
+AspectJ sources. Ajdoc is deeply dependent on the abstract syntax tree
+classes from the old compiler, so it needs a bottom-up rewrite. We think
+it best to use this opportunity to implement more general API's for
+publishing and rendering static structure. Because those API's are last
+to settle in the new architecture, and because the compiler itself is a
+higher priority, we are delaying work on ajdoc until after the 1.1
+release.
+
+AspectJ 1.1 will not include ajdb, the AspectJ stand-alone debugger. It
+is no longer necessary for two reasons. First, the -XnoInline flag will
+tell the compiler to generate code without inlining that should work
+correctly with any Java debugger. For code generated with inlining
+enabled, more third-party debuggers are starting to work according to
+JSR 45, "Debugging support for other languages," which is supported by
+AspectJ 1.0. We aim to support JSR-45 in AspectJ 1.1, but support will
+not be in the initial release. Consider using the -XnoInline flag until
+support is available.
+
+'''''
+
+=== [#runtime]#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
+came with your compiler, and you may run with a later version of the
+library without recompiling your code.
+
+In one instance, however, runtime classes behave differently this
+release. Because the AspectJ 1.1 compiler does its weaving through
+bytecode, column numbers of source locations are not available.
+Therefore, `thisJoinPoint.getSourceLocation().getColumn()` is deprecated
+and will always return 0.
+
+'''''
+
+=== [#devenv]#The AJDE Tools#
+
+The AspectJ Browser supports incremental compilation and running
+programs. AJDE for JBuilder, AJDE for NetBeans, and AJDE for Emacs are
+now independent SourceForge projects (to keep their licenses). They use
+the batch-build mode of the new compiler.
+
+'''''
+
+=== [#sources]#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
+License v 2.0] in the Git repository at http://eclipse.org/aspectj. For
+more information, see the FAQ entry on
+faq.html#q:buildingsource[building sources].
+
+'''''
+
+=== [#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 -
+because they came under different licenses. All of AspectJ 1.1 is
+licensed under the CPL 1.0, so the tools, Ant tasks, and documentation
+are all in one distribution available from http://eclipse.org/aspectj.
+To retain their MPL 1.1 license, Ajde for
+http://aspectj4emacs.sourceforge.net/[Emacs],
+http://aspectj4netbean.sourceforge.net/[NetBeans] and
+http://aspectj4jbuildr.sourceforge.net/[JBuilder] are now independent
+SourceForge projects.
+
+'''''
+
+'''''
+
+=== [#details]#Details# of some language and compiler changes
+
+==== [#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
+compiled and ran:
+
+....
+      public class Client
+      {
+          public static void main(String[] args) {
+              Client c = new Client();
+          }
+      }
+
+      aspect Watchcall {
+          pointcut myConstructor(): execution(new(..));
+
+          before(): myConstructor() {
+              System.err.println("Entering Constructor");
+          }
+      }
+
+....
+
+But there's a conceptual problem with this code: The before advice
+should run before the execution of all constructors in the system. It
+must run in the context of an instance of the Watchcall aspect. The only
+way to get such an instance is to have Watchcall's default constructor
+execute. But before that executes, we need to run the before advice...
+
+AspectJ 1.0.6 hid this circularity through the ad-hoc mechanism of
+preventing an aspect's advice from matching join points that were within
+the aspect's definition, and occurred before the aspect was initialized.
+But even in AspectJ 1.0.6, this circularity could be exposed:
+
+....
+      public class Client
+      {
+          public static int foo() { return 3; }
+          public static void main(String[] args) {
+              Client c = new Client();
+          }
+      }
+
+      aspect Watchcall {
+          int i = Client.foo();
+          pointcut myConstructor():
+              execution(new(..)) || execution(int foo());
+
+          before(): myConstructor() {
+              System.err.println("Entering Constructor");
+          }
+      }
+
+....
+
+This program would throw a NullPointerException when run, since
+Client.foo() was called before the Watchcall instance could be
+instantiated.
+
+In AspectJ 1.1, we have decided that half-hiding the problem just leads
+to trouble, and so we are no longer silently hiding some join points
+before aspect initialization. However, we have provided a better
+exception than a NullPointerException for this case. In AspectJ 1.1,
+both of the above programs will throw
+org.aspectj.lang.NoAspectBoundException.
+
+==== [#THROWS_PATTERN]#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
+extremely wildcarded pointcuts:
+
+....
+    pointcut throwsMathlike():
+      // each call to a method with a throws clause containing at least
+      // one exception with "Math" in its name.
+      call(* *(..) throws *..*Math*);
+
+    pointcut doesNotThrowMathlike():
+      // each call to a method with a throws clause containing no
+      // exceptions with "Math" in its name.
+      call(* *(..) throws !*..*Math*);
+
+....
+
+The longwinded rules are that a method or constructor pattern can have a
+"throws clause pattern". Throws clause patterns look like:
+
+....
+    ThrowsClausePattern:
+        ThrowsClausePatternItem ("," ThrowsClausePatternItem)*
+
+    ThrowsClausePatternItem:
+        ["!"] TypeNamePattern
+
+....
+
+A ThrowsClausePattern matches the ThrowsClause of any code member
+signature. To match, each ThrowsClausePatternItem must match the throws
+clause of the member in question. If any item doesn't match, then the
+whole pattern doesn't match. This rule is unchanged from AspectJ 1.0.
+
+If a ThrowsClausePatternItem begins with "!", then it matches a
+particular throws clause if and only if _none_ of the types named in the
+throws clause is matched by the TypeNamePattern.
+
+If a ThrowsClausePatternItem does not begin with "!", then it matches a
+throws clause if and only if _any_ of the types named in the throws
+clause is matched by the TypeNamePattern.
+
+These rules are completely backwards compatible with AspectJ 1.0. The
+rule for "!" matching has one potentially surprising property, in that
+the two PCD's shown below will have different matching rules.
+
+....
+    [1] call(* *(..) throws !IOException)
+    [2] call(* *(..) throws (!IOException))
+
+    void m() throws RuntimeException, IOException {}
+
+....
+
+[1] will NOT match the method m(), because method m's throws clause
+declares that it throws IOException. [2] WILL match the method m(),
+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#
+
+AspectJ 1.0 does not provide kinded pointcut designators for two (rarely
+used) join points: preinitialization (the code that runs before a super
+constructor call is made) and advice execution. AspectJ 1.1 does not
+change the meaning of the join points, but provides two new pointcut
+designators to pick out these join points, thus making join points and
+pointcut designators more parallel.
+
+`adviceexectuion()` will pick out advice execution join points. You will
+usually want to use `adviceexecution()     && within(Aspect)` to
+restrict it to only those pieces of advice defined in a particular
+aspect. +
+`preinitialization(ConstructorPattern)` will pick out pre-initialization
+join points where the initialization process is entered through
+`ConstructorPattern`.
+
+==== [#PER_TYPE]#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
+xref:#SINGLE_INTERCLASS_TARGET[restrictions on inter-type declarations]
+
+. This is also motivated by many previous request to support a common
+logging idiom. Here's what pertype would look like:
+
+....
+    /** One instance of this aspect will be created for each class,
+     * interface or aspect in the com.bigboxco packages.
+     */
+    aspect Logger pertype(com.bigboxco..*) {
+        /* This field holds a logger for the class. */
+        Log log;
+
+        /* This advice will run for every public execution defined by
+         * a type for which a Logger aspect has been created, i.e.
+         * any type in com.bigboxco..*
+         */
+        before(): execution(public * *(..)) {
+            log.enterMethod(thisJoinPoint.getSignature().getName());
+        }
+
+        /* We can use a special constructor to initialize the log field */
+        public Logger(Class myType) {
+            this.log = new Log(myType);
+        }
+    }
+
+        /** External code could use aspectOf to get at the log, i.e. */
+        Log l = Logger.aspectOf(com.bigboxco.Foo.class).log;
+
+....
+
+The one open question that we see is how this should interact with inner
+types. If a pertype aspect is created for an outer type should advice in
+that aspect run for join points in inner types? That is the behavior of
+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#
+
+Intertype declarations (once called "introductions") in AspectJ 1.1 can
+only have one target type. So the following code intended to declare
+that there is a void doStuff() method on all subtypes of Target is not
+legal AspectJ 1.1 code.
+
+....
+    aspect A {
+        public void Target+.doStuff() { ... }
+    }
+
+....
+
+The functionality of "multi-intertype declarations" can be recovered by
+using a helper interface.
+
+....
+    aspect A {
+        private interface MyTarget {}
+        declare parents:  Target+ implements MyTarget;
+        public void MyTarget.doStuff() { ... }
+    }
+
+....
+
+We believe this is better style in AspectJ 1.0 as well, as it makes
+clear the static type of "this" inside the method body.
+
+The one piece of functionality that can not be easily recovered is the
+ability to add static fields to many classes. We believe that the
+xref:#PER_TYPE[pertype proposal] provides this functionality in a much
+more usable form.
+
+==== [#UNAVAILABLE_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
+with initializers and the code in non-static initializer blocks) is
+something that makes sense only in Java source code, not in Java
+bytecode.
+
+==== [#AFTER_HANDLER]####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#
+
+The code generated by the initializers in Java source code now runs
+inside of constructor execution join points. This changes how before
+advice runs on constructor execution join points. Consider:
+
+....
+    class C {
+        C() { }
+        String id = "identifier"; // this assignment
+                                  // has to happen sometime
+    }
+    aspect A {
+        before(C c) this(c) && execution(C.new()) {
+            System.out.println(c.id.length());
+        }
+    }
+
+....
+
+In AspectJ 1.0, this will print "10", since id is assigned its initial
+value prior to the before advice's execution. However, in AspectJ 1.1,
+this will throw a NullPointerExcception, since "id" does not have a
+value prior to the before advice's execution.
+
+Note that the various flavors of after returning advice are unchanged in
+this respect in AspectJ 1.1. Also note that this only matters for the
+execution of constructors that call a super-constructor. Execution of
+constructors that call a this-constructor are the same in AspectJ 1.1 as
+in AspectJ 1.0.
+
+We believe this difference should be minimal to real programs, since
+programmers using before advice on constructor execution must always
+assume incomplete object initialization, since the constructor has not
+yet run.
+
+==== [#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.
+
+In AspectJ 1.0.6, such an initializer would run after the initializers
+of a class but before the execution of any of its constructor bodies. As
+already discussed in the sections about
+xref:#UNAVAILABLE_JOIN_POINTS[initializer execution join points] and
+xref:#CONSTRUCTOR_EXECUTION_IS_BIGGER[constructor execution], the point
+in code between the initializers of a class and its constructor body is
+not principled in bytecode. So we had a choice of running the
+initializer of an inter-type field definition at the beginning of
+initialization (i.e., before initializers from the target class) or at
+the end (i.e., just before its called constructor exits). We chose the
+former, having this pattern in mind:
+
+....
+    int C.methodCount = 0;
+    before(C c): this(c) && execution(* *(..)) { c.methodCount++; }
+
+....
+
+We felt there would be too much surprise if a constructor called a
+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#
+
+Because of the guarantees made (and not made) by the Java classfile
+format, there are cases where AspectJ 1.1 cannot guarantee that the
+within pointcut designator will pick out all code that was originally
+within the source code of a certain type.
+
+The non-guarantee applies to code inside of anonymous and local types
+inside member types. While the within pointcut designator behaves
+exactly as it did in AspectJ 1.0 when given a package-level type (like
+C, below), if given a member-type (like C.InsideC, below), it is not
+guaranteed to capture code in contained local and anonymous types. For
+example:
+
+....
+    class C {
+        Thread t;
+        class InsideC {
+            void setupOuterThread() {
+                t = new Thread(
+                        new Runnable() {
+                            public void run() {
+                                // join points with code here
+                                // might not be captured by
+                                // within(C.InsideC), but are
+                                // captured by within(C)
+                                System.out.println("hi");
+                            }
+                        });
+            }
+        }
+    }
+
+....
+
+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#
+
+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#
+
+The pointcut designators this, target and args specify a dynamic test on
+their argument. These tests can not be performed on type patterns with
+wildcards in them. The following code that compiled under 1.0 will be an
+error in AspectJ-1.1:
+
+....
+    pointcut oneOfMine(): this(com.bigboxco..*);
+
+....
+
+The only way to implement this kind of matching in a modular way would
+be to use the reflection API at runtime on the Class of the object. This
+would have a very high performance cost and possible security issues.
+There are two good work-arounds. If you control the source or bytecode
+to the type you want to match then you can use declare parents, i.e.:
+
+....
+    private interface OneOfMine {}
+    declare parents: com.bigboxco..* implements OneOfMine;
+    pointcut oneOfMine(): this(OneOfMine);
+
+....
+
+If you want the more dynamic matching and are willing to pay for the
+performance, then you should use the Java reflection API combined with
+if. That would look something like:
+
+....
+    pointcut oneOfMine(): this(Object) &&
+        if(classMatches("com.bigboxco..*",
+                        thisJoinPoint.getTarget().getClass()));
+
+    static boolean classMatches(String pattern, Class _class) {
+        if (patternMatches(pattern, _class.getName())) return true;
+        ...
+    }
+
+....
+
+Note: wildcard type matching still works in all other PCD's that match
+based on static types. So, you can use 'within(com.bigboxco..*+)' to
+match any code lexically within one of your classes or a subtype
+thereof. This is often a good choice.
+
+==== [#NO_SOURCE_COLUMN]#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
+source columns. As a result, we can not effectively support the access
+of column information in the reflection API. So, any calls to
+thisJoinPoint.getSourceLocation().getColumn() will be marked as
+deprecated by the compiler, and will always return 0.
+
+==== [#ASPECT_PRECEDENCE]#Aspect precedence#
+
+AspectJ 1.1 has a new declare form:
+
+....
+    declare precedence ":"  TypePatternList ";"
+
+....
+
+This is used to declare advice ordering constraints on join points. For
+example, the constraints that (1) aspects that have Security as part of
+their name should dominate all other aspects, and (2) the Logging aspect
+(and any aspect that extends it) should dominate all non-security
+aspects, can be expressed by:
+
+....
+    declare precedence: *..*Security*, Logging+, *;
+
+....
+
+In the TypePatternList, the wildcard * means "any type not matched by
+another type in the declare precedence".
+
+===== Various cycles
+
+It is an error for any aspect to be matched by more than one TypePattern
+in a single declare precedence, so:
+
+....
+      declare precedence:  A, B, A ;  // error
+
+....
+
+However, multiple declare precedence forms may legally have this kind of
+circularity. For example, each of these declare precedence is perfectly
+legal:
+
+....
+      declare precedence: B, A;
+      declare precedence: A, B;
+
+....
+
+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
+
+Consider the following library aspects:
+
+....
+      abstract aspect Logging {
+          abstract pointcut logged();
+
+          before(): logged() {
+              System.err.println("thisJoinPoint: " + thisJoinPoint);
+          }
+      }
+
+      aspect MyProfiling {
+          abstract pointcut profiled();
+
+          Object around(): profiled() {
+              long beforeTime = System.currentTimeMillis();
+              try {
+                  return proceed();
+              } finally {
+                  long afterTime = System.currentTimeMillis();
+                  addToProfile(thisJoinPointStaticPart,
+                               afterTime - beforeTime);
+              }
+          }
+          abstract void addToProfile(
+              org.aspectj.JoinPoint.StaticPart jp,
+              long elapsed);
+      }
+
+....
+
+In order to use either aspect, they must be extended with concrete
+aspects, say, MyLogging and MyProfiling. In AspectJ 1.0, it was not
+possible to express that Logging's advice (when concerned with the
+concrete aspect MyLogging) dominated Profiling's advice (when concerned
+with the concrete aspect MyProfiling) without adding a dominates clause
+to Logging itself. In AspectJ 1.1, we can express that constraint with a
+simple:
+
+....
+      declare precedence: MyLogging, MyProfiling;
+
+....
+
+===== 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
+this precedence:
+
+....
+      abstract aspect SuperA dominates SubA {
+          pointcut foo(): ... ;
+
+          before(): foo() {
+              // in AspectJ 1.0, runs before the advice in SubA
+              // because of the dominates clause
+          }
+      }
+
+      aspect SubA extends SuperA {
+          before(): foo() {
+              // in AspectJ 1.0, runs after the advice in SuperA
+              // because of the dominates clause
+          }
+      }
+
+....
+
+This no longer works in AspectJ 1.1, since declare precedence only
+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 AspectJ 1.1 compiler now accepts a -sourceroots option used to pass
+all .java files in particular directories to the compiler. It takes
+either a single directory name, or a list of directory names separated
+with the CLASSPATH separator character (":" for various Unices, ";" for
+various Windows).
+
+So, if you have your project separated into a gui module and a base
+module, each of which is stored in a directory tree, you might use one
+of
+
+....
+    ajc -sourceroots /myProject/gui:/myProject/base
+    ajc -sourceroots d:\myProject\gui;d:\myProject\base
+
+....
+
+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 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
+single directory name, or a list of directory names separated with the
+CLASSPATH separator character (":" for various Unices, ";" for various
+Windows).
+
+So, if MyTracing.java defines a trace aspect that you want to apply to
+all the classes in myBase.jar and myGui.jar, you would use one of:
+
+....
+    ajc -injars /bin/myBase.jar:/bin/myGui.jar MyTracing.java
+    ajc -injars d:\bin\myBase.jar;d:\bin\myGui.jar MyTracing.java
+
+....
+
+The class files in the input jars must not have had advice woven into
+them, since AspectJ enforces the requirement that advice is woven into a
+particular classfile only once. So if the classfiles in the jar file are
+to be created with the ajc compiler (as opposed to a pure Java
+compiler), they should not be compiled with any non-abstract aspects.
+
+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 takes the name of a jar file into which the results
+of the compilation should be put. For example:
+
+....
+    ajc -injars myBase.jar MyTracing.java -outjar myTracedBase.jar
+
+....
+
+No meta information is placed in the output jar file.
+
+==== [#INCREMENTAL]#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
+-sourceroots option specifying a directory to incrementally compile.
+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
+
+This new functionality is still only lightly tested.
+
+==== [#XNOWEAVE]#-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
+final, woven classfiles.
+
+This option was originally envisioned to be the primary way to generate
+binary aspects that could be linked with other code, and so it was
+previously (in AspectJ 1.1beta1) named `-noweave`. We feel that using
+the `-aspectpath` option is a much better option. There may still be use
+cases for unwoven classfiles, but we've moved the flag to experimental
+status.
+
+==== [#BINARY_ASPECTS]#-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
+inter-type declarations. In order for these aspects to have an effect on
+a compilation process, they must be passed to the compiler on the
+-aspectpath. Every .jar file on this path will be searched for aspects
+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#
+
+The 1.0 implementation of AspectJ, when given:
+
+....
+    class MyRunnable implements Runnable {
+        public void run() { ... }
+    }
+
+    aspect A {
+        call(): (void run()) && target(MyRunnable) {
+            // do something here
+        }
+    }
+
+....
+
+would cause A's advice to execute even when, say, java.lang.Thread
+called run() on a MyRunnable instance.
+
+With the new compiler, two things have happened in regard to callee-side
+calls:
+
+. because the programmer has access to more code (i.e., bytecode, not
+just source code), callee-side calls are much less important to have.
+. because compilation is more modular, allowing and encouraging separate
+compilation, callee-side calls are much more difficult to implement
+
+With these two points in mind, advice in an aspect will not be applied
+to call join points whose call site is completely unavailable to the
+aspect.
+
+. One reason (though not the only reason) we worked so hard in the
+_implementation_ of 1.0.6 to expose call join points, even if we only
+had access to the callee's code, was that otherwise users couldn't get
+access to call join points where the call was made from bytecode. This
+is no longer the case. In short, the implementation controls much more
+code (or has the capability to) than ever before.
+. The implementation model for the AspectJ 1.1 compiler is to separate
+the compilation of aspects/advice from their weaving/linking. A property
+of the model is that the compilation requires no access to "target"
+code, only the weaving/linking does, and weaving/linking is inherently
+per-class local: No action at weaving/linking time depends on the
+coordinated mangling of multiple classfiles. Rather, all weaving is done
+on a per classfile basis. This is an essential property for the current
+separate compilation model. +
+However, allowing implementation of call advice on either side requires
+simultaneous knowledge of both sides. If we first have access to a call,
+we can't decide to simply put the advice on the call site, since later
+we may decide to implement on the callee.
+
+This implementation decision is completely in the letter and the spirit
+of the AspectJ language. From the semantics guide describing code the
+implementation controls:
+
+____
+But AspectJ implementations are permitted to deviate from this in a
+well-defined way -- they are permitted to advise only accesses in _code
+the implementation controls_. Each implementation is free within certain
+bounds to provide its own definition of what it means to control code.
+____
+
+And about a particular decision about the 1.0.6 implementation:
+
+____
+Different join points have different requirements. Method call join
+points can be advised only if ajc controls _either_ the code for the
+caller or the code for the receiver, and some call pointcut designators
+may require caller context (what the static type of the receiver is, for
+example) to pick out join points.
+____
+
+The 1.1 implementation makes a different design decision: Method call
+join points can be advised only if ajc (in compiler or linker form)
+controls the code for the caller.
+
+What does 1.1 gain from this?
+
+* a clear (and implemented) separate compilation model (see point 2,
+above)
+* a less confusing interaction between call join points and the
+thisJoinPoint reflective object: We still get bug reports about source
+information sometimes existing and sometimes not existing at call join
+points.
+
+What does 1.1 lose from this?
+
+* The ability to capture all calls to Runnable.run() from anywhere to
+code ajc has access too, even from Thread, even if you don't compile
+java.lang with ajc.
+* The ability to, without access to the caller, capture entry to a
+particular method, but not super calls.
+* A code-size-improvement performance optimization.
+
+What are the possibilities for the future?
+
+* AspectJ 1.1.1 could expand its capture of call join points, possibly
+at the expense of separate compilation clarity, possibly not.
+* AspectJ 1.1.1 could re-introduce reception join points from AspectJ
+0.7 (what callee-side call join points actually are): though they would
+never ever be taught in a tutorial or entry-level description of the
+model, they may have specialized uses.
+
+How will this affect developers?
+
+* When using the call PCD but only supplying the callee code, supply the
+calling code or use the execution PCD instead.
+
+==== [#OTHER_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
+because the "experiment" succeeded (in which case it's part of the
+normal functionality) or failed. Others will be supported as is (or
+nearly so) in 1.1:
+
+* -XOcodeSize: This is no longer necessary because inlining of around
+advice is on by default. We support its inverse,
+xref:#XNOINLINE[`-XnoInline`].
+* xref:#XNOWEAVE[-XnoWeave, a compiler option to suppress weaving]
+* -XtargetNearSource: Not supported in this release.
+* -XserializableAspects: Supported.
+* -XaddSafePrefix: This option will not be supported in 1.1 at all
+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#
+
+Building on the eclipse compiler has given us access to a very
+sophisticated problem reporting system as well as highly optimized error
+messages for pure Java code. Often this leads to noticeably better error
+messages than from ajc-1.0.6. However, when we don't handle errors
+correctly this can sometimes lead to cascading error messages where a
+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#
+
+For compiler errors and warnings detected during bytecode weaving,
+source code context will not be displayed. In particular, for declare
+error and declare warning statements, the compiler now only emits the
+file and line. We are investigating ways to overcome this in cases where
+the source code is available; in cases where source code is not
+available, we might specify the signature of the offending code. For
+more information, see bug 31724.
+
+==== [#XLINT]#The -Xlint option#
+
+`-Xlint:ignore,error,warning` will set the level for all Xlint warnings.
+`-Xlint`, alone, is an abbreviation for `-Xlint:warning`.
+
+The `-Xlintfile:lint.properties` allows fine-grained control. In
+tools.jar, see `org/aspectj/weaver/XlintDefault.properties` for the
+default behavior and a template to copy.
+
+More `-Xlint` warnings are supported now, and we may add disabled
+warnings in subsequent bug-fix releases of 1.1. Because the
+configurability allows users to turn off warnings, we will be able to
+warn about more potentially dangerous situations, such as the
+potentially unsafe casts used by very polymorphic uses of proceed in
+around advice.
+
+==== [#NO_SOURCE]#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#
+
+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#
+
+AspectJ 1.1 does not have a -porting option.
+
+==== [#13_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)
+using J2SE 1.3 or later. The code generated by the compiler can still
+run on Java 1.1 or later VM's if compiled against the correct runtime
+libraries.
+
+==== [#DEFAULT_CONSTRUCTOR_CONFLICT]#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
+longer allowed:
+
+....
+    class C {}
+
+    aspect A {
+        C.new() {}  // was allowed in 1.0.6
+                    // is a "multiple definitions" conflict in 1.1
+    }
+
+....
+
+In the Java Programming Language, a class defined without a constructor
+actually has a "default" constructor that takes no arguments and just
+calls `super()`.
+
+This default constructor is a member of the class like any other member,
+and can be referenced by other classes, and has code generated for it in
+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#
+
+In AspectJ, interfaces may have non-static members due to inter-type
+declarations. Because of this, the semantics of AspectJ defines the
+order that initializer code for interfaces is run.
+
+In the semantics document for AspectJ 1.0.6, the following promises were
+made about the order of this initialization:
+
+. a supertype is initialized before a subtype
+. initialized code runs only once
+. initializers for supertypes run in left-to-right order
+
+The first two properties are important and are preserved in AspectJ 1.1,
+but the third property is and was ludicrous, and was never properly
+implemented (and never could be) in AspectJ 1.0.6. Consider:
+
+....
+    interface Top0 {}
+    interface Top1 {}
+    interface I extends Top0, Top1 {}
+    interface J extends Top1, Top0 {}
+
+    class C implements I, J {}
+    // I says Top0's inits must run before Top1's
+    // J says Top1's inits must run before Top0's
+
+    aspect A {
+        int Top0.i = foo("I'm in Top0");
+        int Top1.i = foo("I'm in Top1");
+        static int foo(String s) {
+            System.out.println(s);
+            return 37;
+        }
+    }
+
+....
+
+This was simply a bug in the AspectJ specification. The correct third
+rule is:
+
+____
+the initializers for a type's superclass are run before the initializers
+for its superinterfaces.
+____
+
+==== [#VOID_FIELD_SET]#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
+java, such as "Foo.i = 37", is in fact an expression, and does in fact
+return a value, the value that the field is assigned to.
+
+This was never "java programmer compatible", however, largely because
+programmers have absorbed the good style of rarely using an assignment
+statement in a value context. Programmers typically expect "Foo.i = 37"
+not to return a value, but to simply assign a value.
+
+Thus, programmers typically wanted to write something like:
+
+....
+    void around(): set(int Foo.i) {
+        if (theSetIsAllowed()) {
+            proceed();
+        }
+    }
+
+....
+
+And were confused by it being a compile-time error. They weren't
+confused for long, and soon adapted to writing:
+
+....
+    int around(): set(int Foo.i) {
+        if (theSetIsAllowed()) {
+            return proceed();
+        } else {
+            return Foo.i;
+        }
+    }
+
+....
+
+But there was definitely a short disconnect.
+
+On top of that, we were never shown a convincing use-case for returning
+an interesting value from a set join point. When we revisited this
+issue, in fact, we realized we had a long-standing bug in 1.0.6 dealing
+with the return value of pre-increment expressions (such as ++Foo.i)
+that nobody had found because nobody cares about the return value of
+such join points.
+
+So, because it's easier to implement, and because we believe that this
+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 to indicate that no inlining of any kind should
+be done. This is purely a compiler pragma: No program semantics (apart
+from stack traces) will be changed by the presence or absence of this
+option.
+
+==== [#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
+previously done in an ad-hoc basis that took whole-program analysis into
+account. With the incremental compilation model of AspectJ 1.1, we can
+now specify the occasions when the compiler makes these visibility
+changes.
+
+In particular, the types used in the `this`, `target`, and `args`
+pointcuts are made public, as are the super-types from `declare parents`
+and the exception type from `declare soft`.
+
+We believe the visibility changes could be avoided in the future with
+various implementation tricks if they become a serious concern, but did
+not encounter them as such a concern when they were done in the 1.0.6
+implementation.
+
+==== [#STRINGBUFFER]#String + now advised#
+
+In Java, the + operator sometimes results in StringBuffer objects being
+created, appended to, and used to generate a new String. Thus,
+
+....
+class Foo {
+    String makeEmphatic(String s) {
+        return s + "!";
+    }
+}
+....
+
+is approximately the same at runtime as
+
+....
+class Foo {
+    String makeEmphatic(String s) {
+        return new StringBuffer(s).append("!").toString();
+    }
+}
+....
+
+In the design process of AspectJ 1.0.6 we didn't expose those
+StringBuffer methods and constructors as join points (though we did
+discuss it), but in 1.1 we do.
+
+This change is likely to affect highly wildcarded aspects, and can do so
+in surprising ways. In particular:
+
+....
+class A {
+    before(int i): call(* *(int)) && args(i) {
+        System.err.println("entering with " + i);
+    }
+}
+....
+
+may result in a stack overflow error, since the argument to println is
+really
+
+....
+new StringBuffer("entering with ").append(i).toString()
+....
+
+which has a call to StringBuffer.append(int). In such cases, it's worth
+restricting your pointcut, with something like one of:
+
+....
+call(* *(int)) && args(i) && !within(A)
+call(* *(int)) && args(i) && !target(StringBuffer)
+....
+
+==== [#ONE_FOUR_METHOD_SIGNATURES]#The -1.4 flag and method signatures#
+
+Consider the following aspect
+
+....
+public aspect SwingCalls {
+
+    pointcut callingAnySwing(): call(* javax.swing..*+.*(..));
+
+    before(): callingAnySwing() {
+        System.out.println("Calling any Swing");
+    }
+}
+....
+
+And then consider the two statements
+
+....
+  JFrame frame = new JFrame();
+  frame.setTitle("Title");
+....
+
+According to the Java Language Specification version 2, the call to
+`frame.setTitle("Title")` should always produce the bytecode for a call
+to `javax.swing.JFrame.setTitle`. However, older compilers (and eclipse
+when run without the `-1.4` flag) will generate the bytecode for a call
+to `java.awt.Frame.setTitle` instead since this method is not overriden
+by JFrame. The AspectJ weaver depends on the correctly generated
+bytecode in order to match patterns like the one you show correctly.
+
+This is a good example of why the pattern
+`call(* *(..)) && target(JFrame)` is the recommended style. In general,
+OO programmers don't want to care about the static type of an object at
+a call site, but only want to know the dynamic instanceof behavior which
+is what the target matching will handle.
+
+=== [#knownLimitations]#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
+information about known limitations in an AspectJ 1.1 release, see the
+bug database at http://bugs.eclipse.org/bugs, especially the open bugs
+for the
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[compiler],
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=IDE&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[IDE
+support],
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Doc&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[documentation],
+and
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Ant&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED[Ant
+tasks]. Developers should know about bugs marked with the "info" keyword
+because those bugs reflect failures to implement the 1.1 language
+perfectly. These might be fixed during the 1.1 release cycle; find them
+using the query
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info
+For ajc's 1.1 implementation limitations, see
+link:progguide/implementation.html[Programming Guide Appendix:
+"Implementation Notes"].
diff --git a/docs/dist/doc/README-12.adoc b/docs/dist/doc/README-12.adoc
new file mode 100644
index 000000000..3aec6a919
--- /dev/null
+++ b/docs/dist/doc/README-12.adoc
@@ -0,0 +1,563 @@
+[.small]#© Copyright 2003,2004 Contributors. All rights reserved.#
+
+== AspectJ 1.2 Readme
+
+The definition of the AspectJ language is unchanged in the 1.2 release.
+Instead, AspectJ 1.2 provides major improvements to the functionality of
+the supporting tools and enforces some language limits that went
+unchecked before. This document describes the tools differences between
+AspectJ versions 1.2 and 1.1.1. Users new to AspectJ need only read the
+link:progguide/index.html[AspectJ Programming Guide] since it describes
+the 1.2 language. Users familiar with AspectJ 1.1 may find this document
+a quicker way to learn what changed in the tools, and should use it as a
+guide for porting programs from 1.1 to 1.2, together with porting.html.
+
+This document first summarizes changes from the 1.1.1 release in
+
+* xref:#compiler[the compiler],
+* xref:#tools[the support tools],
+* xref:#runtime[the runtime],
+* xref:#devenv[the development environment support],
+
+then xref:#details[details] some of the changes, and finally points
+readers to the bug database for xref:#allchanges[all the changes].
+
+'''''
+
+=== [#compiler]#The Compiler#
+
+Compared to AspectJ 1.1.1, the AspectJ 1.2 compiler...
+
+* xref:#WEAVE_TIME[Is faster], with weaving completing in less than half
+the time it used to take in many cases.
+[#WEAVE_CHART]#image:images/AspectJ11v12.JPG[image]#.
+* Supports the xref:#LAZY_TJP[-XlazyTjp option] which produces code that
+runs faster and uses less memory in some common cases.
+* Has xref:#INCREMENTAL[much better support for incremental
+compilation].
+* Produces xref:#ERROR_MESSAGES[better error messages].
+* Has some xref:#LINT[new lint warnings] to catch common mistakes and
+changes to serializability.
+* Supports the xref:#REWEAVABLE[-Xreweavable option] that allows classes
+to be woven more than once.
+* {blank}
+* Supports the xref:#INPATH[-inpath option] which allows both
+directories and jars containing class files to be specified as input to
+the weaver.
+* xref:#COMPLIANCE[Changes the default compiler compliance mode] from
+-1.3 to -1.4.
+
+A short description of the options ajc accepts is available with
+"`ajc -help`". Longer descriptions are available in the
+link:devguide/ajc-ref.html[Development Environment Guide section on
+ajc].
+
+'''''
+
+=== [#tools]#Support Tools#
+
+AspectJ 1.2 contains two important changes to the supporting tools:
+
+* xref:#AJDOC[ajdoc] is back
+* A sample script is supplied for xref:#LTW[load-time weaving] from the
+command-line.
+
+'''''
+
+=== [#runtime]#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
+came with your compiler, and you may run with a later version of the
+library without recompiling your code.
+
+* xref:#SOFTEX[`SoftException`] now supports `getCause()`.
+* Although not part of `aspectjrt.jar` this release also provides a new
+set of tools APIs in the xref:#LTW2[`org.aspectj.weaver.tools`] that
+provide a weaving class loader and an adapter that can be used to
+integrate load-time weaving into an existing class loader hierarchy.
+* Cflow stack management has been modified to use thread local storage
+on JVMs that support this feature. This improves performance in terms of
+heap usage for multi-threaded applications that use cflow.
+
+'''''
+
+=== [#devenv]#The AJDE Tools#
+
+The AJDE based tools for JBuilder, NetBeans and Emacs continue to be
+independent SourceForge projects. The AspectJ 1.2 distribution includes
+an updated version of the AjBrowser tool that benefits from all the
+enhancements made in the 1.2 compiler.
+
+The 1.2 release of AspectJ also lays a lot of the groundwork for a much
+better AspectJ IDE experience that we hope to surface initially through
+AJDT (AspectJ support for Eclipse). Amongst the many improvements, we
+will have full eager parsing support that avoids the need to keep the
+whole structure model of a project in memory, hopefully making AJDT much
+less memory hungry and much slicker to use. For more details see the
+http://www.eclipse.org/ajdt[AJDT project website].
+
+'''''
+
+=== [#details]#Details# of some compiler changes
+
+==== [#WEAVE_TIME]#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
+pointcut expressions (see the xref:#WEAVE_CHART[chart above]). We've
+also made the base incremental compilation implementation in AspectJ 1.2
+approximately twice as fast as in AspectJ 1.1.1, so when this is
+combined with the weave time improvements you should see speed-ups of up
+to 4x for incremental compilation.
+
+In addition, AspectJ 1.2 maintains only weak references to some of its
+recoverable data structures, allowing the JVM to optimise between
+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.#
+
+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
+example a call to `getArgs()`), then a JoinPoint object was always
+creating before entering the advice. This was the case even if the
+advice was guarded with an `if()` pointcut that evaluated to false.
+
+AspectJ 1.2 now supports the `-XlazyTjp` option that only creates the
+JoinPoint object just before dispatching to the advice body. By
+promoting the guard to a test in an `if()` pointcut, the creation of the
+JoinPoint object can be avoided altogether in the case where the test
+returns false.
+
+Consider a simple tracing aspect as follows:
+
+....
+
+  public aspect Tracing {
+
+    public static boolean enabled = false;
+
+    pointcut toBeTraced() : execution(* *(..)) || execution(new(..));
+
+    before() : toBeTraced() && if(enabled) {
+      Object[] args = thisJoinPoint.getArgs();
+      // format args and print out entry trace record etc....
+    }
+  }
+
+
+....
+
+The most important consideration is the system overhead when tracing is
+turned off. Using the `-XlazyTjp` option makes the program above run
+10-100x faster, even when running a small test case with minimal GC
+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.#
+
+AspectJ 1.2 provides more complete incremental compilation support than
+AspectJ 1.1.1. Firstly, incremental compilation resulting from a change
+to a source file is now approximately twice as fast as it was under
+1.1.1 (even before taking the improvements to weaving time into
+account). Secondly, the incremental coverage now takes into account
+changes to resources, classes and jars on the inpath, injars, and
+aspectpath. The new `inpath` option in AspectJ 1.2 allows directories to
+be specified in addition to jars (just like a classpath) as input to the
+weaver. Any update, addition or deletion of a class file in a directory
+on the inpath will cause incremental (re)weaving.
+
+Changes to a jar file on the inpath, injars or aspectpath will now be
+detected, but will trigger a full rebuild, as will any change to the
+paths used to control compilation.
+
+==== [#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
+were passed to the compiler. For example, an error message arising as a
+result of a `declare error` statement might look as follows under
+AspectJ 1.1.1:
+
+....
+  BadClass.java:6 should not be calling bad methods
+
+....
+
+whereas in AspectJ 1.2 you will see:
+
+....
+  BadClass.java:6 error should not be calling bad methods
+  new C().bad();
+  ^^^^^^^^^^^^^^
+       method-call(void C.bad())
+       see also: DeclareError.java:5
+
+....
+
+There are four new things to note about this error message. Firstly,
+errors and warnings are now prefixed with the word "error", or "warning"
+as appropriate. Secondly, the offending line of source is shown if
+source code is available. Thirdly, in the case of weaver messages
+arising as a result of `declare error` and `declare warning` statements,
+AspectJ now shows not only the location of the error or warning, but
+also the location of the `declare` statement itself. Finally, note that
+messages produced as a result of `declare error` and `declare warning`
+statements now also display the matched join point at the location of
+the error:
+
+When source code is not available, the messages show the binary input
+source (class file or jar file) in which the error or warning was
+detected:
+
+....
+  BadClass.java:6 error should not be calling bad methods
+  (no source information available)
+         method-call(void C.bad())
+         see also: C:\...\DeclareError.java:5
+         see also: C:\...\bin-input.jar
+
+....
+
+This error message tells us that `BadClass.class` contained in a jar on
+the inpath called `bin-input.jar`, and originally compiled from a source
+file called `BadClass.java`, contains a join point
+(`method-call(void C.bad())` matched by a `declare error` statement on
+line 5 of the file `DeclareError.java`.
+
+==== [#LINT]#New lint warnings.#
+
+Consider the program:
+
+....
+
+  01 class A {
+  02   public void doIt() {...};
+  03 }
+  04
+  05 class B extends A {
+  06   public void doThisToo() {...};
+  07 }
+  08
+  09
+  10 public class CallsAandB {
+  11
+  12  public static void main(String[] args) {
+  13    B b = new B();
+  14    A bInDisguise = new B();
+  15
+  16    b.doIt();               // AspectJ 1.2 matches here
+  17    bInDisguise.doIt();     // this is never matched
+  18  }
+  19
+  20 }
+  21
+  22 aspect CallPCDMatchingExample {
+  23
+  24   before() : call(* B.doIt(..)) {
+  25     System.out.println("About to call B.doIt(...)");
+  26   }
+  27
+  28 }
+
+
+....
+
+Because the static type of `bInDisguise` is `A` (line 14), the call on
+line 17 is never matched by the pointcut expression on 24, even though
+the runtime type of `bInDisguise` is `B`. Type patterns matched in
+`call` pointcut designators are matched based on static type matching.
+Some users have found this static type matching confusing, and AspectJ
+1.2 has a new Xlint warning (`unmatchedSuperTypeInCall`) which is
+enabled by default.
+
+The compiler will now produce a warning whenever a call pointcut
+designator does not match at a join point, and a user may have expected
+it to. Compiling the above program using AspectJ 1.2 produces the
+following compiler output:
+
+....
+
+
+  CallsAandB.java:24 warning does not match because declaring type is A, if match desired use target(B) [Xlint:unmatchedSuperTypeInCall]
+  before() : call(* B.doIt(..)) {
+             ^^^^^^^^^^^^^^^
+      see also: CallsAandB.java:17
+
+
+  1 warning
+
+
+
+....
+
+The warning is telling us that the call pointcut associated with the
+before advice on line 24 of the source file does not match at a join
+point where the user may have expected it to. The source location
+corresponding to the unmatched join point is indicated by the "see also"
+line - in this case line 17 of the source file. At line 17 we find a
+call to `bInDisguise.doIt()`. Since the static type of `bInDisguise` is
+`A`, this call will never be matched. The warning also tells us a
+possible solution if we intended the pointcut to match at this join
+point: use `call(* doIt(..) && target(B)`.
+
+If you find warnings of this kind coming out when you use the AspectJ
+1.2 compiler, the recommended fix is to switch to using the `target`
+designator in place of a type pattern in the `call` pointcut expression.
+Note that there is no loss of runtime efficiency here - runtime tests
+are only added in the cases where it cannot be determined at compile
+time whether the type of the receiver will match the type specified in
+the `target` expression. Also note that `target` cannot be used in
+`declare` statements.
+
+A new Xlint warning, `needsSerialVersionUIDField` (disabled by default)
+will produce a warning at compile time if the process of weaving changes
+the default `serialVersionUID` of a serializable class, and the class
+does not define a `serialVersionUID`. By defining a `serialVersionUID`
+field, the programmer can ensure that objects serialized without the
+aspect present can be read by a version of the program in which the
+aspect is present, and vice-versa.
+
+A complimentary Xlint warning, `brokeSerialVersionCompatibility`
+(disabled by default) will produce a warning at compile time if the
+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 new `-Xreweavable` option produces class files that contain enough
+additional information in them that they can be rewoven. In time we hope
+that this can become a standard option, replacing the current
+`-Xnoweave` option. Using reweavable produces class files that can be
+legally loaded by a JVM, whereas with noweave, it is too easy to produce
+class files that will result in a verify error at runtime. The
+reweavable option makes it easy to weave code many times without having
+to decide which weave is the final one. In a future version of the
+AspectJ compiler, producing reweavable class files may become the
+default option. The trade-off at the moment is that reweavable class
+files are currently approximately twice the size of their non-reweavable
+counterparts.
+
+To ensure consistent semantics when reweaving, the AspectJ compiler
+requires that all aspects that have previously modified a class file
+during weaving be present in the system during a reweave. An error will
+be issued if any are missing.
+
+==== [#INPATH]#The -inpath option.#
+
+The new `-inpath` option replaces the `-injars` option (which is still
+supported for backwards compatibility). It allows both directories and
+jar files to be specified using path separators to separate entries in
+the path. This option makes it easy for class files produced as the
+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 AspectJ compiler compliance level is now 1.4 (whereas in
+previous releases the default compliance level was 1.3). This has a
+number of implications:
+
+* class files generated by the compiler are now JRE v1.2 and upwards
+compatible. (At compliance level 1.3, AspectJ generated class files that
+were compatible with JRE 1.1 also).
+* `call` pointcuts may match more join points than in the same program
+compiled at compliance level 1.3.
+
+The AspectJ compiler can be restored to 1.3 compliance settings by
+specifying the "-1.3" option on the command-line.
+
+Consider again the following example program which illustrates the
+differences in join point matching with the `call` pointcut designator
+between 1.4 and 1.3 compliance levels.
+
+....
+
+   01 class A {
+   02   public void doIt() {...};
+   03 }
+   04
+   05 class B extends A {
+   06   public void doThisToo() {...};
+   07 }
+   08
+   09
+   10 public class CallsAandB {
+   11
+   12  public static void main(String[] args) {
+   13    B b = new B();
+   14    A bInDisguise = new B();
+   15
+   16    b.doIt();               // AspectJ 1.2 matches here
+   17    bInDisguise.doIt();     // this is never matched
+   18  }
+   19
+   20 }
+   21
+   22 aspect CallPCDMatchingExample {
+   23
+   24   before() : call(* B.doIt(..)) {
+   25     System.out.println("About to call B.doIt(...)");
+   26   }
+   27
+   28 }
+
+
+....
+
+When this program is compiled with AspectJ 1.2 using the default
+compiler options, it will produce one line of output when it is
+executed:
+
+`About to call B.doIt(...)`
+
+The same program compiled under AspectJ 1.1 (or using AspectJ 1.2 with
+the -1.3 flag specified) does not produce any output when it is run. The
+reason for the additional call pcd match is that prior to compliance
+level 1.4, Java compilers produced bytecodes that call A.doIt() (the
+defining type of the method), rather than B.doIt() (the declared type in
+the program text). The generated call to A.doIt() is not matched by the
+call pcd used in the before advice. At compliance level 1.4, the
+bytecodes retain the declared type of the receiver in the program
+source, generating a call to B.doIt(), which _is_ matched by the call
+pcd.
+
+This is a good example of why the recommended style is to use
+`call(* doIt(..)) && target(B)`, which always matches based on the
+actual type of the receiver.
+
+'''''
+
+==== [#AJDOC]#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
+javadoc that also shows advises and advised by relationships next to
+methods and advice. A future enhancement will show inter-type
+declarations in the target class too.
+
+*Known limitations:* Please note that `ajdoc` documents advice and
+pointcut members, shows where advice applies and links affected members
+back to the advice.  It currently does not document or add structural
+links for any inter-type declarations or other declare forms.
+
+Run the "ajdoc.bat" script just as you run javadoc.  For a list of
+accepted parameters run "ajdoc -help".  For example, to document
+everything in the Spacewar example run: +
+> cd examples +
+> ajdoc -d doc -private spacewar coordination
+
+`ajdoc` sample output for an aspect source file:
+
+image:images/ajdoc1.JPG[image]
+
+`ajdoc` sample output for advised methods:
+
+image:images/ajdoc2.JPG[image]
+
+==== [#LTW]#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
+application load time. You will find these scripts in the
+`doc/examples/ltw` directory of your AspectJ installation.
+
+The scripts allow you to set an environment variable, `ASPECTPATH`,
+containing a path-separator delimited list of aspect-library jar files.
+A Java application can then be launched using the "`aj`" script ("`aj`"
+is to "`ajc`" as "`java`" is to "`javac`"). If the `ASPECTPATH` is unset
+or empty, "`aj`" behaves exactly the same as "`java`", but if the
+`ASPECTPATH` contains one or more aspect libraries, the aspects in the
+library will be linked (woven) with the application code as it is
+loaded.
+
+The `doc/examples/ltw` directory of your AspectJ installation contains a
+sample application that demonstrates these capabilities. Following the
+instructions in the `README` file in that directory, running
+"`aj tracing.ExampleMain`" with `ASPECTPATH` unset produces the output:
+
+....
+  c1.perimeter() = 12.566370614359172
+  c1.area() = 12.566370614359172
+  s1.perimeter() = 4.0
+  s1.area() = 1.0
+  c2.distance(c1) = 4.242640687119285
+  s1.distance(c1) = 2.23606797749979
+  s1.toString(): Square side = 1.0 @ (1.0, 2.0)
+
+....
+
+If you set `ASPECTPATH` to include `../jars/tracingLib.jar`, and run
+"`aj tracing.ExampleMain`" again, the output will be:
+
+....
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Circle(double, double, double)
+  <-- tracing.Circle(double, double, double)
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Circle(double, double, double)
+  <-- tracing.Circle(double, double, double)
+  --> tracing.Circle(double)
+  <-- tracing.Circle(double)
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Square(double, double, double)
+  <-- tracing.Square(double, double, double)
+  --> tracing.Square(double, double)
+  <-- tracing.Square(double, double)
+  --> double tracing.Circle.perimeter()
+  <-- double tracing.Circle.perimeter()
+c1.perimeter() = 12.566370614359172
+  --> double tracing.Circle.area()
+  <-- double tracing.Circle.area()
+c1.area() = 12.566370614359172
+  --> double tracing.Square.perimeter()
+  <-- double tracing.Square.perimeter()
+s1.perimeter() = 4.0
+  --> double tracing.Square.area()
+  <-- double tracing.Square.area()
+s1.area() = 1.0
+  --> double tracing.TwoDShape.distance(TwoDShape)
+    --> double tracing.TwoDShape.getX()
+    <-- double tracing.TwoDShape.getX()
+    --> double tracing.TwoDShape.getY()
+    <-- double tracing.TwoDShape.getY()
+  <-- double tracing.TwoDShape.distance(TwoDShape)
+  etc...
+
+....
+
+The scripts only support JDK 1.4 and above - attempting to use them with
+a 1.3 or lower JDK will most likely produce `NoClassDefFound` errors. We
+welcome contributions from users to improve these scripts.
+
+'''''
+
+==== [#SOFTEX]#SoftException now supports getCause()#
+
+`org.aspectj.lang.SoftException` now supports the `getCause()` method,
+which returns the original exception wrapped by the `SoftException`.
+This means that exception chains will print correctly on 1.4 and later
+JREs.
+
+==== [#LTW2]#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
+to integrate load-time weaving into an existing class loader hierachy.
+The package implementation is included in `aspectjtools.jar`. For an
+example of how to use these APIs, see the
+`org.aspectj.weaver.WeavingURLClassLoader` implementation.
+
+'''''
+
+[#allchanges]##
+
+=== 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:
+https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&target_milestone=1.2
diff --git a/docs/dist/doc/README-121.adoc b/docs/dist/doc/README-121.adoc
new file mode 100644
index 000000000..f2a66fda0
--- /dev/null
+++ b/docs/dist/doc/README-121.adoc
@@ -0,0 +1,134 @@
+[.small]#© Copyright 2004 Contributors. All rights reserved.#
+
+== AspectJ 1.2.1 Readme
+
+AspectJ 1.2.1 is largely a bug-fix release and the definition of the
+AspectJ language is unchanged from the 1.2.0 release (with the exception
+that AspectJ 1.2.1 permits the use of the '+' operator to concatenate
+the messages for declare error and warning statements). This document
+describes the tools differences between AspectJ versions 1.2 and 1.2.1.
+Users familiar with AspectJ 1.2 may find this document a quicker way to
+learn what changed in the tools.
+
+This document summarizes changes in:
+
+* Weaver messages
+* Dump support
+* JDT Compiler version
+* Line number information for join points
+* Runtime performance
+* String concatentation in declare error and warning statements
+* Load-time weaving support
+* Use of aspect libraries generated by ajc 1.2.1 with earlier versions
+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
+
+The AspectJ 1.2.1 compiler can produce informational messages about the
+weaving process. To see these messages, use the -showWeaveInfo compiler
+option, or set showweaveinfo=true in the iajc ant task.
+
+The following is an example of the messages produced when this option is
+enabled:
+
+....
+    C:\aspectj1.2.1\doc\examples\tjp>ajc -showWeaveInfo *.java
+
+    Type 'tjp.Demo' (Demo.java:20) advised by around advice from 'tjp.GetInfo'
+    (GetInfo.java:26) [RuntimeTest=true]
+
+    Type 'tjp.Demo' (Demo.java:30) advised by around advice from 'tjp.GetInfo'
+    (GetInfo.java:26) [RuntimeTest=true]
+
+    Type 'tjp.Demo' (Demo.java:34) advised by around advice from 'tjp.GetInfo'
+    (GetInfo.java:26) [RuntimeTest=true]
+....
+
+=== 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
+of the crash. These dump files should enable us to analyze problems more
+effectively. In the rare event that you witness a compiler crash, please
+attach the dump file to the bug report.
+
+In addition to producing a dump file when an abort condition is
+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
+
+AspectJ 1.2.1 is based on the Eclipse 3.0 final JDT compiler.
+
+=== 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
+line number information for execution join points. In particular, for a
+method, constructor or advice execution join point (as matched for
+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
+
+AspectJ 1.2.1 contains a small number of runtime performance
+optimisations, including optimisations of if(true) and if(false)
+pointcut expressions, caching of getSignature() and toString() results
+on JoinPoint objects, and an optimised implementation of cflow.
+
+In the case where there are no arguments bound in the cflow pointcut,
+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 and warning statements is now
+supported. For example, you can write:
+
+....
+        declare warning : jdbcCall() && !inDataLayer()
+                        : "Please don't make calls to JDBC " +
+                          "outside of the data layer.";
+
+....
+
+=== 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
+for weaving only. This jar may be used in situations where you wish to
+exploit AspectJ's binary weaving capabilities, but do not want the full
+aspectjtools.jar around (aspectjweaver.jar is approx. 5 times smaller).
+
+In addition, the load-time weaving "aj" script which was included in the
+doc/examples/ltw directory in the 1.2 distribution has been moved into
+the regular bin directory. See link:README-12.html[README-12] for
+details of using this script.
+
+=== 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
+v1.2.1 cannot be used on the inpath or aspectpath of a weaver from a
+prior version of the compiler. Classes generated by prior versions of
+the compiler can of course be placed on the inpath or aspectpath of the
+1.2.1 weaver.
+
+As ever, you should use the AspectJ runtime library (aspectjrt.jar) that
+comes with the distribution you used to build your application.
+
+'''''
+
+[#allchanges]##
+
+=== 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:
+https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&target_milestone=1.2.1[https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&target_milestone=1.2.1&bug_status=RESOLVED&resolution=FIXED]
diff --git a/docs/dist/doc/README-150.adoc b/docs/dist/doc/README-150.adoc
new file mode 100644
index 000000000..3e553f239
--- /dev/null
+++ b/docs/dist/doc/README-150.adoc
@@ -0,0 +1,21 @@
+[.small]#© Copyright 2005 Contributors. All rights reserved.#
+
+== AspectJ 5 Readme
+
+AspectJ 5 introduces several important changes to the language and tools
+in order to support Java 5 and extend the capabilities of AspectJ in
+general. For language changes, see link:adk15notebook/index.html[AspectJ
+5 Developer's Notebook]. For tools changes, see the
+link:devguide/index.html[AspectJ Development Environment Guide],
+especially the section on link:devguide/ltw.html[Load-time weaving]. The
+changes are summarized in the faq.html#q:aspectj5features[FAQ entry on
+AspectJ 5].
+
+Some of the other documentation has not been updated for AspectJ 5. For
+the latest documentation, see
+http://eclipse.org/aspectj/doc/next/index.html , linked off
+http://eclipse.org/aspectj/docs.php[the AspectJ documentation home page]
+.
+
+For information on bug fixes in AspectJ 5 v1.5.0, see the
+link:changes.html[changes] document.
diff --git a/docs/dist/doc/README-151.adoc b/docs/dist/doc/README-151.adoc
new file mode 100644
index 000000000..6216cd0c3
--- /dev/null
+++ b/docs/dist/doc/README-151.adoc
@@ -0,0 +1,22 @@
+[.small]#© Copyright 2006 Contributors. All rights reserved.#
+
+== AspectJ 5 v1.5.1 Readme
+
+This release is primarily a bug fix and performance / memory usage
+release. Over 70 fixes and enhancements have been incorporated since
+1.5.0, you can see the list through
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&target_milestone=1.5.1&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED[this
+bugzilla query].
+
+AspectJ 1.5.1 has significantly lower memory usage than AspectJ 1.5.0,
+especially when building inside of AJDT. The improvements are also
+noticeable when batch building with Ant, or when load-time weaving.
+Batch building a project with over 1000 source files with both AspectJ
+1.5.1 and AspectJ 1.5.0 shows a 16% reduction in peak memory usage, and
+an 8% reduction in heap consumed by temporary objects. The AspectJ 1.5.1
+compiler integrated into AJDT gives memory savings of at least 50%. The
+greater savings in the AJDT environment are due to improvements in areas
+such as structure model generation that are not exercised
+
+For information on bug fixes in AspectJ 5 v1.5.1, see the
+link:changes.html[changes] document.
diff --git a/docs/dist/doc/README-152.adoc b/docs/dist/doc/README-152.adoc
new file mode 100644
index 000000000..ec41e1488
--- /dev/null
+++ b/docs/dist/doc/README-152.adoc
@@ -0,0 +1,30 @@
+[.small]#© Copyright 2006 Contributors. All rights reserved.#
+
+== AspectJ 5 v1.5.2 Readme
+
+This release is primarily a bug fix release. It includes approximately
+60 fixes and enhancements that have been incorporated since the 1.5.1
+release. You can see the full list through
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&target_milestone=1.5.2&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED[this
+bugzilla query].
+
+Notable changes since the 1.5.1 release include:
+
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=126167[[126167]] The
+handling of proceed in @Around advice has changed to be more compatible
+with code style.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=147711[[147711]] Members
+generated as a result of the AspectJ weaving process are now marked Java
+synthetic - enabling coverage tools such as Emma to process woven
+classes correctly.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=138316[[138316]] AspectJ
+has now transitioned from the CPL to the EPL license.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=140695[[140695]] Using a
+more optimal world for managing types when load-time weaving - reduces
+heap usage (work in progress).
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=101983[[101983]] AspectJ
+can now support separate output folders for each input source folder -
+enables AJDT to behave more like JDT.
+
+For information on bug fixes in AspectJ 5 v1.5.2, see the
+link:changes.html[changes] document.
diff --git a/docs/dist/doc/README-153.adoc b/docs/dist/doc/README-153.adoc
new file mode 100644
index 000000000..8b1c065f1
--- /dev/null
+++ b/docs/dist/doc/README-153.adoc
@@ -0,0 +1,121 @@
+[.small]#© Copyright 2006 Contributors. All rights reserved.#
+
+== AspectJ 5 v1.5.3 Readme
+
+This release includes a number of bug fixes and enhancements (over 80).
+The full list of resolved issues can be found with
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.5.3&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=[this
+bugzilla query].
+
+Notable changes since the 1.5.2 release include: +
+
+=== 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)
+
+``
+
+....
+     /\_
+    /   \_
+   /      \_
+  /         \_
+ /            \_
+/               \
+....
+
+The first phase (as we go up and up and up) is the compilation of every
+file - when the peak is reached we then start weaving files one by one,
+discarding them once woven and dumped to disk. In 1.5.3 we don't compile
+everything up front - we compile and weave files one at a time. Giving
+us this profile:
+
+``
+
+....
+  /\  /\  /\
+ /  \/  \/  \
+/            \
+....
+
+Each peak is compiling a file, then it is woven, dumped to disk and the
+space recovered (the trough) - we then move onto the next file. What
+does this mean? The peaks are far far lower, so you need far less memory
+to compile a project. For example, I have a 1000file project, affected
+by aspects at >750 join points. For given values of Xmx, here are the
+times taken to compile it (on the command line) with AspectJ1.5.2:
+
+....
+Xmx  Time
+512M 33seconds
+256M 40seconds
+220M 116seconds
+212M OutOfMemory
+....
+
+The times gradually increase as the memory is reduced because the VM
+starts to thrash in garbage collection. Here are the results for
+AspectJ1.5.3:
+
+....
+Xmx  Time
+512M 33s
+256M 33s
+180M 33s
+140M 33s
+100M 35s
+80M  43s
+70M  OutOfMemory
+....
+
+So with 1.5.3, it isn't until around 80M that the VM starts to struggle
+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]
+
+As AspectJ grows in popularity, we find that it is becoming more
+difficult for users to come up with the small testcases that recreate
+problems - the usage scenarios for AJ are becoming more and more
+sophisticated. To help us work on problems in these scenarios we have
+added a tracing and logging framework and improved our dump mechanism.
+These traces and dumps can be attached to bug reports. In AspectJ 1.5.3
+we have included some
+http://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
+
+==== 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`
+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]
+
+Concrete aspects defined using aop.xml are now exposed for weaving.
+
+=== 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:
+
+``
+
+....
+String getWithinTypeName()
+....
+
+can be called on an aspect and will return the full qualified name of
+the type (eg. "com.foo.MyClass")
+
+'''''
+
+For information on bug fixes in AspectJ 5 v1.5.3, see the
+link:changes.html[changes] document.
diff --git a/docs/dist/doc/README-154.adoc b/docs/dist/doc/README-154.adoc
new file mode 100644
index 000000000..4565910d8
--- /dev/null
+++ b/docs/dist/doc/README-154.adoc
@@ -0,0 +1,16 @@
+[.small]#© Copyright 2006 Contributors. All rights reserved.#
+
+== AspectJ 5 v1.5.4 Readme
+
+This release includes a number of bug fixes and enhancements. The full
+list of resolved issues can be found with
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.5.4&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=[this
+bugzilla query].
+
+Some key fixes include better handling of generic type declarations,
+both in regular Java classes and in combination with AspectJ constructs
+(for example, inter-type declarations)
+
+ +
+
+'''''
diff --git a/docs/dist/doc/README-160.adoc b/docs/dist/doc/README-160.adoc
new file mode 100644
index 000000000..cba5ce076
--- /dev/null
+++ b/docs/dist/doc/README-160.adoc
@@ -0,0 +1,165 @@
+[.small]#© Copyright 2008 Contributors. All rights reserved.#
+
+== AspectJ v1.6.0 Readme
+
+=== AspectJ v1.6.0 - 23 Apr 2008
+
+For the complete list of every issue addressed since the last full
+release, see
+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=[this
+bugzilla link].
+
+Some of the highlights of 1.6.0 are:
+
+==== 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
+
+Changes under https://bugs.eclipse.org/bugs/show_bug.cgi?id=221427[bug
+221427] mean that the compiler is better able to maintain incremental
+state for projects in Eclipse and determine whether full builds or
+incremental builds are required when project dependencies change. The
+result is that the compiler will more frequently do an incremental build
+rather than falling back to doing a full build. Some basic performance
+findings can be seen in
+http://dev.eclipse.org/mhonarc/lists/aspectj-users/msg09002.html[this
+mailing list post].
+
+==== Parameter annotation matching
+
+Parameter matching is possible for constructors and methods. The use of
+parentheses around the parameter types in a method signature determine
+whether the annotations relate to the type of the parameter or the
+parameter itself.
+
+....
+execution(* *(@A *));
+....
+
+- Execution of a method/ctor whose first parameter is of a type
+annotated with @A.
+
+....
+execution(* *(@A (*)));
+....
+
+- Execution of a method/ctor whose first parameter is annotated with @A
+
+....
+execution(* *(@A (@B *)))
+....
+
+- Execution of a method/ctor whose first parameter is annotated with @A
+and is of a type annotated with @B. Example:
+
+....
+------ Start of Test.java -----
+@interface A {}
+@interface B {}
+
+class C {
+ public void foo(@A String s) {}
+ public void goo(@A @B String s) {}
+}
+
+aspect X {
+ before(): execution(* *(@A (*))) {}
+ before(): execution(* *(@B (*))) {}
+}
+------ End of Test.java -----
+$ ajc -showWeaveInfo -1.6 Test.java
+Join point 'method-execution(void C.foo(java.lang.String))' in Type 'C' (A.java:5) advised by before advice from 'X' (A.java:10)
+
+Join point 'method-execution(void C.goo(java.lang.String))' in Type 'C' (A.java:6) advised by before advice from 'X' (A.java:11)
+
+Join point 'method-execution(void C.goo(java.lang.String))' in Type 'C' (A.java:6) advised by before advice from 'X' (A.java:10)
+....
+
+The first piece of advice matched both methods. The second only matched
+goo(). +
+ +
+
+==== 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
+of the reflection that is currently required within the advice (in some
+cases). A typical use case is tracing where the trace level is defined
+by an annotation but may be switched OFF for a method if the annotation
+has a particular value. Perhaps tracing has been turned on at the type
+level and a few critical methods should not get traced. Here is some
+code showing the use case:
+
+....
+enum TraceLevel { NONE, LEVEL1, LEVEL2, LEVEL3 }
+
+@interface Trace {
+  TraceLevel value() default TraceLevel.LEVEL1;
+}
+  
+aspect X {
+  // Advise all methods marked @Trace except those with a tracelevel of none
+  before(): execution(@Trace !@Trace(TraceLevel.NONE) * *(..)) {
+    System.err.println("tracing "+thisJoinPoint);
+  }
+}
+
+public class ExampleOne {
+
+  public static void main(String[] args) {
+    ExampleOne eOne = new ExampleOne();
+    eOne.m001();
+    eOne.m002();
+    eOne.m003();
+    eOne.m004();
+    eOne.m005();
+    eOne.m006();
+    eOne.m007();
+  }
+
+  @Trace(TraceLevel.NONE)
+  public void m001() {}
+
+  @Trace(TraceLevel.LEVEL2)
+  public void m002() {} // gets advised
+
+  @Trace(TraceLevel.LEVEL3)
+  public void m003() {} // gets advised
+
+  @Trace(TraceLevel.NONE)
+  public void m004() {}
+
+  @Trace(TraceLevel.LEVEL2)
+  public void m005() {} // gets advised
+
+  @Trace(TraceLevel.NONE)
+  public void m006() {}
+
+  @Trace
+  public void m007() {} // gets advised
+
+}
+....
+
+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
+
+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
+
+AspectJ v1.6.0rc1- 16 Apr 2008
+
+AspectJ v1.6.0M2 - 26 Feb 2008
+
+AspectJ v1.6.0M1 - 16 Jan 2008
+
+'''''
diff --git a/docs/dist/doc/README-161.adoc b/docs/dist/doc/README-161.adoc
new file mode 100644
index 000000000..2cea859bb
--- /dev/null
+++ b/docs/dist/doc/README-161.adoc
@@ -0,0 +1,178 @@
+[.small]#© Copyright 2008 Contributors. All rights reserved.#
+
+== AspectJ 1.6.1 Readme
+
+The main themes of AspectJ1.6.1 are better memory usage and faster
+weaving. This has been achieved through profiling of the weaving process
+and has resulted in some serious refactoring of the weaver component
+within AspectJ. It provides exactly the same functionality as in
+previous releases, it just weaves faster now, using less code and less
+memory. This readme will give an overview of the kind of changes made
+and what can be expected when using 1.6.1 compared to previous releases.
+
+The complete list of issues resolved for AspectJ 1.6.1 can be found with
+these bugzilla queries. The first lists bugs addressed (more than 60!)
+whilst the second details enhancements made in this release.
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.1&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&bug_severity=blocker&bug_severity=critical&bug_severity=major&bug_severity=normal&bug_severity=minor&bug_severity=trivial&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=[Bugs
+resolved]
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.1&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&bug_severity=enhancement&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=[Enhancements
+implemented]
+
+'''''
+
+=== 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
+
+The refactoring effort has been focused on the weaver component, hence
+there is limited impact on the performance of source compilation but
+this comparison shows it is faster. Four scenarios are compared, in each
+scenario a different aspect is applied to the JDT compiler (just as a
+sample piece of source code).
+
+. 1100 source files, few aspects that target 859 join points.
+. 1100 source files, code style trace aspect targeting public methods
+(22000 join points)
+. 1100 source files, annotation style trace aspect (22000 join points)
+. 1100 source files, insane aspect (before(): within(*) \{}) (203000
+join points)
+
+image:perfSourceCompile_161.jpg[image]
+
+==== Binary weaving
+
+Moving on from source compilation to pure binary weaving, the
+improvements are more obvious. Here we are using the complete JVM
+classes jar 'rt.jar' as an example of a large jar file for weaving.
+
+. Binary weaving rt.jar (~12000 classes) with a simple aspect (1200 join
+points)
+. Binary weaving rt.jar (~12000 classes) with a code style trace aspect
+(121000 join points)
+. Binary weaving rt.jar (~12000 classes) with an annotation style trace
+aspect (121000 join points)
+. Binary weaving rt.jar (~12000 classes) with an insane aspect
+(before(): within(*) \{}) (352000 join points)
+
+image:perfBinaryWeave_161.jpg[image]
+
+==== 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
+an example of a jar file for loadtime weaving.
+
+. Binary weaving tools.jar (~1900 classes) with a code style trace
+aspect
+. Binary weaving tools.jar (~1900 classes) with an insane aspect
+(before(): within(*) \{})
+
+image:perfLTW_161.jpg[image]
+
+The refactoring work has also reduced the amount of unnecessary garbage
+created on the heap during the weaving process. The next comparison
+shows roughly the reduction in amount of 'stuff' created on the heap
+during a weave. This isn't the max heap required to do a weave, it is
+just showing how many less temporary objects are allocated during an
+entire run of the weaver
+
+. First, the number of kilobytes of memory allocated from the heap
+during a weave of tools.jar with a code style trace aspect
+. Second, another run of the same thing
+. Third, this time using the insane aspect
+
+image:heapContents_161.jpg[image]
+
+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
+
+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
+scenario, where multiple classloaders are being instantiated and
+discarded over time and each has an associated load time weaver. Under
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=210470[bug 210470] we
+looked in detail at whether the lifecycle of the weaver instance
+correctly matched the lifecycle of the associated classloader. It did
+not, but now it does! Here is a memory usage graph for AspectJ1.6.1 -
+this shows an application that spawns 7 threads which run continuously
+for a few minutes. Each thread repeatedly creates a classloader, weaves
+500 classes using it then discards the classloader. You can see that
+over time the memory is recovered correctly and when all threads
+complete (and all classloaders are orphaned), all the weavers are
+discarded.
+
+First, AspectJ 1.6.0, in which memory was never correctly recovered and
+so an OutOfMemory problem would always occur eventually.
+
+image:memLtwStress_160.jpg[image]
+
+And now AspectJ 1.6.1:
+
+image:memLtwStress_161.jpg[image]
+
+=== 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
+221427] ) - we now support the building of 'broken code'
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=102733[bug 102733]). This
+is something the JDT has always been doing - where code containing
+errors continues to build (if recovery is possible) but should the
+actual methods containing the errors get invoked, an exception will be
+thrown at runtime. A number of users typically extract large projects
+from their library systems, knowing that they will only partially build
+in their current eclipse setup, but as long at they do not invoke the
+code containing the errors then they expect the rest of the project to
+run normally. AspectJ now allows this mode of operation, and it has the
+additional effect that the state of the project stays consistent, albeit
+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
+
+==== 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
+can be used to produce faster code. Given this setup:
+
+``
+
+....
+enum Colour { RED,GREEN,BLUE;}
+
+@interface ColouredAnnotation { Colour value(); }
+
+@ColouredAnnotation(Colour.RED)
+public void colouredMethod() { }
+....
+
+Current syntax:
+
+....
+before(ColouredAnnotation anno): execution(* *(..)) && @annotation(anno) {
+  printTheColour(anno.value());
+}
+....
+
+New optional syntax:
+
+``
+
+....
+before(Colour col): execution(* *(..)) && @annotation(ColouredAnnotation(col)) {
+  printTheColour(col);
+}
+....
+
+'''''
diff --git a/docs/dist/doc/README-1610.adoc b/docs/dist/doc/README-1610.adoc
new file mode 100644
index 000000000..faf6b85d6
--- /dev/null
+++ b/docs/dist/doc/README-1610.adoc
@@ -0,0 +1,47 @@
+[.small]#© Copyright 2010 Contributors. All rights reserved.#
+
+== AspectJ 1.6.10 Readme
+
+The full list of resolved issues in 1.6.10 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.10;target_milestone=1.6.10M1;target_milestone=1.6.10M2;target_milestone=1.6.10RC1[here]
+
+=== 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
+
+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
+later time (and so generally run with a smaller memory footprint). Type
+demotion is now supported under AJDT in Eclipse and will enable AJDT to
+run with smaller heaps. This feature is still experimental and needs
+turning ON if you want to try it out. To turn it on, open your AspectJ
+project properties in eclipse and in the AspectJ Compiler section,
+scroll down to 'Other' and in the non-standard compiler options setting,
+specify:
+
+....
+-Xset:minimalModel=true,typeDemotion=true
+....
+
+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
+
+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
+AspectJ. 1.6.10 includes some new changes to the aspectjrt.jar. The
+changes are new methods that enable the woven code to be a little
+shorter/neater. As we want to continue to have compatibility with older
+aspectjrt.jar a user needs to choose to activate these optimizations by
+specifying the option: -Xset:targetRuntime1_6_10=true. With that option
+on you will need to ensure you run against the aspectjrt.jar from a
+1.6.10 build.
+
+The changes are discussed in
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=323438[bug 323438]
diff --git a/docs/dist/doc/README-1611.adoc b/docs/dist/doc/README-1611.adoc
new file mode 100644
index 000000000..e240e36f4
--- /dev/null
+++ b/docs/dist/doc/README-1611.adoc
@@ -0,0 +1,106 @@
+[.small]#© Copyright 2010-2011 Contributors. All rights reserved.#
+
+== AspectJ 1.6.11 Readme
+
+The full list of resolved issues in 1.6.11 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.11;[here]
+
+.
+
+=== 1.6.11 available 15-03-2011
+
+=== Notable Changes
+
+==== 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
+avoid this completely we now have our own XML parser inside for
+processing this files. It is basic but should support all the known
+syntax we have for aop files. To use it instead of the default (if you
+are encountering the deadlock) you need to specify this system property:
+org.aspectj.weaver.loadtime.configuration.lightxmlparser=true.
+
+'''''
+
+==== 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
+they are used when doing compile time weaving or load time weaving.
+However in some configurations, e.g. pointcut matching under Spring, a
+single world instance may be getting accessed by multiple threads at the
+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
+
+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
+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
+
+More changes have been made for users trying out the
+-Xset:minimalModel=true option to try and reduce the memory used in
+their Eclipse/AJDT configurations. This option is discussed in detail
+http://andrewclement.blogspot.com/2010/07/ajdt-memory-usage-reduction.html[here].
+It now saves even more memory. Also, previously the amount of memory it
+recovered depended on compilation order (which the user has no control
+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
+
+AspectJ had problems if the paths it was being passed (e.g. aspectpath)
+included spaces. This is bug
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=282379[282379] and has now
+been fixed.
+
+'''''
+
+==== M1 - Annotation removal
+
+Traditionally AspectJ has taken an additive approach, where
+methods/fields/supertypes/annotations can only be added to types. Now,
+chaos would likely ensue if we allowed removal of supertypes, methods,
+etc, but we are seeing an increasing number of requirements to do more
+with annotations. What kinds of thing? Basically remove existing
+annotations, or modify existing annotations by changing their values.
+1.6.11 includes a new piece of syntax that we are thinking might be
+appropriate for one of these scenarios. 1.6.11 supports this:
+
+....
+declare @field: int Foo.i: -@Anno;
+....
+
+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
+
+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
+usefulness. Fixes have gone into 1.6.11 to support binary weaving. What
+do we mean by intertype innertypes? Here is an example:
+
+....
+class Foo {
+  public void m() {
+    System.out.println(Inner.i);
+  }
+}
+
+aspect X {
+  public static class Foo.Inner {
+    static int i = 34;
+  }
+}
+....
+
+Only static inner types are supported.
diff --git a/docs/dist/doc/README-1612.adoc b/docs/dist/doc/README-1612.adoc
new file mode 100644
index 000000000..d69061257
--- /dev/null
+++ b/docs/dist/doc/README-1612.adoc
@@ -0,0 +1,241 @@
+[.small]#© Copyright 2010-2011 Contributors. All rights reserved.#
+
+== AspectJ 1.6.12 Readme
+
+The full list of resolved issues in 1.6.12 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.12;[here]
+
+.
+
+=== 1.6.12 released 18-Oct-2011
+
+=== 1.6.12.RC1 available 3-Oct-2011
+
+=== 1.6.12.M2 available 18-Aug-2011
+
+=== 1.6.12.M1 available 7-Jun-2011
+
+=== Notable Changes
+
+==== RC1 - annotation value matching and !=
+
+Prior to this change it was only possible to specify an annotation match
+like this: +
+ +
+get(@Anno(someValue=1) * *) || get(@Anno(someValue=3) * *) +
+
+Now it is possible to use != and write this: +
+ +
+get(@Anno(someValue!=2) * *) +
+
+This can enable a group of annotated elements to be more easily
+identified. +
+ +
+
+==== 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
+that included an abstract pointcut and some advice attached to that
+abstract pointcut. Then compile this aspect and finally write the XML to
+concretize the abstract pointcut. With 1.6.12 more flexibility has been
+added and for some cases there can be no need for that abstract aspect.
+
+This is a work in progress but now you can write this in the aop.xml:
+
+....
+<concrete-aspect name="MyAspect">
+  <before pointcut="execution(* Hello.say2(..)) AND args(message)"
+   invokeClass="SomeRegularJavaClass" 
+   invokeMethod="someMethod(JoinPoint tjp, java.lang.String message)"/>
+  <after pointcut="execution(* Hello.say2(..)) AND args(message)"
+   invokeClass="SomeRegularJavaClass" 
+   invokeMethod="someOtherMethod(JoinPoint tjp, java.lang.String message)"/>
+</concrete-aspect>
+
+public class SomeRegularJavaClass {
+
+  public static void someMethod(org.aspectj.lang.JoinPoint tjp, String s) {
+    System.out.println("in advice4: s="+s+" at "+tjp);
+  }
+  
+  public static void someOtherMethod(org.aspectj.lang.JoinPoint tjp, String s) {
+    System.out.println("in advice5: s="+s+" at "+tjp);
+  }
+}
+....
+
+In this example there is a simple regular java class containing some
+static methods. In the XML these can be joined to pointcuts, kind as if
+they were advice. Notice in the XML it specifies:
+
+* The pointcut
+* The invokeClass - the fully qualified name of the class containing the
+Java method
+* The invokeMethod - the method, including signature in the specified
+class.
+
+Due to the method specification being in XML the parameter types must be
+fully specified. The only exception to this rule is that the AspectJ
+core types JoinPoint (and JoinPoint.StaticPart) do not have to be fully
+qualified (see the example above). *Important:* notice that in the case
+above which does argument binding, the names are bound according to the
+XML specification, not according to the parameter names in the Java
+code.
+
+Around advice is also supported (the return type of the method must
+match the joinpoint return type). The example shows after advice,
+currently there is no way to specify either after returning or after
+finally, there is only after.
+
+Expanding this further would enable support for all the code style
+features in the XML. Some of the language features like declare
+annotation cannot be done in annotation style aspects but the XML
+doesn't have the same kind of restrictions. If anyone wants to help out
+by fleshing this area of the weaver out, let me know and I'll help you
+get started!
+
+'''''
+
+==== 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.
+Here is an example: ``
+
+....
+aspect X {
+  boolean doit() {
+    System.out.println("In instance check method doit()");
+    return true;
+  }
+
+  before():execution(* m(..)) && if(thisAspectInstance.doit()){
+    System.out.println(thisJoinPoint);
+  }
+}
+....
+
+Now why not just use X.aspectOf() instead of thisAspectInstance? Well
+thisAspectInstance is quite useful when working with abstract/concrete
+aspects: ``
+
+....
+abstract aspect X {
+abstract pointcut p();
+
+boolean doit() {
+    return true;
+  }
+
+  before():p()  && if(thisAspectInstance.doit()){
+    System.out.println(thisJoinPoint);
+  }
+}
+
+aspect Y extends X {
+
+  pointcut p(): execution(* m(..));
+
+}
+....
+
+Now thisAspectInstance will be an instance of the Y, not X. It enables
+the aspect instance to be used in some kind of check/guard that will
+avoid the costly creation of a thisJoinPoint object if the advice isn't
+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
+
+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
+
+The release notes for the last few versions of AspectJ have mentioned
+two options (minimalModel and typeDemotion) which can be switched on to
+reduce memory consumption. They have had enough field testing now and
+from 1.6.12.M2 onwards they are on by default. Users should see a
+reduction in memory consumed by AspectJ projects in AJDT. It won't
+affect load time weaving. It may also help command line (or Ant) compile
+time weaving. If these options cause a problem then please raise a
+bugzilla but in the interim you could work around the problem by
+actively turning them off by specifying
+-Xset:minimalModel=false,typeDemotion=false in the project properties
+for your AspectJ project.
+
+==== 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
+load successfully on a Java7 VM - the attributes were only optional in
+Java6. It is possible to force loading of classes missing the attributes
+but that requires use of a -XX option. AspectJ 1.6.12.M2 should create
+these for you if you weave Java7 level class files. Nothing has been
+done yet to rebase AspectJ on a version of the Eclipse compiler that
+supports Java7 language constructs - that will happen after Eclipse
+3.7.1 is out.
+
+'''''
+
+==== 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:
+
+....
+pointcut p(): execution(!synthetic * *(..));
+....
+
+==== 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]
+
+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]
+
+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
+don't need the annotation, you just need a value from it. This code
+snippet shows an example:
+
+....
+@interface SomeAnnotation {
+  int i();
+}
+
+before(int i): execution(* *(..)) && @annotation(SomeAnnotation(i)) {
+....
+
+Binding values in this way will result in code that runs *much* faster
+than using pointcuts that bind the annotation itself then pull out the
+value.
+
+Under that same bug some changes were made to match values by name when
+binding too. Suppose the annotation had multiple int values, how would
+we select which int to bind? AspectJ will now use the name (if it can)
+to select the right value:
+
+....
+@interface SomeAnnotation {
+  int mods();
+  int flags();
+}
+
+before(int flags): execution(* *(..)) && @annotation(SomeAnnotation(flags)) {
+....
+
+Here the use of 'flags' as the name of the value being bound will ensure
+the 'flags' value from any SomeAnnotation is bound and not the 'mods'
+value.
diff --git a/docs/dist/doc/README-162.adoc b/docs/dist/doc/README-162.adoc
new file mode 100644
index 000000000..f560778a6
--- /dev/null
+++ b/docs/dist/doc/README-162.adoc
@@ -0,0 +1,84 @@
+[.small]#© Copyright 2008 Contributors. All rights reserved.#
+
+== AspectJ 1.6.2 Readme
+
+The main theme of AspectJ1.6.2 was improved IDE incremental performance
+and a number of changes have gone in to improve how AspectJ and AJDT
+communicate - greatly reducing the time taken to perform an incremental
+compile (more details below). 1.6.2 also includes a number of fixes and
+enhancements covering areas such as:
+
+* better support for generics and intertype declarations
+* better support for annotation style syntax
+* improvements to ajdoc
+* bringing the AspectJ structure model more in line with the JDT model
+
+Many thanks to all the users that helped diagnose problems, provide
+testcases and contribute fixes. In particular:
+
+* Dave Whittaker - for generics and intertype declaration testing and
+testcases
+* Jason Naylor, Arturo Salazar - for ajdoc testcases, fixes and design
+input
+* Andrew Eisenberg - for helping shape the AJDT/AspectJ interface and
+improving incremental
+
+The complete list of issues resolved for AspectJ 1.6.2 (more than 60)
+can be found with this bugzilla query:
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.2&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=[Bugs
+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])
+
+Two main changes in this area.
+
+* Better communication between AJDT and AspectJ. The interface between
+the two has been modified so that AJDT can give more input to AspectJ
+about what needs to be done for an incremental compile, rather than
+having AspectJ discover it each time.
+* Structure model changes. The AspectJ structure model (of types in a
+project and the weaving amongst them) allows handles to be created for
+every node, as a lightweight reference to the elements of the model.
+These handles were similar to those that JDT uses for references to
+elements of a project but not identical. Many many fixes have gone in to
+bring the handle formats closer and closer. For example including src
+folders as elements in the AspectJ model and using the fully correct set
+of JDT delimiters throughout each handle. This means there is no longer
+an expensive transformation cost in going from an AspectJ element to its
+related JDT element and no need for AJDT to maintain a more JDT like
+version of the AspectJ structure model. The imminent development builds
+of AJDT will utilise these changes.
+
+_What difference does it make?_
+
+For every kind of build there are two numbers to take into account.
+Firstly there is the time spent in the compiler (time spent compiling
+and weaving), secondly there is the time spent in AJDT (time spent
+communicating what happened back to the user via the problems view,
+gutter annotations). Values for these times can be seen by opening the
+'AJDT Event Trace View' in eclipse. The changes within AspectJ obviously
+effect the time spent in the compiler and that is described as 'time
+spent in AJDE' within the event trace view (AJDE being the compiler
+wrapper invoked by AJDT).
+
+For a 1000 source file AspectJ project, the times spent in AJDE have
+changed as follows for a single whitespace change and save operation:
+
+* For a sourcefile unaffected by aspects. Was 1828ms, now 75ms.
+* For a sourcefile affected by some advice. Was 1844ms, now 90ms.
+* For a sourcefile affected by lots of advice. Was 1937ms, now 188ms.
+
+The AspectJ changes are done to support this, but we are still bedding
+them down in AJDT. If you want to see numbers like those above you need
+to install the latest AJDT dev builds for Eclipse 3.4 (an AJDT 1.6.1 dev
+build from the dev update site:
+http://download.eclipse.org/tools/ajdt/34/dev/update ) and then after
+starting Eclipse, select 'Window>Preferences' and in the AspectJ tab
+select 'Incremental Compiler Optimizations'. Let us know how you get on!
+When it has had enough testing it will be made the default and then is
+likely to be back ported to Eclipse 3.3 AJDT.
+
+'''''
diff --git a/docs/dist/doc/README-163.adoc b/docs/dist/doc/README-163.adoc
new file mode 100644
index 000000000..74ca5e5a4
--- /dev/null
+++ b/docs/dist/doc/README-163.adoc
@@ -0,0 +1,90 @@
+[.small]#© Copyright 2008 Contributors. All rights reserved.#
+
+== AspectJ 1.6.3 Readme
+
+* xref:#split[Split matching/weaving]
+* xref:#bugsfixed[Bugs fixed]
+* xref:#notable[Notable bug fixes]
+* xref:#whatsnext[What's next?]
+
+'''''
+
+[#split]##
+
+=== 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.
+This matcher would enable reuse of the semantics of AspectJ pointcut
+matching without including the unnecessary code that is the weaver. Why?
+In some environments, for example Spring AOP, the weaving may be done in
+an entirely different way and the default weaver included in
+aspectjweaver.jar is just unnecessary code. Some users also find they
+have trouble getting approval for using the 'aspectjweaver.jar' in their
+projects because it includes a bytecode modification library, even when
+they are not using that code.
+
+The result of this work is documented in
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=246125[bug 246125] and
+there is now a new jar file in the distribution called
+org.aspectj.matcher.jar that includes a first pass at the matching code.
+It is not quite as slimmed down as it could be but is a first pass that
+includes no bytecode modification toolkit.
+
+To use this matcher standalone it simply requires an abstraction of some
+type system to be plugged in. The matcher code can then be used to parse
+standard pointcuts and answer questions about whether they match against
+that type system. There is no documentation on how to do this yet, as we
+don't think many users will be contributing new type systems, but
+internally we are working on an Eclipse JDT type system abstraction that
+will enable us to show matches in AJDT without actually compiling code
+(currently the two type system abstractions we ship are bytecode based
+and reflection based - both of which require compilation).
+
+'''''
+
+[#bugsfixed]##
+
+=== Bugs fixed
+
+The complete list of issues resolved for AspectJ 1.6.3 (more than 50)
+can be found with this bugzilla query:
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.3&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=[Bugs
+resolved]
+
+During 2008, there have been four AspectJ releases, fixing almost 200
+issues.
+
+'''''
+
+[#notable]##
+
+=== Notable bug fixes
+
+* More improvements to the way AspectJ/AJDT communicate (251277, 249216,
+258325)
+* More ajdoc improvements (256514)
+* Better support for non standard annotation style parameter ordering
+(164573, 219419)
+* Fixed long standing issue with extending Spring SecurityInterceptor
+(252722)
+* Ensure parameter annotations made on an ITD reach the target affected
+type (256669)
+
+'''''
+
+[#whatsnext]##
+
+=== 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.
+Some improved syntax for intertype declarations is a possible candidate
+feature (see discussion in
+http://dev.eclipse.org/mhonarc/lists/aspectj-users/msg10208.html[this
+mailing list thread]). A possible introduction of a code style syntax
+for the mixin style that is @DeclareParents (and a renaming of
+@DeclareParents to perhaps DeclareMixin or DeclareDelegate).
+
+'''''
diff --git a/docs/dist/doc/README-164.adoc b/docs/dist/doc/README-164.adoc
new file mode 100644
index 000000000..dd5deea5a
--- /dev/null
+++ b/docs/dist/doc/README-164.adoc
@@ -0,0 +1,256 @@
+[.small]#© Copyright 2009 Contributors. All rights reserved.#
+
+== AspectJ 1.6.4 Readme
+
+* xref:#compilation[Compilation times]
+* xref:#language[Language enhancements]
+* xref:#bugsfixed[Bugs fixed]
+* xref:#whatsnext[What's next?]
+
+'''''
+
+[#compilation]##
+
+=== 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
+incremental builds), improved support for multiple-project
+configurations, and improved feedback in the editor. The following
+sections go into details on each of those topics.
+
+*Full Compilation*
+
+As an example project, all the measurements here are based on the
+modified JDT compiler that AspectJ uses internally. It is 1100 source
+files and includes aspects that affect around 850 join points. Here are
+the full build times in AJDT:
+
+AJDT 1.6.3 (uses AspectJ 1.6.3)
+
+``
+
+....
+21352ms
+21597ms
+21502ms
+....
+
+AJDT 1.6.5dev builds (use AspectJ 1.6.4)
+
+``
+
+....
+19811ms
+19802ms
+19504ms
+....
+
+About 1.5-2 seconds faster for this example.
+
+*Incremental Compilation and multi-project scenarios*
+
+In most common project configurations there are multiple eclipse
+projects in some kind of dependency hierarchy. Depending on what changes
+in a top level project, those downstream may need to be rebuilt. The
+analysis around this area has greatly improved in AspectJ 1.6.4, and
+this has resulted in much reduced incremental build times. The example
+timed here is around 20 AspectJ projects in a hierarchy, and a change is
+made to a source file in the top level project and build times are
+observed for the downstream projects.
+
+The timings reported here are accessible to anyone with AJDT installed -
+just open the 'AJDT Event Trace View' and it will report ongoing
+information about what the compiler/weaver and AJDT are up to. Be aware
+that data is only recorded in this view if it is open - so for optimal
+performance it should be shutdown, but it is useful for debugging
+scenarios or collecting basic benchmark numbers. Within the event trace
+view output, the time recorded for 'time spent in AJDE' represents the
+time spent in the compiler: analysing what has changed on the classpath,
+building code, weaving code.
+
+Initially this is using AJDT 1.6.2 (which embeds AspectJ 1.6.3):
+
+``
+
+....
+Type of change: adding a new method to a type
+Project build times (first one is the compile of our change, the rest are for downstream projects):
+462ms, 4ms, 145ms, 8ms, 9ms, 287ms, 471ms, 222ms, 1028ms, 143ms, 505ms, 199ms, 261ms, 1224ms,
+321ms, 704ms, 75ms, 233ms, 257ms
+Summary: Total time spent in the compiler for that change: 6558ms
+---
+Type of change: whitespace change (adding just a harmless space character)
+Project build times (first one is the compile of our change, the rest are for downstream projects):
+229ms, 5ms, 10ms, 9ms, 10ms, 79ms, 43ms, 62ms, 80ms, 37ms, 64ms, 32ms, 79ms,
+154ms, 94ms, 189ms, 72ms, 144ms, 205ms
+Summary: Total time spent in the compiler for that change: 1597ms
+....
+
+Now with AspectJ 1.6.5 dev builds (which embed AspectJ 1.6.4):
+
+``
+
+....
+Type of change: adding a new method to a type
+Project build times (first one is the compile of our change, the rest are for downstream projects):
+288ms, 3ms, 143ms, 2ms, 2ms, 162ms, 244ms, 89ms, 489ms, 113ms, 277ms, 108ms, 143ms, 626ms,
+135ms, 260ms, 2ms, 96ms, 6ms
+Summary: Total time spent in the compiler for that change: 3188ms down from 6558ms
+
+Type of change: whitespace change (adding just a harmless space character)
+Project build times (first one is the compile of our change, the rest are for downstream projects):
+101ms, 1ms, 1ms, 1ms, 0ms, 1ms, 1ms, 1ms, 1ms, 1ms, 0ms, 1ms, 1ms, 2ms, 0ms, 1ms, 0ms, 2ms, 2ms
+Summary: Total time spent in the compiler for that change: 118ms (down from 1597ms)
+....
+
+Improvements all round, and almost instant builds now for whitespace
+changes, even in large project setups.
+
+In addition the compilation times are also improved in situations where
+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
+
+Under https://bugs.eclipse.org/bugs/show_bug.cgi?id=246393[bug 246393]
+the problem has been addressed where sometimes spurious errors would
+appear throughout the editor for a file in AJDT when just one single
+simple syntax errors exists. More detail on this problem can be found
+http://andrewclement.blogspot.com/2009/02/aspectj-fixing-reverse-cascade-errors.html[here].
+
+'''''
+
+[#language]##
+
+=== Language Enhancements
+
+*Optimizing support for maintaining per join point state*
+
+The traditional way to maintain state on a per join point basis involves
+using the JoinPoint.StaticPart as a key into a map: ``
+
+....
+aspect X pertypewithin(*) {
+  Map<JoinPoint.StaticPart,Timer> timerMap = ...
+
+  Object around(): execution(public * *(..)) {
+    Timer timerToUse = timerMap.get(thisJoinPointStaticPart);
+    timerToUse.start();
+    Object o =  proceed();
+    timerToUse.stop();
+    return o;
+  }
+}
+....
+
+These map lookups are slow. In AspectJ 1.6.4 there is a new getId()
+method on the JoinPoint.StaticPart object. The ids for all affected join
+points within a target type are unique (and start from 0) - they are
+ideal for array lookups. So using this the above aspect can be
+rewritten:
+
+``
+
+....
+aspect X pertypewithin(*) {
+  Timer[] timerArray = ...
+
+  Object around(): execution(public * *(..)) {
+    Timer timerToUse = timerArray[thisJoinPointStaticPart.getId()];
+    timerToUse.start();
+    Object o =  proceed();
+    timerToUse.stop();
+    return o;
+  }
+}
+....
+
+much faster. Just be aware that the ids are only unique within an
+affected target type - hence the use of pertypewithin in this example to
+ensure there is an aspect instance (and so a different array) for each
+advised type.
+
+See related https://bugs.eclipse.org/bugs/show_bug.cgi?id=89009[bug
+89009] for the full discussion
+
+=== @DeclareMixin
+
+The annotation style declare parents support (@DeclareParents) has been
+(rightly) criticized because it really does not offer an equivalent to
+what is possible with code style declare parents, it really offers a
+mixin strategy. It also has limitations such as the delegate instance
+used to satisfy any method invocations on an affected target cannot
+access the object instance for which it is acting as a delegate. To
+address these concerns a proper mixin notation has been introduced that
+makes it more clear that a mixin strategy is being employed and it
+addresses the problem of the mixin delegate accessing the affected
+target instance.
+
+The @DeclareMixin annotation is attached to a factory method which
+returns instances of the delegate. Here is a basic example:
+
+``
+
+....
+        // The factory method that can build the delegate instance is annotated with @DeclareMixin.
+        // The annotation value defines the type pattern for targets of the mixin.
+        // The parameter is the object for which a delegate is being constructed.
+        // The interface that will be mixed in is the return value of the factory method.
+        @DeclareMixin("org.xyz..*")
+        public static SomeInterface createDelegate(Object instance) {
+          return new SomeImplementation(instance);
+        }
+....
+
+More examples are
+http://www.eclipse.org/aspectj/doc/released/adk15notebook/ataspectj-itds.html[here
+in the online documentation].
+
+Going forward attempts will be made to try and make @DeclareParents
+behave more like code style - if this cannot be done it is likely to be
+deprecated.
+
+'''''
+
+[#bugsfixed]##
+
+=== Bugs fixed
+
+The complete list of issues resolved for AspectJ 1.6.4 (more than 70)
+can be found with this bugzilla query:
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.4&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=[Bugs
+resolved]
+
+'''''
+
+[#whatsnext]##
+
+=== What's next?
+
+*More incremental build enhancements*
+
+A number of situations still exist where incremental compile speeds
+still needs optimizing, particular when capabilities like aspectpath or
+inpath are used.
+
+*Build state persistence*
+
+Between restarts of Eclipse the state of each project is not recorded -
+hence full builds are required upon restart. The state (and associated
+relationship model) should be persisted between restarts, but both of
+these need a review first to ensure they are not larger than they need
+to be.
+
+*Memory consumption*
+
+Both for source compilation and load-time weaving scenarios. The size of
+the model in the IDE needs reviewing, and also the type map within the
+weaver. Although the type map uses Weak/Soft references to try and
+better control how it uses memory, the JVM policies for managing these
+references vary wildly and so some work needs to be done to allow for
+these differences.
+
+'''''
diff --git a/docs/dist/doc/README-165.adoc b/docs/dist/doc/README-165.adoc
new file mode 100644
index 000000000..4d52fc0eb
--- /dev/null
+++ b/docs/dist/doc/README-165.adoc
@@ -0,0 +1,15 @@
+[.small]#© Copyright 2009 Contributors. All rights reserved.#
+
+== AspectJ 1.6.5 Readme
+
+[#bugsfixed]##
+
+=== Bugs fixed
+
+The complete list of issues resolved for AspectJ 1.6.5 can be found with
+this bugzilla query:
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.5&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=[Bugs
+resolved]
+
+'''''
diff --git a/docs/dist/doc/README-166.adoc b/docs/dist/doc/README-166.adoc
new file mode 100644
index 000000000..9064cb793
--- /dev/null
+++ b/docs/dist/doc/README-166.adoc
@@ -0,0 +1,65 @@
+[.small]#© Copyright 2009 Contributors. All rights reserved.#
+
+== AspectJ 1.6.6 Readme
+
+[#bugsfixed]##
+
+=== Bugs fixed
+
+The complete list of issues resolved for AspectJ 1.6.6 can be found with
+this bugzilla query:
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.6&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=[Bugs
+resolved]
+
+'''''
+
+=== Changes
+
+*Java5*
+
+The features of Java5 (generics, autoboxing, covariance, etc) are being
+exploited in the AspectJ codebase. This does not in any way change the
+generated code or supported source code, or the dependencies that code
+has, but it *does* mean that AspectJ requires Java5 in order to run. The
+ability to use typed collections has already flushed out a few issues
+within the codebase, improving the quality of AspectJ.
+
+ +
+
+*Closing streams*
+
+Some routes through AspectJ were leaving inputstreams open and this has
+now been fixed. For example if supplying a user written configuration
+file for Lint options. Thanks to Michael Pradel for supplying patches to
+fix these issues.
+
+ +
+
+*Concurrency (281654)*
+
+Fix to address a problem seen when using the weaver in a highly
+concurrent environment. Thanks to Kristian Rosenvold for the patch.
+
+ +
+
+*Incremental compilation*
+
+A few fixes to problems seen only on incremental builds, problem areas
+included:
+
+* problems when fully qualifying the target type in an intertype
+declaration (269652)
+* problems when using annotation style pointcuts and reference pointcuts
+together (286341)
+
+ +
+
+*JavadocRunner in NetBeans*
+
+Fixed by a patch from Joseph A. Levin - thanks!
+
+ +
+
+*Various fixes/enhancements to the structure model to fix issues with
+feedback on weaving in AJDT*
diff --git a/docs/dist/doc/README-167.adoc b/docs/dist/doc/README-167.adoc
new file mode 100644
index 000000000..a6fea804f
--- /dev/null
+++ b/docs/dist/doc/README-167.adoc
@@ -0,0 +1,183 @@
+[.small]#© Copyright 2009 Contributors. All rights reserved.#
+
+== AspectJ 1.6.7 Readme
+
+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
+
+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
+it is possible to turn on timers for pointcuts. These timers show the
+time spent in the weaver matching the pointcut components against join
+points. The details on this feature are here:
+http://andrewclement.blogspot.com/2009/11/aspectj-profiling-pointcut-matching.html[Profiling
+pointcut matching]. Basically by turning on the options '-timers
+-verbose' on the command line (or via Ant), output will be produced that
+looks a little like this:
+
+....
+Pointcut matching cost (total=6532ms for 675000 joinpoint match calls):
+Time:482ms (jps:#168585) matching against 
+    (staticinitialization(*y*.()) && persingleton(SimpleAspect))
+Time:3970ms (jps:#168585) matching against 
+    (execution(* *t*.*(*)) && persingleton(SimpleAspect))
+Time:538ms (jps:#168584) matching against 
+    (execution(* *f*(..)) && persingleton(SimpleAspect))
+Time:1536ms (jps:#168584) matching against 
+    (execution(* java.lang.CharSequence+.*e*(..)) && persingleton(SimpleAspect))
+Time:4ms (jps:#662) matching against 
+    (within(*p*) && persingleton(SimpleAspect))
+....
+
+It shows the component, the number of joinpoints (jps) the weaver
+attempted to match it against and how many milliseconds were spent
+performing those matches. The options can also be turned on
+http://contraptionsforprogramming.blogspot.com/2009/11/getting-aspectj-pointcut-matching-timer.html[]through
+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
+
+The changes to enable pointcut profiling enabled some targeted work to
+be done on the matching algorithms. These have remained unchanged for a
+few years, but in 1.6.7 have received a bit of an overhaul. 'Fast match'
+has been implemented for the execution() pointcut, drastically reducing
+weave times for heavy users of execution - more details
+http://andrewclement.blogspot.com/2009/11/aspectj-how-much-faster-is-aspectj-167.html[here].
+The pointcut cost calculator (which is used to sort pointcuts to
+optimize matching speed) has been reviewed and after determining that
+this() ought to be considered cheaper than call() - any user combining
+those two pointcut designators should see an improvement (one users
+build time reduced from 38minutes to 6minutes with that change!).
+
+As well as faster matching there is also less exploration to determine a
+match. Visitors that walk hierarchies and discover methods now terminate
+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
+
+The processing of include/exclude entries in aop.xml has been rewritten.
+It now optimizes for many more common patterns. If a pattern is
+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
+
+A number of options were previously configurable for load time weaving
+that were considered experimental. These options have now been tested
+enough in the field that they are considered fully reliable and are on
+by default in 1.6.7. If you have been using either of these:
+
+* typeDemotion
+* runMinimalMemory
+
+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
+
+All those changes above, and some additional tweaks, mean we are now
+using less memory than ever before and getting things done more quickly.
+
+http://andrewclement.blogspot.com/2009/12/aspectj-167-and-faster-load-time.html[This
+post] discusses the details. From that article, the graph below shows
+the speed and memory consumption of the various AspectJ 1.6 releases
+when load time weaving a small application loading in Tomcat. For each
+of 10 iterations (x axis), the top comparison is startup time in
+milliseconds, the lower comparison is memory used in bytes.
+
+image:167Memory.png[image]
+
+=== 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
+performance of annotation binding. His case uncovered an old TODO left
+in the code a few years ago:
+
+``
+
+....
+// OPTIMIZE cache result of getDeclaredMethod and getAnnotation?
+....
+
+Annotation binding has become a very common use case since that was
+written and 1.6.7 was the time TODO it.
+
+The result is an optimization for the general case of binding an
+annotation, but also support for a new bit of syntax that aids binding
+of a string annotation member value - using this latter syntax generates
+extremely fast code.
+
+Here are some numbers for a simple benchmark retrieving the annotation
+value at an execution join point in different ways. The three scenarios
+look like this (where the annotation type is 'Marker' and it has a
+String value field called 'message'):
+
+``
+
+....
+  // CaseOne: annotation value fetching is done in the advice:
+  pointcut adviceRetrievesAnnotation(): execution(@Marker * runOne(..));
+  before(): adviceRetrievesAnnotation() {
+    Marker marker = (Marker) ((MethodSignature)
+        thisJoinPointStaticPart.getSignature()).getMethod().getAnnotation(Marker.class);
+    String s = marker.message();
+  }
+
+  // CaseTwo: annotation binding is done in the pointcut, advice retrieves message
+  pointcut pointcutBindsAnnotation(Marker l): execution(@Marker * runTwo(..)) && @annotation(l);
+  before(Marker l): pointcutBindsAnnotation(l) {
+    String s = l.message();
+  }
+
+  // CaseThree: annotation binding directly targets the message value in the annotation
+  pointcut pointcutBindsAnnotationValue(String msg):
+    execution(@Marker * runThree(..)) && @annotation(Marker(msg));
+  before(String s): pointcutBindsAnnotationValue(s) {
+    // already got the string
+  }
+....
+
+Before 1.6.7, case 2 was slower than case 1 and case 3 wasn't supported
+syntax. The two bugs with more info are
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=296484[Bug 296484] and
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=296501[Bug 296501].
+
+Now this is a micro benchmark, slightly unrepresentative of the real
+world because the advice isn't doing anything else, but it does really
+stress the AspectJ binding code. For the benchmark numbers the join
+points advised by those advice were invoked 1,000,000 times. AspectJ
+1.6.7:
+
+``
+
+....
+Manually fetching annotation with getAnnotation(): 645ms
+Binding annotation with @annotation(Marker): 445ms  (was >20 *seconds* for 1.6.6, due to an extra reflection call)
+Binding annotation value with @annotation(Marker(message)): 3ms
+....
+
+The new syntax is definetly the best way to bind an annotation string
+value.
+
+'''''
+
+[#bugsfixed]##
+
+==== Bugs fixed
+
+The complete list of issues resolved for AspectJ 1.6.7 can be found with
+this bugzilla query:
+
+* https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=AspectJ&target_milestone=1.6.7&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=[Bugs
+resolved]
+
+'''''
diff --git a/docs/dist/doc/README-168.adoc b/docs/dist/doc/README-168.adoc
new file mode 100644
index 000000000..eee958509
--- /dev/null
+++ b/docs/dist/doc/README-168.adoc
@@ -0,0 +1,89 @@
+[.small]#© Copyright 2009 Contributors. All rights reserved.#
+
+== AspectJ 1.6.8 Readme
+
+The first sentence in the 1.6.7 readme was 'AspectJ 1.6.7 includes some
+radical internal changes.'
+
+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
+
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298786[Bug 298786]
+
+Basically, if a certain combination of includes and excludes were
+specified in the within section, then the weaver would fail to merge
+them correctly. The conditions for the failure are:
+
+* you need an exclude pattern that the weaver is not optimizing for
+(basically a pattern that could not be matched based upon the typename
+alone, eg. based on whether the type has an annotation)
+* you need two include patterns - one that is being optimized and one
+that is not
+
+These three meet that spec:
+
+``
+
+....
+    <include within="*"/>
+    <include within="@Foo *"/>
+    <exclude within="*Funk*y*"/>
+....
+
+The include="*" can be optimized. The include="@Foo *" is not optimized.
+The exclude="*Funk*y*" is not optimized (this one could be but isn't
+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()
+
+See https://bugs.eclipse.org/bugs/show_bug.cgi?id=298908[Bug 298908]
+
+This is actually a problem AspectJ has had for a long time, but has
+always proved elusive to recreate. It turns out that it is memory
+related and the more aggressive policy in 1.6.7 causes it to occur much
+more frequently.
+
+The stack trace when this is hit looks like:
+
+``
+
+....
+    ...
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+    at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+    ...
+....
+
+The weaver has changed over the 1.5 and 1.6 releases and is now reaching
+a point where it really shrinks quite small when not in use (maybe in a
+loadtime environment you have finished loading all your classes). The
+aim is that it can rebuild any required state that is needed later. With
+the move in 1.6.7 from Soft to Weak references, things are being
+discarded much sooner and this is exercising the state rebuilding code
+that wasn't used that often prior to 1.6.7.
+
+The problem is actually because the call on a generic type to get the
+raw type was actually broken and returning the generic type. This then
+loops forever trying to get the raw type from the generic type. This
+happens because the world should store only raw types (which point to
+their generic form) but there was a bug in state rebuilding that instead
+put the generic type directly in the world.
+
+'''''
+
+Thanks to everyone who helped get to the bottom of these problems.
diff --git a/docs/dist/doc/README-169.adoc b/docs/dist/doc/README-169.adoc
new file mode 100644
index 000000000..1df44489f
--- /dev/null
+++ b/docs/dist/doc/README-169.adoc
@@ -0,0 +1,299 @@
+[.small]#© Copyright 2010 Contributors. All rights reserved.#
+
+== AspectJ 1.6.9 Readme
+
+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
+
+==== 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,
+if you wanted to attach an annotation to all your getter like methods,
+you needed two constructs
+
+....
+declare @method: * is*(): @FooBar;
+declare @method: * get*(): @FooBar;
+....
+
+Now AspectJ allows compound patterns for declare
+@method/@constructor/@field.
+
+....
+declare @method: (* is*()) || (* get*()): @FooBar;
+....
+
+==== 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
+type Foo:
+
+....
+public class Foo {
+    public static void main(String[] args) {
+        new Inner().run();
+    }
+}
+
+aspect Magic {
+    public static class Foo.Inner {
+        public void run() {
+            System.out.println("Inner.run() executing");
+        }
+    }
+}
+....
+
+Only static member types are supported.
+
+==== '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
+containing a multitude of aspects that attach different technologies
+(transactions/persistence/etc) to your application. Normally an aspect
+will fail with a "can't find type" style message if a weaver is told to
+use it and yet it references some missing dependency. This can be
+annoying and require you to include jars on your classpath (or in your
+maven configuration) that you don't actually use, they are *only* there
+to avoid problems with the aspect. In 1.6.9 you can add a setting to
+these aspects in the aop.xml that makes them optional. The setting
+mentions a type and if that type cannot be found the aspect immediately
+shuts itself down. This basically means that the aspect is only going to
+do its job if the type being mentioned in the setting is around. This
+enables the aspect library to be on the aspect path but any aspects
+within it to switch-off if there is nothing for them to do.
+
+Here is an example, 'AspectA' will switch itself off if the type
+'a.b.c.Anno' cannot be found:
+
+``
+
+....
+ <aspect name="AspectA" requires="a.b.c.Anno"/>
+....
+
+==== 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
+but basically some work has been done to improve the serialized form of
+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]
+
+In a further step towards transparent weaving, support for the AjType
+reflection system is now being made optional. This means if intending to
+use the AjTypeSystem to reflect on woven code, then the code must be
+built with the option -makeAjReflectable. This change is being made
+because the reflection supporting metadata that enables the AjTypeSystem
+to work can break other tools that are just using regular reflection on
+the classes. These days many more users are processing classes using
+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]
+
+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
+alternative to reweaving when needing to weave a class multiple times.
+Overweaving can cope with 'other tools' modifying the bytecode in
+between AspectJ weaves, whereas reweaving cannot. More details are in
+the related bugzilla
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=293450[293450] and in this
+http://andrewclement.blogspot.com/2010/05/aspectj-overweaving.html[blog
+article]. A weaver is switched into overweaving mode by the option
+-Xset:overWeaving=true - which can be specified on the command line or
+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]
+
+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
+those not aware of it, it is the ability to specify a scope against
+aspects defined in your loadtime weaving aop.xml file. A scope
+effectively enables the user to limit the applicability of your aspect
+to some subset of all those types included by the weaver include
+section. Why is it needed? It can be useful when taking an aspect that
+did not originally scope itself properly (using a within clause) and
+needing to limit its effect in a load time weaving context. Think of it
+as a within pattern that you can put into the aop.xml that augments all
+the pointcuts defined in the original aspect.
+
+Here is an example:
+
+``
+
+....
+<aspectj>
+  <aspects>
+    <aspect name="X"/>
+    <aspect name="Y" scope="com.foo..*"/>
+  </aspects>
+  <weaver>
+    <include within="com..*"/>
+  </weaver>
+</aspectj>
+....
+
+In this example the weaver include section specifies all the types in
+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
+
+It is now possible to use joinpoint context in the messages attached to
+declare warning and declare error constructs. Some examples:
+
+``
+
+....
+declare warning: execution(* A.m(..)): "joinpoint is {joinpoint}";
+declare warning: execution(* A.m(..)): "joinpoint kind is '{joinpoint.kind}'";
+declare warning: get(int *) && within(A): "joinpoint signature is {joinpoint.signature}";
+declare warning: execution(* A.m(..)): "joinpoint declaring type is {joinpoint.signature.declaringType}";
+declare warning: execution(* A.m(..)): "signature name for method is {joinpoint.signature.name}";
+declare warning: execution(* A.m(..)): "joinpoint location is {joinpoint.sourcelocation.sourcefile}:{joinpoint.sourcelocation.line}";
+declare warning: execution(* A.m(..)): "joinpoint line is '{joinpoint.sourcelocation.line}'";
+
+declare warning: get(int *): "warning is from aspect {advice.aspecttype}";
+declare warning: execution(* A.m(..)): "warning sourcelocation is {advice.sourcelocation.sourcefile}:{advice.sourcelocation.line}";
+....
+
+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
+
+It is now possible to use a type pattern with declare warning and
+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
+
+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
+new is() construct that enables this:
+
+``
+
+....
+execution(* (!is(InnerType)).m(..)) {}
+!within(* && is(InnerType)) {}
+....
+
+Options for use in is() are: ClassType, AspectType, InterfaceType,
+InnerType, AnonymousType, EnumType, AnonymousType.
+
+Note: It is important to understand that "!within(is(InnerType))" and
+"within(!is(InnerType))" are not the same. The latter one is unlikely to
+be what you want to use. For example here: ``
+
+....
+class Boo {
+  void foo() {}
+  class Bar {
+    void foo() {}
+  }
+}
+....
+
+Bar.foo() will match within(!is(InnerType)) because within considers all
+surrounding types (so although Bar doesn't match the pattern, the
+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
+
+Some users always expect this:
+
+``
+
+....
+class C {
+}
+
+aspect X {
+  private int C.someField;
+}
+....
+
+To cause a private field called 'someField' to be added to C. This is
+conceptually what happens during compilation but if any user then later
+attempts to access someField via reflection or runs a javap against the
+class file, they will see that isn't what happens in practice. A public
+member is added with a mangled name. For code attempting to access
+someField built with ajc, the visibility of the declaration will, of
+course, be respected. But for frameworks accessing the code later
+(typically through reflection), it can cause confusion. With AspectJ
+1.6.9 the name and visibility are now preserved. Compile time semantics
+remain the same, it is only the weaving process that has changed to
+produce slightly different output.
+
+Here is the output of javap when that is built with 1.6.8:
+
+``
+
+....
+class C extends java.lang.Object{
+    public int ajc$interField$X$someField;
+    C();
+}
+....
+
+Here is the output of javap when that is built with 1.6.9:
+
+``
+
+....
+class C extends java.lang.Object{
+    private int someField;
+    C();
+    public static int ajc$get$someField(C);
+    public static void ajc$set$someField(C, int);
+}
+....
+
+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
+
+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
+it is also put into the maven.springframework.org repo. The maven
+compatible repo is `maven.springframework.org/snapshot/org/aspectj` -
+and if you browse to it you will see it currently contains 1.6.9 dev
+builds under the name 1.6.9.BUILD-SNAPSHOT. The repo is added with this
+magic:
+
+``
+
+....
+<repository>
+    <id>maven.springframework.org</id>
+    <name>SpringSource snapshots</name>
+    <url>http://maven.springframework.org/snapshot</url>
+</repository>
+....
+
+and then the version to depend upon is: 1.6.9.BUILD-SNAPSHOT
+
+'''''
diff --git a/docs/dist/doc/README-170.adoc b/docs/dist/doc/README-170.adoc
new file mode 100644
index 000000000..de0248de7
--- /dev/null
+++ b/docs/dist/doc/README-170.adoc
@@ -0,0 +1,118 @@
+[.small]#© Copyright 2011 Contributors. All rights reserved.#
+
+== AspectJ 1.7.0 Readme
+
+The full list of resolved issues in 1.7.0 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.7.0;[here]
+
+.
+
+* 1.7.0 available 2-Jul-2012
+* 1.7.0.RC1 available 25-May-2012
+* 1.7.0.M1 available 16-Dec-2011
+
+=== Notable Changes
+
+==== 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
+some of the new features that were allowed by Java 1.7. In particular
+this meant any bytecode containing the INVOKEDYNAMIC (new instruction
+for 1.7) and the related new constant pool entry types that support it.
+RC1 now supports weaving into bytecode containing these features.
+However, the new INVOKEDYNAMIC instruction does not surface as a join
+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
+
+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
+cache for loadtime weaving. The details and some rudimentary benchmark
+numbers are in the bug. Basically it caches woven bytecode on first
+start of a system using LTW and then reuses that woven bytecode on
+subsequent starts - this saves weaving time and also memory consumption.
+To activate it, use the following system properties:
+
+....
+-Daj.weaving.cache.enabled=true
+-Daj.weaving.cache.dir=/tmp/aspectj-cache/
+....
+
+==== 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
+big change where AspectJ is picking up four years of change from the
+Eclipse compiler.
+
+It means that you can now use the new Java 7 language constructs in your
+programs:
+
+- Diamond operator in advice: ``
+
+....
+aspect Foo {
+  before(): execution(* *(..)) {
+    List ls = new ArrayList<>();
+  }
+}
+....
+
+- Diamond operator in ITD: ``
+
+....
+public List DiamondITD.ls = new ArrayList<>();
+....
+
+- Underscore literals and binary literals in advice: ``
+
+....
+  before(): execution(* *(..)) {
+    int onemill = 1_000_000;
+    int four =0b100;
+  }
+....
+
+- Multi-catch:``
+
+....
+before(): execution(* main(..)) {
+    try {
+      foo("abc");
+    } catch (ExceptionA | ExceptionB ex) {
+      bar(ex);
+    }
+}
+....
+
+- String switch:``
+
+....
+ before(String s): execution(* *(..)) && args(s) {
+   switch(s) {
+     case "quux":
+       foo();
+       break;
+     case "bar":
+       foo();
+       break;
+     default:
+       foo();
+       break;
+   }
+ }
+....
+
+- Try with resources:``
+
+....
+   try (
+     InputStream in = new FileInputStream(src);
+     OutputStream out = new FileOutputStream(dest))
+   {
+     // code
+   }
+....
diff --git a/docs/dist/doc/README-171.adoc b/docs/dist/doc/README-171.adoc
new file mode 100644
index 000000000..81712abc7
--- /dev/null
+++ b/docs/dist/doc/README-171.adoc
@@ -0,0 +1,36 @@
+[.small]#© Copyright 2011 Contributors. All rights reserved.#
+
+== AspectJ 1.7.1 Readme
+
+The full list of resolved issues in 1.7.1 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.7.1;[here]
+
+.
+
+* 1.7.1 available 6-Sep-2012
+
+=== Changes
+
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=388971[388971] Double
+Synthetic attributes on some around advice members +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=387718[387718]
+RuntimeException when trying to compile broken code +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=387568[387568] Warning
+"Xlint:unresolvableMember" for enums +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=387444[387444] Softening
+exception in try-with-resources +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=386888[386888] spring-data
+hello-worlds sample fails to compile with 1.7.0 +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=386337[386337] Light AOP
+Parser does not support declare-annotation +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=386049[386049] Error "must
+implement abstract inter-type declaration" even though build is fine +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=384401[384401] NPE when no
+pointcut in afterthrowing annotation style advice +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=384398[384398] Type
+Mismatch error when using inner classes contained in generic types
+within ITDs +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=381906[381906] ASPECTJ
+Internal Compiler Error +
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=73507[73507] Public ITD of
+fields on interfaces creates mangled members +
diff --git a/docs/dist/doc/README-172.adoc b/docs/dist/doc/README-172.adoc
new file mode 100644
index 000000000..ed93e209f
--- /dev/null
+++ b/docs/dist/doc/README-172.adoc
@@ -0,0 +1,25 @@
+[.small]#© Copyright 2011 Contributors. All rights reserved.#
+
+== AspectJ 1.7.2 Readme
+
+The full list of resolved issues in 1.7.2 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.7.2;[here]
+
+.
+
+* 1.7.2 available 13-Feb-2013
+
+=== Fixes:
+
+* Incorrect signature attributes generated into some class files for
+complex generics declarations.
+* Generics information incorrectly being placed in the stackmap
+verification attributes.
+* Problems with generic ITDs not being picked up correctly, resulting in
+'method must be implemented' errors.
+* Problems with multiple usages of 'requires' clause in aop.xml for
+conditional aspects.
+* Generated if() pointcut representations in class files change on only
+a source whitespace change.
+* Intermittent problem with generic ITDs due to weak references being
+collected too soon.
diff --git a/docs/dist/doc/README-173.adoc b/docs/dist/doc/README-173.adoc
new file mode 100644
index 000000000..e50304f2b
--- /dev/null
+++ b/docs/dist/doc/README-173.adoc
@@ -0,0 +1,10 @@
+[.small]#© Copyright 2011 Contributors. All rights reserved.#
+
+== AspectJ 1.7.3 Readme
+
+Available 13-Jun-2013
+
+The list of resolved issues in 1.7.3 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.7.3;[here]
+
+.
diff --git a/docs/dist/doc/README-174.adoc b/docs/dist/doc/README-174.adoc
new file mode 100644
index 000000000..7b4cbb54c
--- /dev/null
+++ b/docs/dist/doc/README-174.adoc
@@ -0,0 +1,34 @@
+[.small]#© Copyright 2013 Contributors. All rights reserved.#
+
+== AspectJ 1.7.4 Readme
+
+Available 24-Oct-2013
+
+The list of resolved issues in 1.7.4 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.7.4;[here]
+
+.
+
+*Notes*
+
+* This release includes an important fix for using loadtime weaving in a
+JVM where JMX is turned on
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=415266[415266])
+* There are some new message insert keys usable in declare error/warning
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=420210[420210]) The new
+keys are:
++
+....
+joinpoint.enclosingclass // Bar
+joinpoint.enclosingmember // void Bar.foo(String)
+joinpoint.enclosingmember.name // foo
+....
++
+All keys are case insensitive.
+* It is now possible to specify individual xlint settings without
+needing to supply a file
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=419279[419279])
++
+....
+ajc -Xlint:adviceDidNotMatch=error,noGuardForLazyTjp=ignore Foo.java
+....
diff --git a/docs/dist/doc/README-180.adoc b/docs/dist/doc/README-180.adoc
new file mode 100644
index 000000000..fe988aa5a
--- /dev/null
+++ b/docs/dist/doc/README-180.adoc
@@ -0,0 +1,71 @@
+[.small]#© Copyright 2014 Contributors. All rights reserved.#
+
+== AspectJ 1.8.0 Readme
+
+The full list of resolved issues in 1.8.0 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.8.0.M1;target_milestone=1.8.0;[here]
+
+.
+
+* 1.8.0 available 17-Apr-2014
+* 1.8.0.RC1 available 18-Mar-2014
+* 1.8.0.M1 available 29-Jul-2013
+
+=== Notable changes
+
+==== 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
+patch on top of Eclipse 4.3.2).
+
+Here is a sample AspectJ8 program:
+
+....
+=== 8< ==== C.java ==== 8< ===
+import java.util.Arrays;
+
+interface I {
+    // Default method
+    default void foo() {
+        System.out.println("ABC");
+    }
+}
+
+public class C implements I{
+    public static void main(String[] args) {
+        new C().foo();
+        // Lambda
+        Runnable r = () -> { System.out.println("hello world!"); };
+        r.run();
+        // Used Java8 b97
+        Arrays.asList(MyClass.doSomething()).forEach((p) -> System.out.println(p));
+    }
+}
+
+aspect X {
+    before(): execution(* I.foo()) {
+        System.out.println("I.foo running");
+    }
+    before(): staticinitialization(!X) {
+        System.out.println("Clazz "+thisJoinPointStaticPart);
+    }
+}
+
+
+class Utils {
+    public static int compareByLength(String in, String out) {
+        return in.length() - out.length();
+    }
+}
+
+class MyClass {
+    public static String[] doSomething() {
+        String []args = new String[]{"4444","333","22","1"};
+        // Method reference
+        Arrays.sort(args,Utils::compareByLength);
+        return args;
+    }
+}
+=== 8< ==== C.java ==== 8< ===
+....
diff --git a/docs/dist/doc/README-181.adoc b/docs/dist/doc/README-181.adoc
new file mode 100644
index 000000000..e008473da
--- /dev/null
+++ b/docs/dist/doc/README-181.adoc
@@ -0,0 +1,18 @@
+[.small]#© Copyright 2014 Contributors. All rights reserved.#
+
+== AspectJ 1.8.1 Readme
+
+The full list of resolved issues in 1.8.1 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.8.1;[here]
+
+.
+
+* 1.8.1 available 20-Jun-2014
+
+=== Notable changes
+
+==== 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
+Java8 related fixes.
diff --git a/docs/dist/doc/README-1810.adoc b/docs/dist/doc/README-1810.adoc
new file mode 100644
index 000000000..947dae81c
--- /dev/null
+++ b/docs/dist/doc/README-1810.adoc
@@ -0,0 +1,39 @@
+[.small]#© Copyright 2016 Contributors. All rights reserved.#
+
+== AspectJ 1.8.10 Readme
+
+The full list of resolved issues in 1.8.10 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.8.10;[here]
+
+.
+
+* 1.8.10 available 9-Dec-2016
+
+=== Notable changes
+
+==== JDT Upgrade
+
+The JDT compiler inside AspectJ has been upgraded to the Eclipse Neon.2
+level (JDT commit #75dbfad0).
+
+==== 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])
+
+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
+joinpoint where 'this'/'target' differ (for example at some call
+joinpoints), the pointcut bound either 'this' or 'target' (but not
+both), then the system would still expect the advice to pass both 'this'
+and 'target' into the proceed call. With the fix here you only need to
+pass what you bind. So if you bind only 'this' you don't need to pass
+'target' (and vice versa). This will affect users that have been working
+around this quirk by passing both 'this' and 'target'. That isn't
+necessary anymore. This fix is in aspectjrt.jar so you will need to be
+using the 1.8.10 version of aspectjrt.jar at runtime to pickup this
+change.
diff --git a/docs/dist/doc/README-1811.adoc b/docs/dist/doc/README-1811.adoc
new file mode 100644
index 000000000..88b159139
--- /dev/null
+++ b/docs/dist/doc/README-1811.adoc
@@ -0,0 +1,19 @@
+[.small]#© Copyright 2017 Contributors. All rights reserved.#
+
+== AspectJ 1.8.11 Readme
+
+This release is a small compatibility release to improve the behaviour
+of the AspectJ 1.8 line on JDK9. Importantly it includes a change that
+knows about the Java 9 version information and so does not get confused
+and think it is running on something really old (which typically
+manifests as it complaining about annotations not being supported on
+this level of Java).
+
+With that change this release is usable for Spring AOP use cases because
+that is doing runtime pointcut matching with proxy creation rather than
+actual weaving. Although if you using Spring AOP with class level
+annotation retention there may still be issues. If you experience
+problems or need to do actual weaving on JDK9, please use AspectJ9
+instead.
+
+* 1.8.11 available 26-Sep-2017
diff --git a/docs/dist/doc/README-182.adoc b/docs/dist/doc/README-182.adoc
new file mode 100644
index 000000000..45215367d
--- /dev/null
+++ b/docs/dist/doc/README-182.adoc
@@ -0,0 +1,171 @@
+[.small]#© Copyright 2014 Contributors. All rights reserved.#
+
+== AspectJ 1.8.2 Readme
+
+The full list of resolved issues in 1.8.2 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.8.2;[here]
+
+.
+
+* 1.8.2 available 14-Aug-2014
+
+=== Notable changes
+
+Although only a few bugs have been fixed here, they are quite important
+ones:
+
+==== 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)
+
+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
+
+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
+
+``
+
+....
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Marker { }
+....
+
+===== Code.java
+
+``
+
+....
+public class Code {
+
+  public static void main(String []argv) {
+    new Code().moo();
+    new Code().boo();
+    new Code().too();
+    new Code().woo();
+  }
+
+  public void moo() {}
+    
+  @Marker
+  public void boo() {}
+    
+  @Marker
+  public void too() {}
+    
+  public void woo() {}
+}
+....
+
+And now a basic annotation processor. This processor will find methods
+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
+
+``
+
+....
+import java.io.*;
+import javax.tools.*;
+import java.util.*;
+import javax.annotation.processing.*;
+import javax.lang.model.*;
+import javax.lang.model.element.*;
+
+@SupportedAnnotationTypes(value= {"*"})
+@SupportedSourceVersion(SourceVersion.RELEASE_6)
+public class DemoProcessor extends AbstractProcessor { 
+
+  private Filer filer;
+
+  @Override
+  public void init(ProcessingEnvironment env) {
+    filer = env.getFiler();
+  }
+
+  @Override
+  public boolean process(Set elements, RoundEnvironment env) {
+    // Discover anything marked with @Marker
+    for (Element element: env.getElementsAnnotatedWith(Marker.class)) {
+      if (element.getKind() == ElementKind.METHOD) {
+        // For any methods we find, create an aspect:
+        String methodName = element.getSimpleName().toString();
+        String aspectText = 
+            "public aspect Advise_"+methodName+" {\n"+
+            "  before(): execution(* "+methodName+"(..)) {\n"+
+            "    System.out.println(\""+methodName+" running\");\n"+
+            "  }\n"+
+            "}\n";
+        try {
+          JavaFileObject file = filer.createSourceFile("Advise_"+methodName, element);
+          file.openWriter().append(aspectText).close();
+          System.out.println("Generated aspect to advise "+element.getSimpleName());
+        } catch (IOException ioe) {
+          // already creates message can appear if processor runs more than once
+          if (!ioe.getMessage().contains("already created")) {
+            ioe.printStackTrace();
+          }
+        }
+      }
+    }
+    return true;
+  }
+}
+....
+
+With those sources, we compile the processor:
+
+``
+
+....
+ajc -1.6 DemoProcessor.java Marker.java
+....
+
+Now compile the code with the processor specified:
+
+``
+
+....
+ajc -1.6 -processor DemoProcessor -showWeaveInfo Code.java Marker.java
+....
+
+``
+
+....
+Generated aspect to advise too
+Generated aspect to advise boo
+Join point 'method-execution(void Code.boo())' in Type 'Code' (Code.java:14) advised by before advice from 'Advise_boo' (Advise_boo.java:2)
+Join point 'method-execution(void Code.too())' in Type 'Code' (Code.java:17) advised by before advice from 'Advise_too' (Advise_too.java:2)
+....
+
+Notice the processor generates the aspects and then they are woven into
+the code being compiled immediately.
+
+Finally we can run it:
+
+``
+
+....
+java Code
+boo running
+too running
+....
+
+*Note:* There is still work to be done to get annotation processors
+behaving under AJDT.
diff --git a/docs/dist/doc/README-183.adoc b/docs/dist/doc/README-183.adoc
new file mode 100644
index 000000000..95425e392
--- /dev/null
+++ b/docs/dist/doc/README-183.adoc
@@ -0,0 +1,116 @@
+[.small]#© Copyright 2014 Contributors. All rights reserved.#
+
+== AspectJ 1.8.3 Readme
+
+The full list of resolved issues in 1.8.3 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.8.3;[here]
+
+.
+
+* 1.8.3 available 22-Oct-2014
+
+=== Notable changes
+
+==== 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
+library might typically be available as a jar and contains a single
+aop.xml file that names all the aspects. The library is then consumed by
+some application. However, the application may not need to use all those
+aspects but because they are listed in the aop.xml they will be
+'active'. Now the pointcuts in those unused aspects may not match
+anything in the application and could be considered harmless but the
+pointcuts and the aspects themselves may have references to types in
+other libraries that the application does not have around. This can lead
+to unhelpful "can't find type" messages and currently requires the user
+to add unnecessary entries to their build dependencies just to keep the
+unused aspects happy.
+
+With AspectJ 1.8.3 it is now possible to express a constraint on an
+aspect. The @RequiredTypes annotation specifies one or more fully
+qualified types that must be discoverable on the classpath in order for
+the aspect to activate. Using this there is no need to add those
+extraneous dependencies to an applications build classpath.
+
+Example:
+
+....
+import org.aspectj.lang.annotation.*;
+
+@RequiredTypes("com.foo.Bar")
+public aspect Foo {
+  before(): execution(@com.foo.Bar * *(..)) {}
+}
+....
+
+If the above aspect is listed in an aop.xml for loadtime weaving or
+passed on the aspectpath for compile time weaving, if the type
+'com.foo.Bar' is not accessible on the classpath then the aspect will be
+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]
+
+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
+particular AspectJ construct. The problem occurs if you are using cflow
+and it hits the preinitialization join point. The pattern of code
+generated in that case causes the verifyerror. In this release of
+AspectJ we have taken the 'quick' approach to solving this, namely to
+avoid advising preinitialization with the cflow construct. This problem
+appears to come up when the aspect is non-optimal anyway and hitting
+preinitialization was never really intended by the pointcut writer. For
+example:
+
+....
+execution(* foo(..)) && cflow(within(Bar))
+....
+
+The use of cflow and within there will actually hit *a lot* of
+joinpoints, many of which the user probably didn't mean to. It feels
+like we actually need a warning to indicate the pointcut is probably
+suboptimal. What the user probably meant was something more like this:
+
+....
+execution(* foo(..)) && cflow(execution(* Bar.*(..))
+....
+
+or
+
+....
+execution(* foo(..)) && cflow(within(Bar) && execution(* *(..)))
+....
+
+But even if they did want the less optimal form of cflow there still
+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]
+
+For optimal performance, where possible, AspectJ tries to inline around
+advice when it applies at a joinpoint. There are few characteristics of
+a joinpoint match that can prevent this but we do try to inline where we
+can (the inlining can be manually turned off via -XnoInline).
+
+Inlining of around advice basically means copying the advice
+instructions into the target class. This causes a problem when the
+advice uses lambdas. Lambda usage is currently implemented in java
+compilers by generating invokedynamic bytecode instructions that
+reference bootstrap methods created in the class and a helper method
+generated in the class containing the lambda code. When the
+invokedynamic is encountered at runtime, some magic happens and the
+bootstrap method is used to generate a class on the fly that calls the
+particular lambda method. All this 'extra stuff' breaks the basic
+inlining algorithm that simply copies the advice bytecode into the
+target. Effectively the inlining process needs to become much more
+sophisticated and copy the bootstrap methods and the lambda helper
+methods, avoiding clashes with existing bootstrap/helpers in the target.
+
+Prior to AspectJ 1.8.3 when the inlining failed you would get a horrible
+class cast exception that mentions constant pool entries (because the
+bootstrap method hadn't been copied over to the target). Temporarily in
+1.8.3 we are turning off inlining of around advice containing lambdas,
+which will at least avoid the failure, with the longer term goal of
+improving the inlining process to do all the necessary extra work.
diff --git a/docs/dist/doc/README-184.adoc b/docs/dist/doc/README-184.adoc
new file mode 100644
index 000000000..002aea1ac
--- /dev/null
+++ b/docs/dist/doc/README-184.adoc
@@ -0,0 +1,31 @@
+[.small]#© Copyright 2014 Contributors. All rights reserved.#
+
+== AspectJ 1.8.4 Readme
+
+The full list of resolved issues in 1.8.4 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.8.4;[here]
+
+.
+
+* 1.8.4 available 6-Nov-2014
+
+=== Notable changes
+
+==== 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-169.html[README].
+This enabled pointcuts to include is(..) clauses to specify which kinds
+of type they were or were not interested in matching, e.g. !within(* &&
+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
+
+This is the key fix in this release. Some products based on AspectJ were
+using the thisAspectInstance feature (see
+https://www.eclipse.org/aspectj/doc/released/README-1612.html[README
+1.6.12] for more info on the feature). Unfortunately if specifying -1.8
+compliance and using the feature an error would be reported at compile
+time of the aspect. This is now fixed.
diff --git a/docs/dist/doc/README-185.adoc b/docs/dist/doc/README-185.adoc
new file mode 100644
index 000000000..909dbfecc
--- /dev/null
+++ b/docs/dist/doc/README-185.adoc
@@ -0,0 +1,16 @@
+[.small]#© Copyright 2015 Contributors. All rights reserved.#
+
+== AspectJ 1.8.5 Readme
+
+The full list of resolved issues in 1.8.5 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.8.5;[here]
+
+.
+
+* 1.8.5 available 28-Jan-2015
+
+=== Notable changes
+
+The most important fixes in 1.8.5 are JDT compiler fixes that it
+includes
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=455277[455277],https://bugs.eclipse.org/bugs/show_bug.cgi?id=458660[458660]).
diff --git a/docs/dist/doc/README-186.adoc b/docs/dist/doc/README-186.adoc
new file mode 100644
index 000000000..9810ab863
--- /dev/null
+++ b/docs/dist/doc/README-186.adoc
@@ -0,0 +1,10 @@
+[.small]#© Copyright 2015 Contributors. All rights reserved.#
+
+== AspectJ 1.8.6 Readme
+
+The full list of resolved issues in 1.8.6 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.8.6;[here]
+
+.
+
+* 1.8.6 available 5-Jun-2015
diff --git a/docs/dist/doc/README-187.adoc b/docs/dist/doc/README-187.adoc
new file mode 100644
index 000000000..de61a362b
--- /dev/null
+++ b/docs/dist/doc/README-187.adoc
@@ -0,0 +1,134 @@
+[.small]#© Copyright 2015 Contributors. All rights reserved.#
+
+== AspectJ 1.8.7 Readme
+
+The full list of resolved issues in 1.8.7 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.8.7;[here]
+
+.
+
+* 1.8.7 available 9-Sep-2015
+
+=== Notable changes
+
+==== ajdoc
+
+The ajdoc tool has been fixed! It is now working again if run on a 1.7
+JDK.
+
+==== 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
+extra flexibility but obviously any classes loaded before attachment
+will not be woven.
+
+Here is a simple aspect:
+
+``
+
+....
+public aspect Azpect {
+  before(): execution(* *(..)) {
+    System.out.println(thisJoinPointStaticPart);
+  }
+}
+....
+
+Compiled via:
+
+``
+
+....
+ajc -1.8 Azpect.java -outxml
+....
+
+This produces a compiled class Azpect.class and a file
+META-INF/aop-ajc.xml.
+
+I then have this sample application (same directory):
+
+``
+
+....
+import java.lang.management.ManagementFactory;
+import org.aspectj.weaver.loadtime.Agent;
+import com.sun.tools.attach.VirtualMachine;
+
+public class Application {
+
+  public static void main(String[] args) {
+    if (!isAspectJAgentLoaded())
+      System.err.println("WARNING: AspectJ weaving agent not loaded");
+    new Sample().doSomething();
+  }
+
+  public static boolean isAspectJAgentLoaded() {
+    try {
+      Agent.getInstrumentation();
+    } catch (NoClassDefFoundError e) {
+      System.out.println(e);
+      return false;
+    } catch (UnsupportedOperationException e) {
+      System.out.println(e);
+      return dynamicallyLoadAspectJAgent();
+    }
+    return true;
+  }
+
+  public static boolean dynamicallyLoadAspectJAgent() {
+    String nameOfRunningVM = ManagementFactory.getRuntimeMXBean().getName();
+    int p = nameOfRunningVM.indexOf('@');
+    String pid = nameOfRunningVM.substring(0, p);
+    try {
+      VirtualMachine vm = VirtualMachine.attach(pid);
+      String jarFilePath = System.getProperty("AGENT_PATH");
+      vm.loadAgent(jarFilePath);
+      vm.detach();
+    } catch (Exception e) {
+      System.out.println(e);
+      return false;
+    }
+    return true;
+  }
+}
+....
+
+And this Sample class:
+
+``
+
+....
+public class Sample {
+    public void doSomething() {
+        System.out.println("Do something");
+        System.out.println("Square of 7 = " + square(7));
+    }
+
+    private int square(int i) {
+        return i * i;
+    }
+}
+....
+
+Compile these with javac, *but you must have the aspectjweaver and the
+JDK tools.jar on your classpath*.
+
+Once compiled we can run it:
+
+``
+
+....
+java -DAGENT_PATH=<path-to>/aspectjweaver.jar Application
+....
+
+What does it do? The main method calls the function that detects whether
+the agent is attached, if it is not then it programmatically attaches it
+using the VirtualMachine class. Then the main method accesses the Sample
+class. At this point in program execution the Sample class is loaded and
+because the agent has been attached it gets woven. Notice that the
+Application class itself is not woven because it was loaded prior to
+agent attachment.
+
+Thanks to Alexander Kriegisch for the sample code and the patch to add
+this behaviour to AspectJ.
diff --git a/docs/dist/doc/README-188.adoc b/docs/dist/doc/README-188.adoc
new file mode 100644
index 000000000..3f720edac
--- /dev/null
+++ b/docs/dist/doc/README-188.adoc
@@ -0,0 +1,19 @@
+[.small]#© Copyright 2016 Contributors. All rights reserved.#
+
+== AspectJ 1.8.8 Readme
+
+The full list of resolved issues in 1.8.8 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.8.8;[here]
+
+.
+
+* 1.8.8 available 7-Jan-2016
+
+=== Notable changes
+
+==== 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
+declaring the default method (loading these interfaces would then result
+in a verifier error). This has now been fixed.
diff --git a/docs/dist/doc/README-189.adoc b/docs/dist/doc/README-189.adoc
new file mode 100644
index 000000000..c3ecd3a56
--- /dev/null
+++ b/docs/dist/doc/README-189.adoc
@@ -0,0 +1,15 @@
+[.small]#© Copyright 2016 Contributors. All rights reserved.#
+
+== AspectJ 1.8.9 Readme
+
+The full list of resolved issues in 1.8.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.8.9;[here]
+
+.
+
+* 1.8.9 available 14-Mar-2016
+
+=== Notable changes
+
+The JDT compiler inside AspectJ has been upgraded to the Eclipse Mars.2
+level (commit #a7bba8b1).
diff --git a/docs/dist/doc/README-190.adoc b/docs/dist/doc/README-190.adoc
new file mode 100644
index 000000000..3b1f27784
--- /dev/null
+++ b/docs/dist/doc/README-190.adoc
@@ -0,0 +1,339 @@
+[.small]#© Copyright 2018 Contributors. All rights reserved.#
+
+The full list of resolved issues in 1.9.0 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.0[here]
+
+.
+
+== AspectJ 1.9.0
+
+=== Improved runtime interface
+
+New factory methods have been added to the AspectJ runtime. This is an
+attempt to more optimally create thisJoinPoint and
+thisEnclosingJoinPoint objects. The generated code that invokes these
+now also uses the ability for the LDC bytecode instruction to load class
+constants directly (this replaces what was happening previously where
+generated code referenced string classnames and classloading was being
+done from the aspectj runtime as the woven application was starting).
+
+This is turned on by using -Xajruntimetarget:1.9. This option was used
+previously to enable users to target an old runtime if they knew that
+old runtime is all that was available at some deployed target. The new
+generation mechanism is not the default, not until it has had a bit more
+testing out in the wild.
+
+The changes to generated code have a couple of potential side effects:
+
+* *overall size*: the woven code may be smaller due to the use of
+smaller string constant pieces in the generated code (previously strings
+were smashed together in the generated code and then taken apart by
+AspectJ at runtime). Since the pieces are smaller, they can be shared
+across other uses in the class file.
+* *method size*: although the overall class may be smaller there are
+more instructions involved in preparing the data for invocation of the
+new joinpoint factory methods. It is possible if you have a lot of
+joinpoints that we might blow the 64k instruction limit for the
+ajc$preClinit method (where the factory invocation code is generated).
+Please provide feedback if this happens to you!
+
+In anticipation of not all build plugins supporting that
+-Xajruntimetarget option, you can now specify these kinds of option in
+the ASPECTJ_OPTS environment variable. Set that in your environment:
+
+....
+export ASPECTJ_OPTS="-Xajruntimetarget:1.9"
+....
+
+And it should get picked up by AspectJ when it runs.
+
+* 1.9.0 available 2-Apr-2018
+
+== AspectJ 1.9.0.RC4
+
+Primary changes in RC4 are to add support for <compilerArg> in the Ant
+task. This enables users of the Ant task to pass in options supported by
+the underlying AspectJ but not yet surfaced elsewhere. Particularly
+useful with Java9 which includes a number of module related commands.
+For example, here is an iajc usage with compilerArg that is passing
+--add-modules java.xml.bind:
+
+....
+  <iajc destdir="bin" failonerror="true"
+     showWeaveInfo="true" source="1.9" target="1.9"
+     debug="true"  fork="true"  maxmem="256m">
+     <compilerArg value="--add-modules"/>
+     <compilerArg value="java.xml.bind"/>
+    <src path="src" />
+    <classpath>
+            <pathelement location="${aspectj.home}/lib/aspectjrt.jar"/>
+    </classpath>
+ </iajc>
+....
+
+1.9.0.RC4 available 21-Feb-2018
+
+== AspectJ 1.9.0.RC3
+
+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.
+
+1.9.0.RC3 available 5-Feb-2018
+
+== AspectJ 1.9.0.RC2
+
+* 1.9.0.RC2 available 9-Nov-2017
+
+Key change in 1.9.0.RC2 is actually to be more tolerant of JDK10. The
+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
+
+* 1.9.0.RC1 available 20-Oct-2017
+
+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
+
+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
+automatic module name is org.aspectj.runtime for the aspectjrt module:
+
+....
+$ java --module-path <pathto>/lib/aspectjrt.jar --list-modules | grep aspectj
+
+org.aspectj.runtime file:///<pathto>/lib/aspectjrt.jar automatic
+....
+
+And similarly org.aspectj.weaver and org.aspectj.tools for aspectjweaver
+and aspectjtools respectively:
+
+....
+$ java --module-path <pathto>/lib/aspectjweaver.jar --describe-module org.aspectj.weaver
+
+org.aspectj.weaver file:///<pathto>/lib/aspectjweaver.jar automatic
+requires java.base mandated
+contains aj.org.objectweb.asm
+contains aj.org.objectweb.asm.signature
+contains org.aspectj.apache.bcel
+contains org.aspectj.apache.bcel.classfile
+contains org.aspectj.apache.bcel.classfile.annotation
+contains org.aspectj.apache.bcel.generic
+contains org.aspectj.apache.bcel.util
+contains org.aspectj.asm
+contains org.aspectj.asm.internal
+...
+....
+
+ +
+ +
+
+=== Building woven modules
+
+AspectJ understands module-info.java source files and building modules
+that include aspects. Here is an example:
+
+....
+module-info.java
+
+module demo {
+    exports pkg;
+    requires org.aspectj.runtime;
+}
+
+
+pkg/Demo.java
+
+package pkg;
+
+public class Demo {
+    public static void main(String[] argv) {
+        System.out.println("Demo running");
+    }
+}
+
+
+otherpkg/Azpect.java
+
+package otherpkg;
+
+public aspect Azpect {
+    before(): execution(* *(..)) && !within(Azpect) {
+        System.out.println("Azpect running");
+    }
+}
+....
+
+We can now build those into a module:
+
+....
+$ ajc -1.9 module-info.java otherpkg/Azpect.java pkg/Demo.java -outjar demo.jar
+
+...
+module-info.java:3 [error] org.aspectj.runtime cannot be resolved to a module
+...
+....
+
+Wait, that failed! Yes, aspectjrt.jar (which includes the required
+org.aspectj.weaver module) wasn't supplied. We need to pass it on the
+module-path:
+
+....
+$ ajc -1.9 --module-path <pathto>/aspectjrt.jar module-info.java otherpkg/Azpect.java pkg/Demo.java -outjar demo.jar
+....
+
+Now we have a demo module we can run:
+
+....
+$ java --module-path <pathto>/aspectjrt.jar:demo.jar --module demo/pkg.Demo
+
+Azpect running
+Demo running
+....
+
+That's it!
+
+ +
+ +
+
+=== 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
+aspects. Take the module we built above, let's weave into it again:
+
+....
+extra/AnotherAzpect.java
+
+package extra;
+
+public aspect AnotherAzpect {
+    before(): execution(* *(..)) && !within(*Azpect) {
+        System.out.println("AnotherAzpect running");
+    }
+}
+....
+
+....
+$ ajc -inpath demo.jar AnotherAzpect.java -outjar newdemo.jar
+....
+
+Notice how there was no complaint here that the org.aspectj.runtime
+module hadn't been passed in. That is because inpath was being used
+which doesn't treat specified jars as modules (and so does not check
+dependencies). There is no module-inpath right now.
+
+Because the new jar produced includes the compiled aspect, the
+module-info specification inside is still correct, so we can run it
+exactly as before:
+
+....
+$ java --module-path ~/installs/aspectj190rc1/lib/aspectjrt.jar:newdemo.jar --module demo/pkg.Demo
+
+Azpect running
+AnotherAzpect running
+Demo running
+....
+
+ +
+ +
+
+=== Faster Spring AOP
+
+Dave Syer recently created a series of benchmarks for checking the speed
+of Spring-AspectJ: https://github.com/dsyer/spring-boot-aspectj
+
+Here we can see the numbers for AspectJ 1.8.11 (on an older Macbook
+Pro):
+
+....
+Benchmark                 (scale)  Mode  Cnt   Score   Error  Units
+StartupBenchmark.ltw          N/A  avgt   10   2.553 ~ 0.030   s/op
+StartupBenchmark.ltw_100      N/A  avgt   10   2.608 ~ 0.046   s/op
+StartupBenchmark.spring     v0_10  avgt   10   2.120 ~ 0.148   s/op
+StartupBenchmark.spring     v1_10  avgt   10   2.219 ~ 0.066   s/op
+StartupBenchmark.spring    v1_100  avgt   10   2.244 ~ 0.030   s/op
+StartupBenchmark.spring    v10_50  avgt   10   2.950 ~ 0.026   s/op
+StartupBenchmark.spring    v20_50  avgt   10   3.854 ~ 0.090   s/op
+StartupBenchmark.spring   v20_100  avgt   10   4.003 ~ 0.038   s/op
+StartupBenchmark.spring     a0_10  avgt   10   2.067 ~ 0.019   s/op
+StartupBenchmark.spring     a1_10  avgt   10   2.724 ~ 0.023   s/op
+StartupBenchmark.spring    a1_100  avgt   10   2.778 ~ 0.057   s/op
+StartupBenchmark.spring    a10_50  avgt   10   7.191 ~ 0.134   s/op
+StartupBenchmark.spring   a10_100  avgt   10   7.191 ~ 0.168   s/op
+StartupBenchmark.spring    a20_50  avgt   10  11.541 ~ 0.158   s/op
+StartupBenchmark.spring   a20_100  avgt   10  11.464 ~ 0.157   s/op
+....
+
+So this is the average startup of an app affected by aspects applying to
+the beans involved. Where numbers are referenced the first is the number
+of aspects/pointcuts and the second is the number of beans. The 'a'
+indicates an annotation based pointcut vs a non-annotation based
+pointcut ('v'). Notice things are much worse for annotation based
+pointcuts. At 20 pointcuts and 50 beans the app is 9 seconds slower to
+startup. +
+
+In AspectJ 1.8.12 and 1.9.0.RC1 some work has been done here. The key
+change is to recognize that the use of annotations with runtime
+retention is much more likely than annotations with class level
+retention. Retrieving annotations with class retention is costly because
+we must open the bytes for the class file and dig around in there (vs
+runtime retention which are immediately accessible by reflection on the
+types). In 1.8.11 the actual type of the annotation involved in the
+matching is ignored and the code will fetch *all* the annotations on the
+type/method/field being matched against. So even if the match is looking
+for a runtime retention annotation, we were doing the costly thing of
+fetching any class retention annotations. In 1.8.12/1.9.0.RC1 we take
+the type of the match annotation into account - allowing us to skip
+opening the classfiles in many cases. There is also some deeper work on
+activating caches that were not previously being used correctly but the
+primary change is factoring in the annotation type.
+
+What difference does that make? AspectJ 1.9.0.RC1:
+
+....
+Benchmark                 (scale)  Mode  Cnt  Score   Error  Units
+StartupBenchmark.ltw          N/A  avgt   10  2.568 ~ 0.035   s/op
+StartupBenchmark.ltw_100      N/A  avgt   10  2.622 ~ 0.075   s/op
+StartupBenchmark.spring     v0_10  avgt   10  2.096 ~ 0.054   s/op
+StartupBenchmark.spring     v1_10  avgt   10  2.206 ~ 0.031   s/op
+StartupBenchmark.spring    v1_100  avgt   10  2.252 ~ 0.025   s/op
+StartupBenchmark.spring    v10_50  avgt   10  2.979 ~ 0.071   s/op
+StartupBenchmark.spring    v20_50  avgt   10  3.851 ~ 0.058   s/op
+StartupBenchmark.spring   v20_100  avgt   10  4.000 ~ 0.046   s/op
+StartupBenchmark.spring     a0_10  avgt   10  2.071 ~ 0.026   s/op
+StartupBenchmark.spring     a1_10  avgt   10  2.182 ~ 0.032   s/op
+StartupBenchmark.spring    a1_100  avgt   10  2.272 ~ 0.024   s/op
+StartupBenchmark.spring    a10_50  avgt   10  2.557 ~ 0.027   s/op
+StartupBenchmark.spring   a10_100  avgt   10  2.598 ~ 0.040   s/op
+StartupBenchmark.spring    a20_50  avgt   10  2.961 ~ 0.043   s/op
+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...
+
+* 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
+AspectJ 1.9.X revisions.
+* AspectJ does not currently modify module-info.java files. An aspect
+from one module applying to code in another module clearly introduces a
+dependency between those two modules. There is no reason - other than
+time! - that this can't be done.
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=526244[Issue 526244])
+* Related to that AspectJ, on detection of aspects should be able to
+automatically introduce the requires org.aspectj.runtime to the
+module-info. (https://bugs.eclipse.org/bugs/show_bug.cgi?id=526242[Issue
+526242])
+* Module aware variants of AspectJ paths: --module-inpath,
+--module-aspectpath.
+(https://bugs.eclipse.org/bugs/show_bug.cgi?id=526243[Issue 526243])
+
+ +
+ +
diff --git a/docs/dist/doc/README-191.adoc b/docs/dist/doc/README-191.adoc
new file mode 100644
index 000000000..acab550c3
--- /dev/null
+++ b/docs/dist/doc/README-191.adoc
@@ -0,0 +1,35 @@
+[.small]#© Copyright 2018 Contributors. All rights reserved.#
+
+The full list of resolved issues in 1.9.1 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.1[here]
+
+.
+
+== AspectJ 1.9.1
+
+=== Java 10 support
+
+AspectJ has updated to a recent JDT compiler version (commit
+#abe06abe4ce1 - 9-Apr-2018). With this update it now supports Java10.
+This means you can use the 'var' support. A simple example of combining
+var with an aspect:
+
+....
+public class Code3 {
+    public static void main(String []argv) {
+        var x = "hello";
+        System.out.println(x.getClass());
+    }
+}
+
+aspect X {
+    before(): call(* *.getClass()) && target(String) {
+        System.out.println(thisJoinPointStaticPart);
+    }
+}
+....
+
+Available: 1.9.1 available 20-Apr-2018
+
+ +
+ +
diff --git a/docs/dist/doc/README-192.adoc b/docs/dist/doc/README-192.adoc
new file mode 100644
index 000000000..03f3e6c15
--- /dev/null
+++ b/docs/dist/doc/README-192.adoc
@@ -0,0 +1,18 @@
+[.small]#© 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]
+
+.
+
+== AspectJ 1.9.2
+
+=== Java 11 support
+
+AspectJ now supports Java11. It has been updated to a more recent JDT
+compiler that supports Java 11 (JDTCore #6373b82afa49b).
+
+Available: 1.9.2 available Oct-2018
+
+ +
+ +
diff --git a/docs/dist/doc/README-193.adoc b/docs/dist/doc/README-193.adoc
new file mode 100644
index 000000000..a75724c2c
--- /dev/null
+++ b/docs/dist/doc/README-193.adoc
@@ -0,0 +1,77 @@
+[.small]#© Copyright 2018 Contributors. All rights reserved.#
+
+The full list of resolved issues in 1.9.3 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.3[here]
+
+.
+
+AspectJ 1.9.3 supports Java12. Java12 introduces the new switch
+expression syntax, but you must activate support for that via an
+--enable-preview flag when using the compiler and attempting to run the
+resultant classes: Here is Switch3.java:
+
+....
+=========8<=========
+public class Switch3 {
+    public static void main(String[] argv) {
+        System.out.println(one(Color.R));
+        System.out.println(one(Color.G));
+        System.out.println(one(Color.B));
+        System.out.println(one(Color.Y));
+    }
+
+    public static int one(Color color) {
+        int result = switch(color) {
+         case R -> foo(0);
+         case G -> foo(1);
+         case B -> foo(2);
+         default -> foo(3);
+        };
+        return result;
+    }
+    
+    public static final int foo(int i) {
+        return i+1;
+    }
+}
+
+enum Color {
+    R, G, B, Y;
+}
+
+aspect X {
+    int around(): call(* foo(..)) {
+        return proceed()*3;
+    }
+}
+=========8<=========
+....
+
+Compile it with:
+
+....
+$ ajc --enable-preview -showWeaveInfo -12 Switch3.java
+
+Join point 'method-call(int Switch3.foo(int))' in Type 'Switch3' (Switch3.java:12) advised by around advice from 'X' (Switch3.java:30)
+
+Join point 'method-call(int Switch3.foo(int))' in Type 'Switch3' (Switch3.java:13) advised by around advice from 'X' (Switch3.java:30)
+
+Join point 'method-call(int Switch3.foo(int))' in Type 'Switch3' (Switch3.java:14) advised by around advice from 'X' (Switch3.java:30)
+
+Join point 'method-call(int Switch3.foo(int))' in Type 'Switch3' (Switch3.java:15) advised by around advice from 'X' (Switch3.java:30)
+....
+
+Now run it:
+
+....
+$ java --enable-preview Switch3
+3
+6
+9
+12
+....
+
+Available: 1.9.3.RC1 available 7-Mar-2019
+
+ +
+ +
diff --git a/docs/dist/doc/README-194.adoc b/docs/dist/doc/README-194.adoc
new file mode 100644
index 000000000..44d4e238d
--- /dev/null
+++ b/docs/dist/doc/README-194.adoc
@@ -0,0 +1,29 @@
+[.small]#© Copyright 2019 Contributors. All rights reserved.#
+
+== AspectJ 1.9.4
+
+The full list of resolved issues in 1.9.4 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.4[here]
+
+.
+
+AspectJ 1.9.4 has a couple of important fixes in it:
+
+* Due to the new maven build process being used to build release
+artifacts for the first time, there were errors in the aspectjweaver jar
+that affected the ability to use it on the command line as an agent,
+this is now fixed.
+* A number of users were noticing a ClassCastException problem, which I
+believe was due to trying to run AspectJ on one level of the JDK whilst
+targeting another. This can happen quite easily in eclipse if running
+your Eclipse on Java 8 but developing projects targeting Java 11. The
+class cast is because Java8 couldn't understand the packaging of system
+classes post Java9 and so couldn't find java.lang.Object. This has now
+all been tidied up and should work much better. More details in
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=546807[546807], thanks to
+Denys Khanzhyiev for some tips on getting to the right solution.
+
+Available: 1.9.4 available 10-May-2019
+
+ +
+ +
diff --git a/docs/dist/doc/README-195.adoc b/docs/dist/doc/README-195.adoc
new file mode 100644
index 000000000..2af7e42a7
--- /dev/null
+++ b/docs/dist/doc/README-195.adoc
@@ -0,0 +1,59 @@
+[.small]#© Copyright 2019 Contributors. All rights reserved.#
+
+== AspectJ 1.9.5
+
+The full list of resolved issues in 1.9.5 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.5[here]
+
+.
+
+AspectJ 1.9.5 supports Java13. Java13 introduces text blocks, but you
+must activate support for that via an --enable-preview flag when using
+the compiler and attempting to run the resultant classes: Here is
+Code.java:
+
+....
+=======8<=========
+public class Code {
+  public static void main(String[] argv) {
+  }
+
+  static aspect X {
+    before(): execution(* Code.main(..)) {
+    System.out.println(
+"""
+This
+is
+on
+multiple
+lines
+"""
+);
+    }
+  }
+
+}
+=========8<=========
+....
+
+Compile it with:
+
+....
+$ ajc --enable-preview -13 Code.java
+....
+
+Now run it:
+
+....
+$ java --enable-preview Code
+This
+is
+on
+multiple
+lines
+....
+
+Available: 1.9.5 available 28-Nov-2019
+
+ +
+ +
diff --git a/docs/dist/doc/README-196.adoc b/docs/dist/doc/README-196.adoc
new file mode 100644
index 000000000..536cd4ec9
--- /dev/null
+++ b/docs/dist/doc/README-196.adoc
@@ -0,0 +1,57 @@
+[.small]#© Copyright 2020 Contributors. All rights reserved.#
+
+== AspectJ 1.9.6
+
+The full list of resolved issues in 1.9.6 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.6[here]
+
+.
+
+AspectJ 1.9.6 supports Java14. Java14 introduces records, but you must
+activate support for that via an --enable-preview flag when using the
+compiler and attempting to run the resultant classes: Here is Code.java:
+
+....
+=======8<=========
+public record Person(String firstName, String lastName, int age) {}
+=======8<=========
+
+=======8<=========
+public class UsingPersonRecord {
+  public static void main(String[] argv) {
+    Person p = new Person("A","B",99);
+    System.out.println(p);
+    System.out.println(p.firstName());
+  }
+}
+=======8<=========
+
+=======8<=========
+public aspect TraceRecordComponents {
+  before(): execution(public * *()) {
+    System.out.println(thisJoinPointStaticPart);
+  }
+}
+=======8<=========
+....
+
+Compile it with:
+
+....
+$ ajc --enable-preview -14 Person.java UsingPersonRecord.java TraceRecordComponents.java
+....
+
+Now run it:
+
+....
+$ java --enable-preview UsingPersonRecord
+execution(String Person.toString())
+Person[firstName=A, lastName=B, age=99]
+execution(String Person.firstName())
+A
+....
+
+Available: 1.9.6 available 22-Jul-2020
+
+ +
+ +
diff --git a/docs/dist/doc/README-197.adoc b/docs/dist/doc/README-197.adoc
new file mode 100644
index 000000000..974891425
--- /dev/null
+++ b/docs/dist/doc/README-197.adoc
@@ -0,0 +1,109 @@
+[.small]#© Copyright 2021 Contributors. All rights reserved.#
+
+== AspectJ 1.9.7
+
+AspectJ (binaries, source code, documentation) is now distributed under
+the https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse
+Public License v 2.0].
+
+Please note that going forward Bugzilla for issue management is
+deprecated and new issues should be filed as
+https://github.com/eclipse/org.aspectj/issues/new[GitHub issues]. The
+list of issues addressed for 1.9.7 can be found
+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.7[here
+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
+
+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
+respective final and review features:
+
+* text blocks (final 15)
+* records (preview 15, final 16)
+* instanceof pattern matching (preview 15, final 16)
+* hidden classes (final 15)
+* sealed classes (preview 15, preview 16)
+
+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.
+
+Please note that you cannot run code compiled with preview features on
+any other JDK than the one used for compilation. For example, records
+compiled with preview on JDK 15 cannot be used on JDK 16 without
+recompilation. This is a JVM limitation unrelated to AspectJ. Also, e.g.
+sealed classes are preview-1 on JDK 15 and preview-2 on JDK 16. You
+still need to recompile, no matter what.
+
+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):
+
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features195/textblock[AspectJ
+1.9.5: text blocks]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features196/java14[AspectJ
+1.9.6: records, instanceof patterns]
+* https://github.com/eclipse/org.aspectj/tree/master/tests/features197/java15[AspectJ
+1.9.7: hidden classes, sealed classes]
+
+=== 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
+(Strongly Encapsulate JDK Internals by Default)]. Therefore, you need to
+set the JVM parameter --add-opens java.base/java.lang=ALL-UNNAMED in
+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
+
+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
+product itself but will help us to more easily maintain and release the
+product in the future and more easily on-boarding new developers or
+contributors. For example:
+
+* The main repository has been moved to
+https://github.com/eclipse/org.aspectj[GitHub], i.e. you can open bug
+reports, feature requests and pull requests there now.
+* The Maven build has been improved, i.e. it is now easier to build and
+contribute to the product. Developers can just import the Maven project
+and no longer depend on Eclipse to build and test AspectJ, but can e.g.
+also use IntelliJ IDEA.
+* Continuous integration builds now run on GitHub for different JDK
+versions, also for pull requests. I.e. both maintainers and contributors
+get to know if their changes break any tests.
+* We can build releases and deploy them directly to Sonatype OSSRH
+(snapshots) or Maven Central (releases) with Maven now, i.e. it should
+be much easier in the future to publish development versions in order to
+enable users to re-test fixed bugs or try new features.
+* All tests are portable now, i.e. they correctly run on Windows, too.
+This enables developers and contributors to make a choice if they want
+to work on Linux or on Windows.
+
+=== Other changes and bug fixes
+
+* Remove legacy JRockit support.
+* Support Windows 10 and Windows Server 2016/2019 in installer. Those
+versions were not detected until now, which led to bogus Windows batch
+files forwarding only 9 AJC parameters to the Java process via %1 %2 %3
+%4 %5 %6 %7 %8 %9 instead of %*.
+* AJdoc (AspectJ's javadoc generator add-on for aspects) now supports
+the JDK 16 javadoc generator.
+* Fix serialVersionUID initialization for Java 9+
+* AJC (AspectJ Compiler) usage texts sometimes used to be printed twice
+and they were printed too often, e.g. on top of every compile error.
+This has been fixed. Furthermore, the partly outdated usage text is now
+basically the same as ECJ (Eclipse Java Compiler), which AJC is a fork
+of, plus AspectJ-specific additions which are added during runtime.
+* Source and javadoc JARs distributed together with the AspectJ
+artifacts on Maven Central are now more accurate and more complete with
+regard to what is included (ASM, JDT Core) and how package names have
+been relocated.
+* Fix sample code formatting issues (indentation) throughout the
+documentation.
+
+Available: 1.9.7 available 24-Jun-2021
diff --git a/docs/dist/doc/changes.adoc b/docs/dist/doc/changes.adoc
new file mode 100644
index 000000000..12192b51c
--- /dev/null
+++ b/docs/dist/doc/changes.adoc
@@ -0,0 +1,1538 @@
+[.small]#© Copyright 1998-2002 Palo Alto Research Center Incorporated
+2003-2008 Contributors. All rights reserved.#
+
+== Changes in AspectJ
+
+* xref:#1.6.0[1.6.0] (released 2008-04)
+* xref:#1.5.4[1.5.4] (released 2007-12)
+* xref:#1.5.3[1.5.3] (released 2006-11)
+* xref:#1.5.2[1.5.2] (released 2006-06)
+* xref:#1.5.1[1.5.1] (released 2006-04)
+* xref:#1.5.0[1.5.0] (released 2005-12)
+* xref:#1.2.1[1.2.1] (released 2004-10)
+* xref:#1.2[1.2] (released 2004-05)
+* xref:#1.1.1[1.1.1] (released 2003-09)
+* 1.1.0 (released 2003-06-06) See README-11.html
+* xref:#1.0.6[1.0.6] (released 2002-07-24)
+** xref:#1.0.6compiler[Compiler]
+** xref:#1.0.6ajde[AJDE]
+** xref:#1.0.6ajdoc[Ajdoc]
+* xref:#1.0.5[1.0.5] (released 2002-06-27)
+* xref:#1.0.4[1.0.4] (released 2002-04-17)
+* xref:#1.0.3[1.0.3] (released 2002-02-08)
+* xref:#1.0.2[1.0.2] (released 2002-02-06)
+* xref:#1.0.1[1.0.1] (released 2001-12-18)
+* xref:#1.0.0[1.0.0] (released 2001-11-30)
+* xref:#1.0rc3[1.0rc3] (released 2001-11-14)
+* xref:#1.0rc2[1.0rc2] (released 2001-10-12)
+* xref:#1.0rc1[1.0rc1] (released 2001-10-5)
+* xref:#1.0beta1[1.0beta1] (released 2001-08-29)
+* xref:#1.0alpha1[1.0alpha1] (released 2001-08-09)
+* xref:porting.adoc[Porting and Transition]
+
+'''''
+
+== [#1.6.0]#1.6.0#
+
+This release rebases AspectJ on the Eclipse Compiler version 785_R33X -
+making it Java6 compliant.
+
+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#
+
+This release contains around 40 bug fixes and enhancements since the
+1.5.3 release.
+
+A full list of bugs fixed and enhancements implemented can be found in
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&target_milestone=1.5.4&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED[]
+Bugzilla
+
+== [#1.5.3]#1.5.3#
+
+This release contains around 80 bug fixes and enhancements since the
+1.5.2 release.
+
+A full list of bugs fixed and enhancements implemented can be found in
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&target_milestone=1.5.3&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED[]
+Bugzilla
+
+== [#1.5.2]#1.5.2#
+
+This release contains around 60 bug fixes and enhancements since the
+1.5.1 release.
+
+A full list of bugs fixed and enhancements implemented can be found in
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&target_milestone=1.5.2&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED[]
+Bugzilla
+
+== [#1.5.1]#1.5.1#
+
+This release contains over 70 bug fixes and enhancements since the 1.5.0
+release.
+
+A full list of bugs fixed in AspectJ 5 can be found in
+https://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced&product=AspectJ&target_milestone=1.5.1&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED[]
+Bugzilla
+
+== [#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
+link:adk15notebook/index.html[AspectJ 5 Developer's Notebook]. There are
+also a number of enhancements to accompanying tools documented in the
+link:devguide/index.html[Developer's Guide]
+
+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#
+
+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
+list of fixes and enhancements] can be found on bugzilla. Some of the
+more significant bug fixes and enhancements include:
+
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=53981[53981] Any
+occurence of proceed(..) within the body of around advice is treated as
+the special proceed form (even if the aspect defines a method named
+proceed) unless a target other than the aspect instance is specified as
+the recipient of the call.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=48990[48990]
+Optimisations added for the special cases of if(true) and if(false) in
+pointcut expressions.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=69319[69319] The Eclipse
+JDT compiler inside AspectJ has been upgraded to the Eclipse 3.0 release
+version.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=61572[61572] AspectJ
+1.2.1 correctly detects an attempt to access instance variables of the
+declaring aspect of an inter-type declared method from within the body
+of that method.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=65319[65319] Error
+message now correctly produced when attempting to bind a pointcut formal
+in both a this() and a target() pointcut sub-expression.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=70619[70619] Conflicting
+declare precedence statements are now handled gracefully.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=42573[42573] Relative
+paths specified in .lst files are now resolved relative to the lst file
+location.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=57666[57666] Resource
+copying from jar files correctly handles duplicate manifests.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=61768[61768] Static
+inner types of an aspect can now be referenced within the body of
+inter-type declared methods in that aspect.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=62642[62642]
+after-throwing advice on a static initialization join point no longer
+swallows ExceptionInInitializer errors.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=67578[67578] AspectJ
+1.2.1 correctly handles privileged access to members defined in a
+different package to the privileged aspect.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=67592[67592] The
+Object[] given in response to a getArgs() call on a JoinPoint object is
+now a value copy.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=68991[68991]
+Initialisers of inter-type declared fields now have field-set join
+points.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=69459[69459] A static
+inter-type method declaration is not allowed to hide an instance method.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=70794[70794] An
+inter-type declaration of an abstract method on a target type which is
+an interface must be declared as public.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=71372[71372] Calls can
+be made to private static methods of enclosing types from the body of
+around advice in an inner aspect.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=71377[71377] Join points
+are now correctly detected for calls to private methods and set/get of
+private fields within the body of around advice.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=71723[71723] A
+non-privileged inter-type declared method cannot call protected methods
+defined in parent classes of the target type.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=74238[74238] Any
+privileged calls made by the AspectJ runtime library are now correctly
+wrapped in doPrivileged blocks, with fall-back implementations, allowing
+usage in restricted environments.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=74245[74245] Specifying
+the -proceedOnError flag will now cause the compiler to attempt weaving
+even in the face of errors.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=76030[76030] Runtime
+optimisations for cflow (in the case where there are no arguments bound
+in the cflow pointcut) have been implemented. This can dramatically
+speed-up some programs making heavy use of cflow. Thanks to the abc
+compiler team for detecting this performance related bug and for
+piloting the fix.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54421[54421] String
+concatentation (using "+") is now allowed for the message associated
+with a declare error or warning statement.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=69011[69011] ajdoc now
+correctly handles types in the default package.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=36747[36747] The 1.2.1
+compiler supports an additional option, -showWeaveInfo, which will
+produce informational messages concerning the activity of the weaver.
+For example:
++
+....
+        Type 'tjp.Demo' (Demo.java:30) advised by around advice from 'tjp.GetInfo'
+        (GetInfo.java:26) [RuntimeTest=true]
+
+....
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=44191[44191] AspectJ
+1.2.1 improves the error messages issued in many of the infamous "can't
+find type" scenarios.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=46298[46298] The code
+generated by ajc is now more easily digested by many decompilers (but
+you wouldn't want to do that anyway would you?? ;) ).
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=49743[49743] Performance
+optimisations in the AspectJ runtime library when using getSignature()
+and toString().
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=61374[61374] AspectJ now
+includes its own version of BCEL under the org.aspectj namespace which
+eliminates unwanted conflicts with BCEL versions inside JDKs or on
+classpaths in general.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=68494[68494] ajdoc now
+supports ".aj" files.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=72154[72154] The AspectJ
+1.2.1 compiler includes the ability to dump information about the
+current state of the compiler on failure. By default this only happens
+on an abort, but it can also be forced to dump on error by specifying
+the property: org.aspectj.weaver.Dump.condition=error
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=37020[37020] The line
+number locations for method execution and static initialization join
+points now give the first line of the method declaration (rather than
+the line number of the first line of code in the method body) when the
+source code is compiled by ajc.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=73369[73369] A new jar,
+aspectjweaver.jar is included in the lib directory, which contains the
+subset of aspectjtools.jar needed for weaving. The "aj" script is also
+moved into the bin directory.
+
+== [#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
+list of fixes and enhancements] can be found on bugzilla. Some of the
+more significant bug fixes and enhancements include:
+
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=46347[46347] The ajc
+compiler now can read .class files from directories as well as zip files
+for bytecode weaving, via the new -inpath option.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=48080[48080] Error and
+warning messages emitted as a result of a declare error or declare
+warning statement now include context information that indicates the
+matched join point.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54819[54819] Error and
+warning messages coming from the weaving phase of compilation now show
+source context wherever it is available, and also indicate as the source
+location of the error either the class file or jar file from which the
+binary source unit came.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=36430[36430] A new
+-Xreweavable option has been added which allows class files to be woven
+more than once.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=49250[49250]
+SoftException now supports getCause().
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=51320[51320] AspectJ 1.2
+now gives a compilation error if one of the non-statically determinable
+pointcut forms is used in a declare statement.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=53012[53012] Declaring
+precedence on a class type (rather than an aspect type) is now an error
+unless subtypes are included.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=36069[36069] The source
+information for inlined advice is now correct (using JSR 45).
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=34206[34206] (See also
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=44587[44587]). Errors
+occuring during static initialisation of an aspect are now handled much
+more gracefully.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=41952[41952] A new Xlint
+warning warns users specifying declaring type patterns in call pointcut
+designators if the pointcut does not match at places they may expect it
+to.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=42574[42574] -extdirs
+opion now recognises .zip files as well as .jar.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=48091[48091] New option
+-XlazyTjp defers creation of JoinPoint objects until just before calling
+the advice body that requires them. This allows the cost of creating
+JoinPoint objects to be avoided using an if() pointcut test that returns
+false when the advice body is not required to be executed. Speed-ups of
+10-100X are obtained via this optimisation (as compared to putting the
+test inside the advice body).
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=45441[45441]
+IncompatibleClassChangeError at runtime when compiling with the -1.4
+option.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54625[54625] Incremental
+compilation did not support the -outjar option, but silently failed if
+it was specified. AspectJ 1.2 always performs a full build when the
+-outjar option is present.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54965[54965] Incremental
+compilation under AspectJ 1.2 is approximately twice as fast as under
+AspectJ 1.1.1.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=55134[55134] Incremental
+compilation now deletes any additional class files generated during the
+weave phase when the class file from whence they came is deleted.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54621[54621] Incremental
+compilation will now detect changes (add, delete, modify) to class files
+in directories on the inpath and will include them in incremental
+compilation.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54621[54621] Incremental
+compilation will now detect changes to jars on the inpath (and injars),
+and trigger a full build if a jar is modified.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54622[54622] Incremental
+compilation will now detect changes to resources on the inpath.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=54618[54618] Incremental
+compilation will now detect changes to any of the paths affecting
+compilation, and triggers a full build if there has been any change
+since the last build.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=50200[50200] The
+aspectjrt.jar manifest file now has the correct (upper) case.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=49457[49457] No error
+given when overloading pointcuts, unless variables are bound.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=50776[50776] Compilation
+failure when overriding an inter-type declared method with a different
+throws clause.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=51919[51919] Polymorphic
+inter-type declaration fails.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=52464[52464] Declare
+warning coupled with inter-type declaration causes compiler crash.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=41125[41125] Variable
+names in the local variable table (for debugging) are now correctly
+preserved in all cases.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=43792[43792] Improved
+support for non-US locales (and significantly boosted weaver performance
+at the same time).
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=35636[35636] AspectJ 1.2
+behaves much more gracefully when running out of memory. (It also
+requires less memory than 1.1.1 did in any case).
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=42711[42711] Super-types
+of parameters not recognised when calling priveleged methods.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=43972[43972] (See also
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=45676[45676]). Incorrectly
+adding synthetic attribute to generated methods.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=45184[45184] External
+pointcut references not resolved when a named pointcut is used by a
+declare statement.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=46750[46750] Declare
+soft does not work inside a nested aspect.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=47754[47754] No error
+signalled when attempting to declare a static method on an interface
+using an inter-type declaration.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=48522[48522] Declare
+soft softens all exceptions at matched join points, not just the
+exception declared to be soft.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=49295[49295] AspectJ 1.2
+no longer supports inter-type constructor declarations on interfaces.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=51929[51929] Call to a
+protected super-type method within a advice body causes
+java.lang.VerifyError.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=52928[52928] Private
+members introduced via an interface are incorrectly visible within
+implementing classes.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=47910[47910] An output
+jar file created by AspectJ when using the -outjar option does not
+contain a valid manifest file.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=59909[59909] Thread
+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#
+
+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
+list of bug fixes] (49 in all) can be found on bugzilla.
+
+Some of the more significant bug fixes and enhancements in this release
+include:
+
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=40943[40943] The ajc
+compiler now copies resource files from jars specified using the -injars
+option. When compiling with source directories, resources are _not_
+copied - mirroring the behaviour of javac so as to cause minimum
+disruption when switching between ajc and javac. (To copy resources from
+source directories, use the iajc Ant task sourceRootCopyFilter option.)
+Thanks to Matthew Webster for contributing many of the patches for this
+enhancement.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=39626[39626] ajc was
+erroneously putting aspectjtools.jar in the classpath of a compilation.
+This caused problems when attempting to compile projects using different
+versions of any of the classes in aspectjtools.jar. Thanks to George
+Harley and Igor Hjelmstrom Vinhas Ribeiro for their assistance in
+tracking this down.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=40257[40257] Relative
+paths are now supported in ".lst" files.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=40771[40771] The Ajde
+apis are no longer coupled to swing. This is of most significance to
+AJDT users on the Mac OS X platform, enabling AJDT to be used with Mac
+OS X.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=41254[41254] Of interest
+to those writing tools that need to interact with the structure model
+for AspectJ programs: the interface to the AspectJ structure model was
+significantly revised and enhanced in 1.1.1.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=39462[39462] A compiler
+exception was thrown when an abstract aspect in a library was extended
+by a concrete aspect using cflow. Thanks to Takao Naguchi for an easy to
+reproduce bug report.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=39479[39479] Compiler
+crashes when a constructor delegates to another constructor that uses a
+switch statement. Thanks to Andy Clement for both the easy to reproduce
+bug report and the patch.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=41175[41175] Declared
+exceptions were being lost on inter-type declarations made from binary
+aspects in an aspect library.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=41359[41359] Aspect
+per-clauses were not inherited by sub-aspects when using binary aspect
+libraries. Thanks to Chris Bozic for the easy to reproduce bug report.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=42539[42539] The "+"
+pattern was being ignored for type patterns used in throws clauses.
+Thanks to Keith Sader for the easy to reproduce bug report.
+* https://bugs.eclipse.org/bugs/show_bug.cgi?id=40807[40807] If you
+specify no output directory, the iajc Ant task now defaults to using the
+source directory, following ajc and javac. As a result, now you can use
+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#
+
+This release contains mainly bug fixes for ajde and ajdoc.
+
+=== [#1.0.6compiler]#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
+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 Framework, AJBrowser, and AJDE for Forte/NetBeans*
+
+The memory use of the structure model has been streamlined in order to
+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
+
+JBuilder 7 is now supported.  All known bugs have been fixed including:
+
+* http://aspectj.org/bugs/resolved?id=787[787] AJDE for JBuilder throws
+exception given non-existent file
+* http://aspectj.org/bugs/resolved?id=788[788] Label too small in error
+message
+* http://aspectj.org/bugs/resolved?id=789[789] Index-out-of-bounds
+exception in JBuilder AJDE
+* http://aspectj.org/bugs/resolved?id=792[792] Required libraries
+disappear from JBuilder 6
+* http://aspectj.org/bugs/resolved?id=795[795] Unable to compile open
+tools
+* http://aspectj.org/bugs/resolved?id=802[802] AJDE loses current
+(cursor) position in file when switching files
+
+In addition, thanks to user feedback that indicated trouble building
+JBuilder OpenTools with AJDE/JBuilder, the OpenTool is now being built
+with itself.
+
+=== [#1.0.6ajdoc]#Ajdoc#
+
+* Fixed http://aspectj.org/bugs/resolved?id=790[790] aspect code
+comments suppressed by fix to bug 710
+* Known problems: http://aspectj.org/bugs/ajdoc
+
+'''''
+
+== [#1.0.5]#1.0.5#
+
+This release includes significant improvements to AspectJ Development
+Environment (AJDE) support. The entire user interface has been revised
+and streamlined. The AJDE features are more tightly integrated into
+JBuilder and NetBeans/Forte support. JBuilder support now includes
+graphical configuration file editing and an integrated AspectJ Browser
+tool.
+
+* xref:#1.0.5compiler[Compiler]
+* xref:#1.0.5ajde[AJDE]
+* xref:#1.0.5ajdoc[Ajdoc]
+* xref:#1.0.5anttasks[Ant tasks]
+
+=== [#1.0.5compiler]#Compiler#
+
+This was another compiler release primarily concerned with fixing corner
+cases in the language implementation. Our handling of nested classes,
+the assert statement, and cflow were the principal offenders this time.
+Thanks to Nicholas Alex Leidenfrost and Patrick Chan for their clear and
+concise bug reports on some of these issues.
+
+=== [#1.0.5ajde]#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.
+
+* The entire user interface has been revised and streamlined.
+* The structure view and browser have a new UI, and offer both a
+file-based and global structure views. All views expose node ordering,
+node filtering, and association filtering functionality. The global
+views expose a package tree as well as the global inheritance and
+crosscutting structure.
+* Structure view navigation now has a history exposed by back/forward.
+* The is a new build configuration management UI.
+* The compiler preferences UI now includes access to all build options.
+* Error messages have been improved, and the structure views include
+annotations of nodes with errors and warnings.
+
+==== AJDE for JBuilder
+
+Integration into the JBuilder IDE is more streamlined. In addition:
+
+* The AspectJ Browser is included as a tool that replaces JBuilder's
+"Project View" and can be used to navigate the global structure of your
+system (including the crosscutting and inheritance structure).
+* Inline structure annotations in the editor's gutter can now expose all
+of the structure presented in the structure view, and can be used to
+navigate in a similar way. Note that there are preferences for toggling
+which of these appear.
+* Building is better integrated and the JBuilder build toolbar is
+removed when AJDE is enabled.
+* Build configurations can be selected from the build button's menu.
+* Execution is better integrated: instead of a separate "run" button
+JBuilder's run and debug can be used. Note that for new projects you
+will need to use the "AspectJ Runtime" library, which will be added to
+your preferences automatically.
+* A new graphical build configuration editor can be used by
+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
+
+Integration into the NetBeans IDE is more streamlined. In addition:
+
+* NetBeans 3.3.2 and SunONE Studio 4 are supported.
+* Multiple filesystems are supported.
+* Default project build configurations (all project files) are now
+supported.
+* Build configurations can be selected in the tool bar.
+* Regular NetBeans execution and debugging is supported. Note that you
+have to add netbeans/lib/ext/aspectjrt.jar file to your project
+configuration.
+* Class files are generated beside source files (NetBeans/javac
+default). There is currently no way to specify a target directory.
+
+==== 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
+your path, and the class that you expect to execute on your classpath.
+* The error messages UI has been improved.
+
+=== [#1.0.5ajdoc]#Ajdoc#
+
+Bug fixes:
+
+* http://aspectj.org/bugs/resolved?id=710[710 - compiler-generated
+constructor shown with class comment]
+* http://aspectj.org/bugs/resolved?id=712[712 - comments lost in aspect
+docs for methods or constructors declared on other types.]
+* http://aspectj.org/bugs/resolved?id=719[719 - poor support for @link,
+@see tags]
+* http://aspectj.org/bugs/resolved?id=742[742 - crash with @see tag]
+* http://aspectj.org/bugs/resolved?id=751[751 - error loading doclet
+resource]
+
+=== [#1.0.5anttasks]#Ant tasks#
+
+Bug fixes:
+
+* http://aspectj.org/bugs/resolved?id=730[730 - document all supported
+ajc flags]
+
+'''''
+
+== [#1.0.4]#1.0.4#
+
+* xref:#1.0.4compiler[Compiler]
+* xref:#1.0.4ajde[AJDE]
+* xref:#1.0.4ajdoc[Ajdoc]
+* xref:#1.0.4taskdefs[Ant taskdefs]
+* xref:#1.0.4doc[Documentation]
+
+=== [#1.0.4compiler]#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
+into a nice error message. A number of other bug reports related to
+around advice and proceed have also been fixed, including the ability to
+change the bindings for `this` and `target` using proceed in around
+advice.
+* David Walend gets the _black thumb_ award for the most bug reports
+submitted by a new user. His bug report on the behavior of after
+returning advice led to some valuable clarifications of this part of the
+language spec.
+* A number of places where ajc didn't fully comply with the Java
+Language Spec have been fixed in this release. Thanks to Neal Gafter for
+reporting many of these.
+
+==== 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
+design. These changes will be signalled by clear warning or error
+messages at compile-time and will not cause any run-time surprises. We
+expect most users to never notice these changes.
+
+* The obsolete class `org.aspectj.lang.MultipleAspectsBoundException`
+has been removed from aspectjrt.jar. This class had not been used since
+AspectJ-0.8 and should have been removed prior to the 1.0 release. It is
+not documented as part of the 1.0 language spec. This change will cause
+a compile-time type not found error in any code that refers to this
+exception.
+* The compiler was not correctly implementing the AspectJ-1.0 language
+design for some uses of after returning advice. This compiler behavior
+was fixed, and advice whose behavior might be changed by this bug fix
+will be highlighted with a compiler warning. More information about some
+of these changes can be found in the xref:porting.adoc#pre-1.0.4[porting
+notes].
+
+=== [#1.0.4ajde]#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
+
+* Updates
+** This is a bug fix release only.
+
+==== AJDE for Forte/NetBeans
+
+* Updates
+** NetBeans 3.3.1 is now supported in addition to NetBeans 3.2 and Forte
+CE 3.
+** Native NetBeans main class execution can now be used. After doing a
+"Compile with AJC" browse to the main class in the "Filesystems"
+Explorer, right-click the class and select "Execute".
+** The debugger can now be used if the project main class is set
+("Project" menu -> "Set Project Main Class...").
+** Numerous bugs have been fixed.
+* Known limitations
+** Breakpoint setting does not work in the debugger.
+** In the "Filesystems" Explorer red Xs appear on files with AspectJ
+source code. The "AspectJ" Explorer understands the structure of AspectJ
+projects and should be used for navigating structure instead.
+
+==== AJDE for Emacs
+
+* This is a bug fix release only.
+
+=== [#1.0.4ajdoc]#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#
+
+* Repackaged to fit into the AspectJ product directory - e.g.,
+`aspectj-ant.jar` moved to `lib` as expected by `examples/build.xml`.
+* Fixed bugs, esp. http://aspectj.org/bugs/resolved?id=682[682]: Throw
+BuildException if failonerror and ajdoc detects misconfiguration.
+
+=== [#1.0.4doc]#Documentation#
+
+Added a 1-page quick reference guide. Improved javadoc documentation for
+the org.aspectj.lang package.
+
+'''''
+
+== [#1.0.3]#1.0.3#
+
+* xref:#1.0.3compiler[Compiler]
+* xref:#1.0.3taskdefs[Ant taskdefs]
+
+=== [#1.0.3compiler]#Compiler#
+
+This release fixes a single significant bug in 1.0.2 where ajc could
+generate unreachable code in `-usejavac` or `-preprocess` mode. This
+would happen when around advice was placed on void methods whose body
+consisted solely of a `while (true) {}` loop. We now properly handle the
+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#
+
+Added support to the Ajc taskdef for the -source 1.4 and -X options
+generally.
+
+'''''
+
+== [#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
+new 1.4 assertions and running on the 1.4 VM. In honor of the public
+review of JSR-45 Debugging Support for Other Languages we implement this
+spec for AspectJ. We support Borland's recent release of JBuilder 6, and
+since some of our users are starting to work on Mac OSX, AJDE now works
+nicely on this platform. We also fixed almost all of the bugs you
+reported in 1.0.1.
+
+* xref:#1.0.2compiler[Compiler]
+* xref:#1.0.2ajde[AJDE]
+* xref:#1.0.2ajdb[AJDB]
+
+=== [#1.0.2compiler]#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
+assertions]. This makes ajc completely compatible with j2se-1.4.
+* Implementation of http://jcp.org/jsr/detail/45.jsp[JSR-45 Debugging
+Support for Other Languages] so that debuggers which correctly implement
+this specification will be able to accurately debug any AspectJ program
+at a source code level. We are not currently aware of any debuggers that
+implement this so far, but expect that as j2se-1.4 becomes widely
+available this will change.
+* As proposed by Arno Schmidmeier and seconded by Nick Lesiecki, we now
+have an experimental `-Xlint` option that will provide warnings when
+type patterns used in pcds have no bindings. We are very interested in
+feedback on the usefulness and suggested improvements for this feature.
+* Several significant bugs in the implementation of around advice have
+been fixed. These include issues with
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=632[dynamic
+tests], with
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=620[complicated
+local types in an around body], and with
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=636[capturing
+proceed in a closure].
+* All but two
+(http://aspectj.org/jitterbug/aspectj-bugs/compiler?id=626[1],
+http://aspectj.org/jitterbug/aspectj-bugs/compiler?id=645[2]) verified
+bugs in 1.0.1 have been fixed. The two outstanding bugs have relatively
+easy work-arounds. Thanks as usual to everyone who submitted a bug
+report.
+* We no longer use the `SYNTHETIC` attribute to label declarations added
+by the aspectj compiler. We were using this attribute in compliance with
+http://java.sun.com/docs/books/vmspec/2nd-edition/html/ClassFile.doc.html#80128[the
+JVM Specification]; however, we've found that many tools expect this
+attribute to only be used for the narrow purpose of implementing Java's
+inner classes and that using it for other synthetic members can confuse
+them. This led to problems both
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=649[with javap]
+and http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=646[with
+javac].
+* Changes required adding runtime classes, so please compile and run
+using the latest `aspectjrt.jar`
+
+=== [#1.0.2ajde]#AJDE#
+
+This is a bug fix release only.
+
+* Thanks to Dave Yost and Matt Drance for submitting the AJDE patches
+for Mac OSX (context popup menus and keyboard shortcuts did not work).
+* Bugs in history navigation (back-forward buttons in the structure
+view) have been fixed.
+* "Declares" are now handled properly in the structure view.
+* Other GUI and usability improvements have been made the AspectJ
+Browser and core framework.
+
+==== AJDE for JBuilder
+
+* Support has been extended to JBuilder 6, and support for Enterprise
+version features has been improved.
+* Fixed bug causing inline source code annotations in the editor pane to
+not be updated after a recompile.
+* Keyboard shortcuts were fixed to work with Mac OSX.
+
+==== AJDE for Forte
+
+* Keyboard shortcuts were fixed to work with Mac OSX.
+
+==== [#1.0.2ajdb]#AJDB#
+
+Some minor bug fixes, but this is still early-access software. Please
+try using another JPDA-compliant debugger. If it uses JDI correctly,
+then it should navigate to line numbers when the classes are run under
+J2SE1.4, based on the new JSR-45 debugging support described above. We
+would appreciate any reports of success or failure.
+
+'''''
+
+== [#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#
+
+This release fixes a significant performance issue in the compiler,
+reported by Rich Price, that could lead to extremely long compiles in
+systems with many aspects and classes. Several other small bugs related
+to reporting compilation errors have also been fixed, see
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=610[this bug
+report] for an example.
+
+A new experimental flag has been added, `-XaddSafePrefix`, that will
+cause the prefix `aspectj$` to be inserted in front of all methods
+generated by ajc. This mode should be helpful when using aspectj with
+tools that do reflection based on method names, such as EJB tools.
+Thanks to Vincent Massol for pointing out the importance of this. It is
+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#
+
+Minor bug fixes, including: AJDE for JBuilder failed to preserve
+application parameters from project settings when executing the
+application.
+
+Source builds were cleaned up for JBuilder and Forte sources.
+
+=== [#1.0.1ajdb]#AJDB#
+
+Two bugs were reported and have been fixed in this release. (Note that
+ajdb is still considered early-access software.)
+
+* bug 611: NullPointerException dumping non-primitive values
+* bug 617: -X and -D options not passed to debug VM correctly
+
+== [#1.0.0]#1.0.0#
+
+* xref:#1.0.0language[Language]
+* xref:#1.0.0compiler[Compiler]
+* xref:#1.0.0ajde[AJDE]
+* xref:#1.0.0ajdoc[AJDoc]
+* xref:#1.0.0taskdefs[Ant taskdefs]
+
+== [#1.0.0language]#Language#
+
+There were no language changes for this release.
+
+== [#1.0.0compiler]#Compiler#
+
+Several minor bugs primarily in error handling were reported and have
+been fixed in this release. The two most serious bugs are described
+below:
+
+* Niall Smart and Stephan Schmidt reported related bugs (variants of
+which are also produced by other compilers) that caused verify errors
+when dealing with nested try-finally and synchronized statements. These
+are now fixed. More details are available
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=601[here] and
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=595[here]
+* Jan Hannemann submitted a
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=600[succint and
+clear bug report] for a difficult intermittant bug. The bug led to the
+compiler sometimes generating illegal code when introduced methods on a
+class overrode introduced methods on an interface implemented by that
+class. This is now fixed.
+
+== [#1.0.0ajde]#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
+
+* 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
+
+* The AspectJ Browser now uses Forte's icons and distinguishes nodes by
+visibility
+
+=== AJBrowser
+
+* Documentation for the browser is now available at
+http://aspectj.org/docs
+
+=== 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#
+
+* 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.
+* Disabled some non-functioning options, documented as `unsupported` in
+the syntax message.
+
+=== [#1.0.0taskdefs]#Ant taskdefs#
+
+* Fork is not supported in the AJDoc taskdef
+
+== [#1.0rc3]#1.0rc3#
+
+== [#1.0rc3language]#Language#
+
+There have been several minor clarifications/changes to the language.
+
+* Thanks to Robin Green for suggesting that we could relax the rules for
+inheriting multiple concrete members in order to allow those unambiguous
+cases where one member has already overridden the other.
+http://aspectj.org/pipermail/users/2001/001289.html[More details...]
+* Ron Bodkin encouraged us to examine the details of privileged aspects
+more closely. This led to several small improvements and clarifications
+to this language feature.
+http://aspectj.org/pipermail/users/2001/001258.html[More details...]
+
+== [#1.0rc3compiler]#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
+javac rather than necessarily following the Java Language Specification.
+
+* Hanson Char reported a bug where ajc's correctly generated bytecodes
+for some references to interface fields result in verify errors on
+certain JVMs. While this is a known bug in those JVMs, we've modified
+ajc to be bug compatible with all the other Java compilers out there to
+work-around this JVM bug.
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=551[More
+details...]
+* Frank Hunleth discovered a similar bug where ajc's correct bytecodes
+could lead to essentially random method dispath due to a bad bug in the
+1.3.0 JVM from Sun. Even though this bug was fixed in the 1.3.1 and
+1.2.2 JVMs, we have introduced the appropriate work-around in ajc's code
+generation.
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=580[More
+details...]
+* Thomas Haug (as well as several other members of his group) reported a
+problem with name binding where ajc was behaving differently than javac.
+This problem was resolved to come from a class created by an obfuscator
+that conflicted with his package names. The JLS doesn't clearly specify
+which of these two behaviors is correct. Nevertheless, ajc has been
+changed to treat packages more like javac does in order to minimize this
+sort of problem in the future.
+http://aspectj.org/jitterbug/aspectj-bugs/resolved?id=574[More
+details...]
+* Several "real" bugs in ajc were also reported and fixed. Toby Allsopp
+gets credit for reporting two of them. The most interesting of these
+bugs to me was his report that we just didn't support qualified
+anonymous inner constructors. This is a part of the Java language that
+ajc has never supported over its almost 3 year history. We'd just
+noticed this ourselves when running the jacks compiler test suite from
+the jikes group, and had added the feature days before getting our first
+bug report for it not being there.
+
+== [#1.0rc3ajde]#AJDE#
+
+* The structure view has been improved.
+* Multiple user-configurable views are supported.
+* Structure tree filtering and ordering has been added.
+* A split tree mode has been added to permit the navigation of multiple
+views on the same structure.
+* The view can also be toggled between a file-based and a system-based
+mode which determines whether the root of the structure tree is the
+current file or the project root.
+* The signatures of tree nodes have been improved and several new node
+associations are now navigable.
+* A depth slider for controlling tree-expansion has been added.
+
+=== AJDE for JBuilder
+
+* Changes:
+* Inline annotations support have been improved and made consistent with
+the structure tree (annotations only show up for intra-declaration
+structure).
+* The current structure view persists across IDE launches.
+* An enabled AJDE no longer slows down JBuilder shutdown.
+
+=== AJDE for Forte
+
+* Execution remembers main class.
+* The bug causing an error during a "Mode" and "Explorer" switch has
+been fixed.
+
+=== AJBrowser
+
+* AJBrowser is currently an undocumented demonstration application. To
+use it type: ajbrowser <lst file1> <lst file2> ...
+* 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
+
+* 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#
+
+Some of the more obvious NullPointerException bugs in Ajdoc were fixed,
+but Ajdoc does not implement all the functionality of Javadoc and has
+some bugs:
+
+* Split indexes do not work correctly
+* Inner classes are not listed in indexes
+* Synthetic methods are documented
+* There is no package frame even when packages are specified on the
+command line
+* -group option is not implemented
+* -use targets are not all calculated correctly
+* Exception information may not be printed for the @throws tag
+* Verbose output should go to stderr, not stdout
+* Extra links are generated (should be unlinked text)
+
+Further, Ajdoc has not been testing on variants of the J2SE (it uses
+javadoc classes).
+
+=== [#1.0rc3taskdefs]#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
+Vincent Massol for a bug report listing the line number of the fix). The
+AJDoc cannot be run repeatedly in a single Ant run, and has trouble
+loading the doclet unless the libraries are installed in
+$\{ant.home}/lib.
+
+'''''
+
+== [#1.0rc2]#1.0rc2#
+
+* xref:#1.0rc2language[Language]
+* xref:#1.0rc2compiler[Compiler]
+* xref:#1.0rc2ajde[AJDE]
+
+== [#1.0rc2language]#Language#
+
+There are no language changes in this release. This is a bug fix release
+only.
+
+== [#1.0rc2compiler]#Compiler#
+
+A bug in handling inner type names that conflict with enclosing type
+names was fixed. Many error messages were improved.
+
+== [#1.0rc2ajde]#AJDE#
+
+* This is a bug fix release only.
+
+=== AJDE for JBuilder
+
+* Changes:
+** Fixed bug causing the output path to be ignored and .class files to
+be generated into the JBuilder install's "bin" directory.
+** Fixed bugs in Browser listener causing NullPointerExceptions to be
+thrown if no node editor was present.
+** Fixed bug permitting "-bcg" option to be passed to the compiler.
+** Fixed bug preventing ajc from compiling all of the project source
+files when automatic package discovery was on (JBuilder Proffessional
+and Enterprise editions).
+** If the "-preprocess" flag is used resulting source files will be
+placed in the project's "Working directory".
+* Limitations:
+** "Automatic package discovery" mode is not supported in this release.
+** The debugger has not seen much use and it's stability and performance
+is limited.
+
+=== AJDE for Forte
+
+* Changes:
+** Moved the "AspectJ" menu into the "Tools" menu in order to make it
+less intrusive.
+** Added a "ctrl-alt-shift-F9" keyboard compile shortcut.
+* Limitations:
+** Known bug: "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 to be restarted for the AspectJ window to show again.
+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
+
+* Changes:
+** ...
+* Limitations:
+** AJBrowser is currently an undocumented demonstration application. To
+use it type: +
+> ajbrowser <lst file1> <lst file2> ...
+
+=== Emacs Support: aspectj-mode and AJDEE
+
+This release now properly displays annotations for call sites and
+introductions. Robustness has been improved in several dimensions,
+including performance at startup. The compile menu now recomputes
+properly when changing directories.
+
+'''''
+
+== [#1.0rc1]#1.0rc1#
+
+* xref:#1.0rc1language[Language]
+* xref:#1.0rc1compiler[Compiler]
+* xref:#1.0rc1ajde[AJDE]
+
+== [#1.0rc1language]#Language#
+
+Some of the details of the specification for perthis and pertarget have
+changed. These changes make these language constructs implementable on
+current JVMs without memory leaks (this wasn't true of the previous
+version). Most people will probably not notice these changes, but the
+correct semantics are described in link:progguide/semantics.html[the
+semantics section of the programming guide].
+
+In a related change, aspects are not allowed to implement either the
+`java.io.Serializable` or the `java.lang.Cloneable` interface. It is
+unclear what the correct behavior of a system should be when an aspect
+is serialized or cloned, and rather than make an arbitrary choice right
+now we've chosen to leave the most room to design them right in a future
+release.
+
+== [#1.0rc1compiler]#Compiler#
+
+ajc now directly generates .class files without using javac as a
+back-end. This should result in improved compiler performance, better
+error messages and better stack-traces and debugging info in those
+.class files. -preprocess mode is still available for those who want to
+generate legal Java source code and a new -usejavac mode is available if
+you have a requirement to continue to use javac as a back-end.
+
+ajc now officially supports source files with the .aj extension. We plan
+to extend this support to the rest of our tools as time permits.
+
+This release of ajc includes support for the "-source 1.4" option that
+enables the new 'assert' keyword in jdk1.4. This option only works
+correctly when compiling against the jdk1.4 libraries. In addition, this
+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#
+
+* The structure view can now be configured (using the "Options" dialog)
+to display different kinds of associations between program elements that
+appear in the tree.
+* Structure view history navigation has been added.
+* When navigating links the structure view will stay synchronized with
+the editor.
+
+=== AJDE for JBuilder
+
+* Changes:
+** Inline structural navigation annotations appear in the gutter of the
+editor and can be used to navigate associations such as advice and
+introduction.
+* Limitations:
+** "Automatic package discovery" mode is not supported in this release.
+** The debugger has not seen much use and it's stability and performance
+is limited.
+
+=== AJDE for Forte
+
+* Changes:
+** Support for Forte 3 and Netbeans 3.2 has been added.
+** The module is now installed by default on the first use without
+having to go to the IDE options to enable it.
+* Limitations:
+** Known bug: "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 to be restarted for the AspectJ window to show again.
+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
+
+* Changes:
+** Build configuration file editor added.
+* Limitations:
+** AJBrowser is currently an undocumented demonstration application. To
+use it type: +
+> ajbrowser <lst file1> <lst file2> ...
+
+=== 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
+view. Also, advice are now shown on non-declarations, when appropriate,
+such as call advice. The internal event model has been revised to reduce
+computational overhead.
+
+'''''
+
+== [#1.0beta1]#1.0beta1#
+
+* xref:#1.0beta1language[Language]
+* xref:#1.0beta1compiler[Compiler]
+* xref:#1.0beta1ajbrowser[AJBrowser]
+* xref:#1.0beta1ajde[AJDE]
+
+== [#1.0beta1language]#Language#
+
+There is one language change since 1.0alpha1. The static modifier is no
+longer needed or allowed on pointcut declarations. Name binding for
+pointcut declarations works like class methods now. Thanks to Robin
+Green for encouraging us to look at this one last time.
+
+The current implementation of perthis/pertarget has the possibility of
+memory leaks (thanks to Arno Schmidmeier for pointing this out). The
+design of this part of the language will almost certainly see some
+changes in the next release to address issues of implementability on the
+JVM as well as related issues.
+
+== [#1.0beta1compiler]#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
+report any errors in 'ajworkingdir' as bugs.
+
+All reported bugs in 1.0alpha1 have been fixed. Thanks to everyone for
+your bug reports. Most notably, the 'if' pcd that was added in 1.0alpha1
+should work correctly in this release. Thanks to Morgan Deters for a
+very thorough bug report on this broken feature days after the 1.0alpha1
+release.
+
+== [#1.0beta1ajbrowser]#AJBrowser#
+
+* Support for executing classes has been added.
+* .lst can now be passed as arguments on the command line.
+* Compiler options can be set.
+* Know limitations:
+** In order to execute classes they must be available on the classpath
+that the browser is launched with.
+
+== [#1.0beta1ajde]#AJDE#
+
+* The performance and UI of the structure tree has been improved.
+* Compilation now runs in a separate thread and a progress monitor is
+updated during the compile.
+* The structure view now persists across IDE launches.
+* Limitations:
+** If an error occurs in the javac pass it will not display properly in
+the error messages pane. To view the error you have check the output of
+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
+
+* Known bugs have been fixed.
+* Classpath separator character is no longer hardcoded.
+* Keyboard shortcuts for compilation (ctrl-F11) and execution (ctrl-F12)
+have been added.
+* Limitations:
+** The debugger has not seen much use and it's stability and performance
+is limited.
+
+=== AJDE for Forte
+
+* Known bugs have been fixed.
+* 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
+to be restarted for the AspectJ window to show again.
+** There are no keyboard compile/execute shortcuts.
+** The debugger has not seen much use and it's stability and performance
+is limited.
+
+=== 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
+extension of JDE). Additionally, a switch, -emacssym, has been added to
+ajc that generates AspectJ declarations information directly, thus
+beanshell is no longer required for use of these modes.
+
+'''''
+
+== [#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
+tools. We wish to thank our users for putting up with the high
+volatility of AspectJ in the push to 1.0.
+
+* xref:#1.0alpha1language[Language]
+* xref:#1.0alpha1compiler[Compiler]
+* xref:#1.0alpha1documentation[Documentation]
+* xref:#1.0alpha1ajdoc[AJDoc]
+* xref:#1.0alpha1ant[Ant]
+* xref:#1.0alpha1ajbrowser[AJBrowser]
+* xref:#1.0alpha1ajde[AJDE]
+
+=== [#1.0alpha1language]#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.
+Each email we've received either making a suggestion or just asking a
+question about a confusing part of the language has played a part in
+shaping this design. We'd like to thank all of our users for their
+contributions.
+
+While we don't have room to thank all of our users by name, we'd like to
+specifically mention a few people for their high-quality sustained
+contributions to the users@aspectj.org mailing list as well as through
+their feature requests and bug reports. Robin Green (who'll be very
+happy to see `declare error`), Stefan Hanenberg (who should appreciate
+the '+' wildcard in type patterns), and Rich Price (who suggested final
+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
+
+Perhaps the least interesting -- but most pervasive -- change is that
+the names of the single-kinded pointcut designators (the ones that pick
+out only one kind of join point)
+
+____
+calls executions gets sets handlers initializations
+staticinitializations
+____
+
+have been xref:porting.adoc#1.0a1-plural-to-singular[changed] to be
+singular rather than plural nouns
+
+____
+call execution get set handler initialization staticinitialization
+____
+
+Although a side benefit is that the names are one character shorter, the
+real benefit is that their combination with the `&&` and `||` operators
+now reads much more naturally. No longer does "and" mean "or" and "or"
+mean "and".
+
+You'll notice that `receptions` doesn't appear on the table as being
+shortened to `reception`. That's because call and reception join points
+have been merged, and the `receptions` pointcut declaration has been
+xref:porting.adoc#1.0a1-remove-receptions[eliminated]. Now, `call` join
+points describe the action of making a call, including both the caller
+and callee. Eliminating reception join points makes AspectJ much simpler
+to understand (reception join points were a commonly misunderstood
+feature) without giving up expressive power.
+
+We have xref:porting.adoc#1.0a1-fixing-state-access[changed the
+mechanism for accessing state] at join points, which has the benefit of
+making our treatment of signatures
+xref:porting.adoc#1.0a1-no-subs-in-sigs[cleaner] and easier to read. As
+a part of this, the `instanceof` pointcut designator has now been
+xref:porting.adoc#1.0a1-fixing-instanceof[split into two different
+pointcut designators], `this` and `target`, corresponding to a join
+point's currently executing object and target object, respectively.
+
+The new `args` pointcut adds expressive power to the language by
+allowing you to capture join points based on the actual type of an
+argument, rather than the declared type of its formal. So even though
+the `HashSet.removeAll` method takes a `Collection` as an argument, you
+can write advice that only runs when it is actually passed a `HashSet`
+object.
+
+AspectJ's notion of object construction and initialization, a
+complicated process in Java, has been clarified. This affects some uses
+of the xref:porting.adoc#1.0a1-initializations[initializations pointcut]
+and xref:porting.adoc#1.0a1-constructor-calls[constructor calls]
+pointcut.
+
+The little-used pointcuts xref:porting.adoc#1.0a1-hasaspect[`hasaspect`]
+and xref:porting.adoc#1.0a1-withinall[`withinall`] have been removed.
+
+The `returns` keyword is xref:porting.adoc#1.0a1-user-defined-returns[no
+longer necessary] for user-defined pointcuts.
+
+Pointcuts may now be declared `static`, and
+xref:porting.adoc#1.0a1-static-pointcuts[only static pointcuts] may be
+declared in classes and referred to with qualified references (such as
+`MyAspect.move()`).
+
+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
+
+Our treatment of xref:porting.adoc#1.0a1-new-wildcards[* and ..] in type
+patterns is cleaner.
+
+Type patterns now have the ability to include array types, and there is
+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
+
+Around advice is treated much more like a method, with a
+xref:porting.adoc#1.0a1-around-returns[return value] and an optional
+xref:porting.adoc#1.0a1-around-throws[throws clause].
+
+The advice precedence rules have been
+xref:porting.adoc#1.0a1-advice-precedence[changed]. Now, for example, a
+piece of after advice that appears lexically later than another piece of
+after advice will run later, as well. Previously, the relationship was
+the other way around, which caused no small amount of confusion.
+
+After returning advice has lost a
+xref:porting.adoc#1.0a1-after-returning[useless set of parentheses] when
+not using the return value.
+
+The `thisStaticJoinPoint` reflective object has been
+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
+
+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
+statically-crosscutting properties. One of these properties is
+subtyping, so we've
+xref:porting.adoc#1.0a1-plus-implements-extends[gotten rid of] the ugly
+keywords `+implements` and `+extends`.
+
+We have provided two new forms, `declare error` and `declare warning`,
+for the often-asked-for property of compile-time error detection based
+on crosscutting properties.
+
+AspectJ's interaction with checked exceptions is now firmly on the side
+of static crosscutting, since Java treats such exceptions at
+compile-time. A new form, `declare soft`, can be used to "soften"
+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
+
+The "of each" modifiers have been
+xref:porting.adoc#1.0a1-aspects[renamed]. Apart from the spelling, the
+main interesting difference is the splitting up of `of eachobject` into
+two different modifiers, parallel with the split of `instanceof` into
+`this` and `target`.
+
+The `dominates` keyword now takes a type pattern, rather than a type.
+This allows an aspect A, for example, to declare that its advice should
+dominate the advice of another aspect B as well as its subtypes, with
+the new + subtypes operator: `aspect A dominates B+`.
+
+=== [#1.0alpha1compiler]#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
+fixed. Thanks for your bug reports.
+
+The compiler also gets a new `-encoding` flag in this release for
+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
+
+The previous compiler's limitations regarding join points that occurred
+in anonymous classes have all been eliminated. Unfortunately,
+eliminating this restriction has resulted in preprocessed source code
+that is less readable than in previous releases. More care will be taken
+in the next release to mitigate this effect.
+
+Many semantic errors are not caught by ajc but fall through to javac.
+Moreover, some errors regarding the initialization of final fields might
+never show up when using ajc. This will be fixed shortly.
+
+=== [#1.0alpha1documentation]#Documentation#
+
+Although we spent much of our time this release cycle updating the
+documentation to the new language rather than improving its content, we
+did make some structural improvements. The old Primer has been split
+into a Programming Guide, covering the language, and a Development
+Environment Guide, covering the develompent tools. In addition,
+printable versions of both guides (in PDF) are finally included in the
+documentation package.
+
+=== [#1.0alpha1ajdoc]#Ajdoc#
+
+Ajdoc was rewritten to conform with the language changes and provide
+support for other AspectJ/Java compilers. Our doclet is used by default
+creating AspectJ-specific documentation, or Sun's standard doclet can be
+used by passing the '-standard' flag to Ajdoc to produce regular Javadoc
+documentation (excluding AspectJ-specifics).
+
+=== [#1.0alpha1ant]#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#
+
+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 for JBuilder
+
+===== Installation
+
+* Use the installer to place the "ajdeForJBuilder.jar" and
+"aspectjrt.jar" in to JBuilder's lib/ext directory.
+
+===== Key Improvements
+
+* The "AspectJ Structure View" replaces JBuilder's structure view
+instead of being launched in a separate window.
+* 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
+removed.
+* Projects no longer require the manual adding of the "aspectjrt.jar"
+libarary.
+
+===== 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.
+* There are no keyboard compile/execute shortcuts.
+* The structure view is not persistent between IDE launches--you must
+compile to view the structure for a program.
+* The debugger has not seen much use and it's stability and performance
+is limited.
+* There is no ajdoc tool support.
+* Linux testing has been very limited.
+
+==== AJDE for Forte
+
+===== Installation
+
+* Use the installer to place the "ajdeForForte.jar" in Forte's modules
+directory and "aspectjrt.jar" in to Forte's lib/ext directory.
+* In the "Tools" menu select "Global Options"
+* Right-click the "Modules" item and select "New Module from File..."
+* Find the ajdeForForte.jar in the directory that you installed into
+(e.g. c:\forte4j\modules) and select it.
+
+===== 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
+removed.
+* The AJDE functionality is now contained within it's own toolbar and
+menu.
+
+===== 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
+to be restarted for the AspectJ window to show again.
+* 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.
+* There are no keyboard compile/execute shortcuts.
+* The structure view is not persistent between IDE launches--you must
+compile to view the structure for a program.
+* The debugger has not seen much use and it's stability and performance
+is limited.
+* There is no ajdoc tool support.
+* Linux testing has been very limited.
+
+==== 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
+projects. See the README and CHANGES files in the distribution for
+additional details.
+
+AJDEE is now compatible with JDEE 2.2.7.1, JDEE 2.2.8beta4, and speedbar
+0.14alpha. It a toggle in the AspectJ menu that disables its intrusive
+functions, enabling easy switching between Java and AspectJ projects.
+See the README and CHANGES files in the distribution for additional
+details.
+
+'''''
diff --git a/docs/dist/doc/examples/spacewar/README.adoc b/docs/dist/doc/examples/spacewar/README.adoc
new file mode 100644
index 000000000..624dd0ffc
--- /dev/null
+++ b/docs/dist/doc/examples/spacewar/README.adoc
@@ -0,0 +1,54 @@
+© Copyright 1997-2001 Xerox Corporation. All rights reserved.
+
+*Last updated*: January 10, 2001
+
+
+
+== [#5]#Exploring the Spacewar Example#
+
+The code in this directory is an implementation of the classic video
+game Spacewar.
+
+The Spacewar game is intended to provide a modest-sized example of a
+program that uses aspects. The code for this example is evolving, as we
+add new features to AspectJ and come up with a better understanding of
+how to use the features.
+
+In order to compile and run this example, make sure to have the latest
+version of AspectJ correctly installed. If you're not sure you do, try
+the helloworld example first by following the instructions in
+xref:../doc/primer/default.html[Primer] section Getting Started.
+
+=== [#5.1]#Compiling Spacewar#
+
+* Change to the `examples` directory.
+* Type `ajc -argfile spacewar/demo.lst` to compile the system.
+
+=== [#5.2]#Running Spacewar#
+
+* In the examples directory, type `java spacewar.Game`
+
+When the game starts up you will see two different displays. These are
+the two built-in display aspects of the game. In each you will see a
+single white ship and two red ships. The white ship is yours to control;
+the red ships are an enemy robots. Your ship is controlled with the four
+arrow keys to turn, thrust and stop; the spacebar fires. As you play,
+the game will be displayed in both windows.
+
+When running on a 1.4 or later VM, click in the main panel to give it
+focus so that your keystrokes are recognized.
+
+You can quit the game with ctl-Q.
+
+=== [#5.3]#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
+debugging aspect for the game.
+
+We recommend you explore the Spacewar source code and look at the
+aspects that it uses. You will find several of them, of different scales
+and different degrees of cross-cutting. Remember that these represent
+our evolving understanding of how to use AspectJ to implement Spacewar.
+If you believe we should be doing something differently, then please let
+us know.
diff --git a/docs/dist/doc/examples/spacewar/README.html b/docs/dist/doc/examples/spacewar/README.html
deleted file mode 100644
index a9ec265b4..000000000
--- a/docs/dist/doc/examples/spacewar/README.html
+++ /dev/null
@@ -1,82 +0,0 @@
-<html>
-
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
-<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
-<meta name="ProgId" content="FrontPage.Editor.Document">
-<title>Space War</title>
-</head>
-
-<body BGCOLOR="white">
-
-<P>&copy; Copyright 1997-2001 Xerox Corporation. All rights
-reserved.</P>
-
-<P><B>Last updated</B>: January 10, 2001</P>
-
-<p>&nbsp;</p>
-
-
-
-<h2><a name="5">Exploring the Spacewar Example</a></h2>
-
-<P>The code in this directory is an implementation of the
-classic video game Spacewar.</P>
-
-<P>The Spacewar game is intended to provide a modest-sized example of
-a program that uses aspects.  The code for this example is evolving,
-as we add new features to AspectJ and come up with a better
-understanding of how to use the features.</P>
-
-<P>In order to compile and run this example, make sure to have the latest
-version of AspectJ correctly installed. If you're not sure you do, try the
-helloworld example first by following the instructions in <a href="../doc/primer/default.html">Primer</a>
-section Getting Started.</P>
-
-<h3><a name="5.1">Compiling Spacewar</a></h3>
-
-<ul>
-<li> Change to the <code>examples</code> directory. </li>
-
-<li> Type <code><strong>ajc -argfile spacewar/demo.lst</strong></code> to compile the
-     system.</li>
-</ul>
-
-<h3><a name="5.2">Running Spacewar</a></h3>
-
-<ul>
-<li> In the examples directory, type <code><strong>java spacewar.Game</strong></code></li>
-</ul>
-
-<p>When the game starts up you will see two different displays.  These
-are the two built-in display aspects of the game.  In each you will
-see a single white ship and two red ships.  The white ship is yours
-to control; the red ships are an enemy robots.  Your ship is controlled
-with the four arrow keys to turn, thrust and stop; the spacebar
-fires.  As you play, the game will be displayed in both windows.</p>
-
-<p>When running on a 1.4 or later VM, click in the main panel to give
-	it focus so that your keystrokes are recognized.</p>
-
-<p>You can quit the game with ctl-Q.</p>
-
-<h3><a name="5.3">Exploring the Code</a></h3>
-
-<p>There is one other built-in configurations for the Spacewar game.
-Try it by typing <code><strong>ajc @spacewar\debug.lst</strong></code>.  This
-compiles in an elaborate debugging aspect for the game.
-
-</p>
-
-<p> We recommend you explore the Spacewar source code and look at the
-aspects that it uses.  You will find several of them, of different
-scales and different degrees of cross-cutting.  Remember that these
-represent our evolving understanding of how to use AspectJ to
-implement Spacewar.  If you believe we should be doing something
-differently, then please let us know.
-</p>
-
-
-</body>
-
-</html>
diff --git a/docs/dist/doc/index.adoc b/docs/dist/doc/index.adoc
new file mode 100644
index 000000000..cfde98826
--- /dev/null
+++ b/docs/dist/doc/index.adoc
@@ -0,0 +1,231 @@
+[#top]##
+
+== AspectJ Documentation and Resources
+
+AspectJ ^[.small]#tm#^ is a seamless aspect-oriented extension to
+Java^[.small]#tm#^. The compiler and development tools are available
+under an open-source license, require Java 1.3 to run, and produce code
+that runs in JDK 1.1 and later VM's. For the latest materials, see
+http://eclipse.org/aspectj. Not all of these materials have been updated
+for AspectJ 5.
+
+[cols=",",]
+|===
+|+++Section+++ |+++Contents+++
+
+|xref:#documentation[docs] |link:faq.html[FAQ], link:quick5.pdf[Quick
+Reference (AspectJ 5)], link:quick.pdf[Quick Reference (1.2.1)],
+link:adk15notebook/index.html[AspectJ 5 Developer's Notebook],
+link:progguide/index.html[programming],
+link:devguide/index.html[development] and
+link:pdguide/index.html[problem diagnosis] guides,
+link:runtime-api/index.html[API] and link:examples/[example code].
+
+|xref:#distributions[distributions]
+|http://eclipse.org/aspectj[AspectJ]; development environment support
+for http://eclipse.org/ajdt[Eclipse] and
+https://jdeveloperaop.dev.java.net/[JDeveloper].
+
+|xref:#resources[resources] |http://aosd.net[aosd.net];
+http://eclipse.org/aspectj[AspectJ project] the bug
+http://bugs.eclipse.org/bugs[db], and mailing lists for
+mailto:aspectj-users@eclipse.org[users] and
+mailto:aspectj-dev@eclipse.org[developers].
+
+|xref:#paths[paths] |for those new to AspectJ
+|===
+
+[#documentation]##
+
+=== AspectJ documentation
+
+[width="100%",cols="50%,50%",options="header",]
+|===
+|Documentation |Description
+|link:quick5.pdf[AspectJ 5 Quick Reference] |This is a four-page quick
+reference for the AspectJ 5 language.
+
+|link:quick.pdf[AspectJ Quick Reference] |This is a two-page quick
+reference for the AspectJ language.
+
+|link:adk15notebook/index.html[AspectJ 5 Developer's Notebook]
+(printable link:adk15notebook/printable.html[html]) |This describes the
+changes to the AspectJ language and tools introduced in the AspectJ 5
+Development Kit. These changes are additive, and are not yet reflected
+in the programming guide or quick reference.
+
+|link:progguide/index.html[Programming Guide] (printable
+link:progguide/printable.html[html]) |This introduces AOP and the
+AspectJ language. link:progguide/starting.html[Getting Started]
+describes basic semantics, and shows development- and production-time
+applications. link:progguide/language.html[The AspectJ Language]
+describes join points, pointcuts, advice, and introduction, all features
+new to AOP. link:progguide/examples.html[Examples] walks you through the
+examples included with the documentation, and there are two short
+chapters on useful link:progguide/idioms.html[Idioms] and a few
+link:progguide/pitfalls.html[Pitfalls] The appendices have reference
+information: the link:progguide/quick.html[Quick Reference] summarizes
+AspectJ syntax, the link:progguide/semantics.html[Language Semantics]
+best describes AspectJ usage, and
+link:progguide/implementation.html[Implementation Notes] describes how
+the current version is limited to code the compiler controls.
+
+|link:devguide/index.html[Development Environment Guide] +
+(printable link:devguide/printable.html[html]) |This is a guide to
+link:devguide/ajc-ref.html[ajc], the command-line compiler;
+link:devguide/ajbrowser.html[ajbrowser], the stand-alone GUI for
+compiling and viewing crosscutting structure; and the
+link:devguide/antTasks.html[Ant tasks] for building AspectJ programs.
+
+|link:pdguide/index.html[Problem Diagnosis Guide] +
+(printable link:pdguide/printable.html[html]) |This has a guide to the
+various features available such as messages and trace to help you both
+solve problems with you own programs and report bugs to the AspectJ
+team.
+
+|link:runtime-api/index.html[AspectJ API] |API documentation for AspectJ
+runtime classes. JoinPoint shows the state automatically available at
+each join point. See also the link:weaver-api/index.html[Weaver API]
+
+|link:faq.html[FAQ] |Frequently-asked questions about the AspectJ
+language, tools, and project.
+
+|README's |Changes and porting guide for AspectJ
+link:README-197.html[1.9.7], link:README-196.html[1.9.6],
+link:README-195.html[1.9.5], link:README-194.html[1.9.4],
+link:README-193.html[1.9.3], link:README-192.html[1.9.2],
+link:README-191.html[1.9.1], link:README-190.html[1.9.0],
+link:README-1811.html[1.8.11], link:README-1810.html[1.8.10],
+link:README-189.html[1.8.9], link:README-188.html[1.8.8],
+link:README-187.html[1.8.7], link:README-186.html[1.8.6],
+link:README-185.html[1.8.5], link:README-184.html[1.8.4],
+link:README-183.html[1.8.3], link:README-182.html[1.8.2],
+link:README-181.html[1.8.1], link:README-180.html[1.8.0],
+link:README-174.html[1.7.4], link:README-173.html[1.7.3],
+link:README-172.html[1.7.2], link:README-171.html[1.7.1],
+link:README-170.html[1.7.0], link:README-1612.html[1.6.12],
+link:README-1611.html[1.6.11], link:README-1610.html[1.6.10],
+link:README-169.html[1.6.9], link:README-168.html[1.6.8],
+link:README-167.html[1.6.7], link:README-166.html[1.6.6],
+link:README-165.html[1.6.5], link:README-164.html[1.6.4],
+link:README-163.html[1.6.3], link:README-162.html[1.6.2],
+link:README-161.html[1.6.1], link:README-160.html[1.6.0],
+link:README-154.html[1.5.4], link:README-153.html[1.5.3],
+link:README-152.html[1.5.2], link:README-151.html[1.5.1],
+link:README-150.html[1.5.0], link:README-121.html[1.2.1],
+link:README-12.html[1.2.0], link:README-11.html[1.1], and
+xref:porting.adoc[1.0].
+
+|link:changes.html[Changes] |Changes between the latest releases.
+
+|link:examples/[Examples] |AspectJ code to demonstrate some language
+features and implement JavaBean properties, the Observer pattern, a
+tracing library, and a game application where aspects handle display
+updating.
+|===
+
+[#distributions]##
+
+=== AspectJ distributions
+
+[cols=",",options="header",]
+|===
+|Distributions |Description
+|http://eclipse.org/aspectj[AspectJ] |The AspectJ distribution contains
+binaries for the compiler, structure browser, and Ant taskdefs, as well
+as the documentation and examples.
+
+|http://eclipse.org/aspectj[AspectJ] source code |Source code for
+AspectJ is available under the open-source
+https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.txt[Eclipse Public
+License v 2.0] license from the Git repositories for the AspectJ
+project. See the faq.html#q:buildingsource[FAQ entry].
+
+|http://eclipse.org/ajdt[AspectJ for Eclipse] |AspectJ Development
+Environment support for Eclipse is available under Eclipse Public
+License v 1.0 from the eclipse.org project site http://eclipse.org/ajdt
+
+|https://jdeveloperaop.dev.java.net/[Support for the JDeveloper IDE]
+|Support for programming in AspectJ using the JDeveloper IDE is
+available under the Apache Software License from the java.net project
+site https://jdeveloperaop.dev.java.net/
+|===
+
+[#resources]##
+
+=== Other AspectJ resources
+
+[cols=",",options="header",]
+|===
+|Resources |Description
+|Mail lists |AspectJ users discuss tips and best practices for writing
+AspectJ programs on aspectj-users@eclipse.org. AspectJ developers
+discuss issues with developing the AspectJ tools on
+aspectj-dev@eclipse.org. To get occasional emails about AspectJ releases
+and relevant events, subscribe to aspectj-announce@eclipse.org. To view
+list archives or subscribe to the list, go to
+http://eclipse.org/aspectj[the AspectJ home page]. To find archived
+emails, use the Eclipse site
+http://www.eclipse.org/search/search.cgi[search page].
+
+|http://bugs.eclipse.org/bugs[Bug database] |Use the Eclipse project's
+Bugzilla database to view and submit bugs against the AspectJ product
+components
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler[Compiler]
+(for the AspectJ compiler, ajc)
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=IDE[IDE]
+(for AJBrowser and AJDE bugs),
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Ant[Ant]
+(for the Ant tasks), and
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Docs[Docs]
+(for the documentation). Bugs all users should know about are
+http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info[flagged
+with the "info" keyword]. See the faq.html#q:ajcbugs[FAQ entry] for
+instructions on submitting compiler bugs.
+
+|http://aosd.net - the AOSD web site |This site has discussion and
+announcements related to aspect-oriented software development (AOSD) in
+general. Use announce@aosd.net to get and publish notices about AOSD
+workshops, conferences, and technology releases. Use discuss@aosd.net
+for general AOSD discussions.
+|===
+
+[#paths]##
+
+=== Suggested paths for those new to AspectJ
+
+To learn the AspectJ language, read the
+link:progguide/index.html[Programming Guide], keeping the
+link:progguide/semantics.html[Semantics appendix] nearby as the best
+reference for AspectJ usage. Focus initially on the join point model and
+pointcuts, concepts AOP adds to OOP. To read about how the
+link:examples/[examples] work, see the
+link:progguide/examples.html[Examples] section in the
+link:progguide/index.html[Programming Guide]. View and navigate the
+crosscutting structure using http://eclipse.org/ajdt[AJDT]; if you can't
+use Eclipse, try the `ajbrowser` structure viewer, as described in the
+link:devguide/ajbrowser.html[AspectJ Browser] section of the
+link:devguide/index.html[Development Environment Guide].
+
+To start using AspectJ with your own code, modify the example aspects to
+apply to your classes. As you learn, use the compiler's `-Xlint` flags
+to catch some common mistakes. (Understand that the
+link:progguide/implementation.html[current implementation] is limited to
+code the compiler controls.)
+
+To plan how to adopt AspectJ into a project, read the
+link:progguide/index.html[Programming Guide] on development- and
+production-time aspects and the link:faq.html[FAQ] entries for
+faq.html#q:startUsingAJ[How should I start using AspectJ?],
+link:faq.html#adoption[Deciding to adopt AspectJ], the Development tools
+sections (faq.html#q:integrateWithDevTools[one],
+link:faq.html#devtools[two], link:faq.html#ltw[Load-time weaving] ), and
+faq.html#q:opensource[AspectJ as open-source].
+
+Enjoy the language!
+
+The AspectJ Team
+
+'''''
+
+[.small]#xref:#top[Top]#
diff --git a/docs/dist/doc/porting.adoc b/docs/dist/doc/porting.adoc
new file mode 100644
index 000000000..809f85b4f
--- /dev/null
+++ b/docs/dist/doc/porting.adoc
@@ -0,0 +1,1868 @@
+[.small]#© Copyright 1998-2002 Palo Alto Research Center Incorporated,
+2003-2004 Contributors. All rights reserved.#
+
+== AspectJ Porting Notes
+
+* xref:#pre-1.2[Pre-1.2 code]
+* xref:#pre-1.1[Pre-1.1 code]
+* xref:#pre-1.0.4[Pre-1.0.4 code]
+* xref:#pre-1.0rc1[Pre-1.0rc1 code]
+* xref:#pre-1.0beta1[Pre-1.0beta1 code]
+* xref:#pre-1.0alpha1[Pre-1.0alpha1 code]
+* xref:#pre08b3[Pre-0.8beta3 code]
+* xref:#pre08b1[Pre-0.8beta1 code]
+* xref:#pre07b11[Pre-0.7beta11 code]
+* xref:#pre07b10[Pre-0.7beta10 code]
+
+=== [#pre-1.2]#Porting pre-1.2 code to AspectJ 1.2#
+
+README-12.html contains a discussion of the changes between 1.1 and 1.2.
+The key points are:
+
+*The default AspectJ compiler compliance level is now 1.4* (whereas in
+previous releases the default compliance level was 1.3). This has a
+number of implications:
+
+* class files generated by the compiler are now JRE v1.2 and upwards
+compatible. (At compliance level 1.3, AspectJ generated class files that
+were compatible with JRE 1.1 also).
+* `call` pointcuts may match more join points than in the same program
+compiled at compliance level 1.3.
+
+The AspectJ compiler can be restored to 1.3 compliance settings by
+specifying the "-1.3" option on the command-line.
+
+The following example program illustrates the differences in join point
+matching with the `call` pointcut designator between 1.4 and 1.3
+compliance levels.
+
+....
+01 class A {
+02   public void doIt() {...};
+03 }
+04
+05 class B extends A {
+06   public void doThisToo() {...};
+07 }
+08
+09
+10 public class CallsAandB {
+11
+12  public static void main(String[] args) {
+13    B b = new B();
+14    A bInDisguise = new B();
+15
+16    b.doIt();               // AspectJ 1.2 matches here
+17    bInDisguise.doIt();     // this is never matched
+18  }
+19
+20 }
+21
+22 aspect CallPCDMatchingExample {
+23
+24   before() : call(* B.doIt(..)) {
+25     System.out.println("About to call B.doIt(...)");
+26   }
+27
+28 }
+....
+
+When this program is compiled with AspectJ 1.2 using the default
+compiler options, it will produce one line of output when it is
+executed:
+
+`About to call B.doIt(...)`
+
+The same program compiled under AspectJ 1.1 (or using AspectJ 1.2 with
+the -1.3 flag specified) does not produce any output when it is run.
+
+The reason for the additional call pcd match is that prior to compliance
+level 1.4, Java compilers produced bytecodes that call A.doIt() (the
+defining type of the method), rather than B.doIt() (the declared type in
+the program text). The generated call to A.doIt() is not matched by the
+call pcd used in the before advice. At compliance level 1.4, the
+bytecodes retain the declared type of the receiver in the program
+source, generating a call to B.doIt(), which _is_ matched by the call
+pcd.
+
+This is a good example of why the recommended style is to use
+`call(* doIt(..)) && target(B)`, which always matches based on the
+actual type of the receiver.
+
+*New warnings emitted by the compiler for unmatched call pcds.* Because
+users have found the static type matching used for a type pattern
+specified in a `call` pcd confusing (as evidenced by the example above),
+AspectJ 1.2 has a new Xlint warning which is enable by default. The
+compiler will now produce a warning whenever a call pointcut designator
+does not match at a join point, and a user may have expected it to.
+Compiling the above program using AspectJ 1.2 produces the following
+compiler output:
+
+....
+
+CallsAandB.java:24 warning does not match because declaring type is A, if match desired use target(B) [Xlint:unmatchedSuperTypeInCall]
+before() : call(* B.doIt(..)) {
+           ^^^^^^^^^^^^^^^
+
+    see also: CallsAandB.java:17
+
+
+1 warning
+
+....
+
+The warning is telling us that the call pointcut associated with the
+before advice on line 24 of the source file does not match at a join
+point where the user may have expected it to. The source location
+corresponding to the unmatched join point is indicated by the "see also"
+line - in this case line 17 of the source file. At line 17 we find a
+call to `bInDisguise.doIt()`. Since the static type of `bInDisguise` is
+`A`, this call will never be matched. The warning also tells us a
+possible solution if we intended the pointcut to match at this join
+point: use `call(* doIt(..) && target(B)`.
+
+If you find warnings of this kind coming out when you use the AspectJ
+1.2 compiler, the recommended fix is to switch to using the `target`
+designator in place of a type pattern in the `call` pointcut expression.
+Note that there is no loss of runtime efficiency here - runtime tests
+are only added in the cases where it cannot be determined at compile
+time whether the type of the receiver will match the type specified in
+the `target` expression. Note that `target` cannot be used in `declare`
+statements.
+
+*Use of non-statically determinable pointcut expressions in declare
+statements* has always been forbidden, but prior to 1.2 the AspectJ
+compiler did not raise an error if they were used. The AspectJ Language
+Semantics appendix states that `cflow, cflowbelow, this, target, args`
+and `if` pointcut designators cannot be used directly or indirectly
+(through a user-defined pointcut) inside of a `declare` statment. When
+moving code from 1.1 to 1.2, additional errors may be raised due to the
+stricter policing of this rule. The solution is to recode the declare
+statement avoiding pointcut expressions that may require a run-time
+test.
+
+*Interface constructors no longer supported*. Declaring a constructor on
+an interface is now (correctly) prohibited, and there will no longer be
+a constructor-execution join point for the interface. To initialize a
+field declared on an interface, use initialization, e.g.,
+
+....
+int I.i;
+after(I i) returning: initialization(I) && this(i) { i.i = 2; }
+....
+
+To pick out the constructor-execution for any implementation of I, try
+
+....
+execution(I+.new(..))
+....
+
+For more information, see bug
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=49295[49295].
+
+*Declaring a static method on an interface* is now (correctly)
+prohibited. One workaround is to define a static method on the aspect
+instead. For more information, see bug
+https://bugs.eclipse.org/bugs/show_bug.cgi?id=47754[47754].
+
+*Watch for problems due to incompatible BCEL versions.* AspectJ 1.2
+includes a different version of BCEL than AspectJ 1.1. If you have the
+older version of BCEL available earlier on your classpath than the
+version included in the 1.2 aspectjtools.jar then you will see errors
+like:
+
+....
+C:\work\test\TestAspect.aj error Internal compiler error
+java.lang.NoSuchMethodError: org.apache.bcel.generic.InstructionFactory.
+createNewArray(Lorg/apache/bcel/generic/Type;S)Lorg/apache/bcel/generic/Instruction;
+....
+
+This typically happens because the old version of BCEL has been included
+as a standard extension in your JVM configuration. Ensure you have
+removed it from jre/lib/ext under your JDK installation.
+
+For more information, see bugs including
+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#
+
+README-11.html contains a discussion of the language changes from 1.0 to
+1.1. The high points:
+
+The `call(..)` pointcut designator is now implemented only at the call
+site; by contrast, the AspectJ 1.0 compiler could also implement it on
+the callee side. So in 1.0 if you compiled a pointcut using `call(..)`
+but only passed the compiler the code for the target of the call, the
+pointcut could be implemented. This is not true for 1.1. To fix this,
+use `execution(..)` in place of `call(..)`, or include all calling
+clients in the compile. (link:README-11.html#NO_CALLEE_SIDE_CALL[more
+info])
+
+Type-patterns are no longer permitted for the defining type of
+inter-type declarations. Replace the pattern with a type. In many cases,
+you can declare members on an interface type, and then declare that the
+types picked out by the type-pattern implement have the interface as
+their parent. (link:README-11.html#SINGLE_INTERCLASS_TARGET[more info])
+
+Type-patterns are no longer permitted when specifying `declare soft`.
+Replace the pattern with a literal type.
+
+Wildcards patterns (`foo..*`) are no longer permitted for `this()`,
+`target()`, or `args()`. Replace the pattern with a literal type or with
+a subtype wildcard (`Type+`).
+(link:README-11.html#INSTANCEOF_ON_WILD[more info])
+
+Conflicts will be reported for no-argument constructors generated by
+compilers when no constructor is defined for a class. That means the
+following code will compile in 1.0 but not in 1.1:
+
+....
+class C {}
+aspect A {
+   C.new() {}  // permitted in 1.0; conflict in 1.1
+}
+....
+
+One fix is to declare a non-conflicting constructor by adding arguments
+(or defining a constructor in the target class); a better fix might be
+to do the work of the declared constructor in advice on the
+initialization join point for the object.
+(link:README-11.html#DEFAULT_CONSTRUCTOR_CONFLICT[more info])
+
+The pointcut designators `within()` and `withincode()` will not pick out
+code within the lexical extent of method-local and anonymous inner types
+(because these are not represented as such in bytecode form). Because
+`within` forms specify staticly-determinable pointcuts, they might be
+used in declare error or declare warning statements, which might produce
+different results. (link:README-11.html#WITHIN_MEMBER_TYPES[more info])
+
+The compiler will report an error that the form
+`aspect {name} dominates {list}...` is no longer supported. It has been
+replaced by a new declare statement:
+
+....
+declare precedence : {name} {list}...
+....
+
+(link:README-11.html#ASPECT_PRECEDENCE[more info])
+
+The field set join point now has a return type of `void`. Compiling
+programs using around advice on these join points might cause errors
+unless the return type of the around advice and the result of any
+proceed() call is `Object` or `void`.
+(link:README-11.html#VOID_FIELD_SET[more info])
+
+The compiler cannot implement after or around advice for the handler PCD
+because the end of exception handlers is ambiguous in bytecode. Try to
+use before advice. (link:README-11.html#AFTER_HANDLER[more info])
+
+=== [#pre-1.0.4]#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
+returning advice.
+
+The main change that was made was of after returning advice for
+constructor execution join points. Previously, this advice was legal:
+
+....
+after() returning (Foo f): execution(Foo.new(..)) { ... }
+....
+
+However, it has always been a part of the 1.0 language design (and of
+Java's language design) that constructors themselves (as opposed to
+constructor calls) do not return the value of the new object. Rather,
+`this` is bound to the new object, and the constructor behaves like a
+void method. With that in mind, any code like the above should be
+conveted to the form.
+
+....
+after(Foo f) returning: this(f) && execution(Foo.new(..)) { ... }
+....
+
+In compilers prior to 1.0.4, the following advice could pick out join
+points
+
+....
+after() returning (String s): call(void foo()) { ... }
+....
+
+This is no longer picked out. This pattern was most commonly used in
+highly polymorphic contexts, such as
+
+....
+after() returning (String s): call(* foo()) { ... }
+....
+
+If you want to capture all calls, binding null objects for those that
+would otherwise have no value, you must use the `Object` type.
+
+....
+after() returning (Object o): call(* foo()) { ... }
+....
+
+Uses of both of these forms are highleted with compiler warnings in the
+1.0.4 compiler.
+
+'''''
+
+=== [#pre-1.0rc1]#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
+aspects, you should refactor your code to keep the state you need to
+serialize or clone in objects associated with the aspects.
+
+'''''
+
+=== [#pre-1.0beta1]#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
+you find them.
+
+Also, though the `returns` modifier on pointcuts has not been part of
+the language since 1.0alpha1, the compiler still accepted them until
+now. If you used this feature, now is the right time to remove the
+`returns` modifier when the compiler complains about it.
+
+'''''
+
+=== [#pre-1.0alpha1]#Porting pre-1.0alpha1 code#
+
+The release of AspectJ 1.0alpha1 involved sweeping cleanups of the
+language to bring it to 1.0 status.
+
+* xref:#1.0a1-pointcuts[Pointcuts]
+* xref:#1.0a1-type-patterns[Type patterns]
+* xref:#1.0a1-advice[Advice]
+* xref:#1.0a1-introduction-and-static[Introduction and static
+crosscutting]
+* xref:#1.0a1-aspects[Aspects]
+
+==== [#1.0a1-pointcuts]#Pointcuts#
+
+===== [#1.0a1-plural-to-singular]#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
+singular, that is, they lose an "s". In one sense, making this change in
+your programs is easy: just go through and whever you see uses of the
+pointcuts
+
+____
+calls executions gets sets handlers initializations
+staticinitializations
+____
+
+Just take off the final "s", to make one of
+
+____
+call execution get set handler initialization staticinitialization
+____
+
+Often, there will be other changes you should make for each of these
+pointcuts, but as for the name, just take off the "s".
+
+One risk you will have when doing this is creating name conflicts. If,
+for example, you named a parameter of a pointcut "set", you should (for
+your own sanity -- the compiler doesn't require it) rename it in the
+rewritten pointcut.
+
+....
+pointcut sort(Collection set): calls(void addAll(set));
+==>
+pointcut sort(Collection mySet): call(void addAll(mySet));
+....
+
+While converting to use singular nouns for the primitive pointcuts, you
+may also want to remove the "s" from your user-defined pointcuts.
+
+....
+pointcut publicCalls(): calls(public * *(..));
+==>
+pointcut publicCall(): call(public * *(..));
+....
+
+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#
+
+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
+in AspectJ 1.0, so now a call join point doesn't represent the
+"caller-side" of a call, but the call itself, both caller and receiver.
+
+Changing code that used the `receptions` pointcut should be fairly
+straightforward, depending on whether the pointcut exposed state or not.
+
+====== Not exposing state
+
+Receptions pointcuts that did not expose state can simply be replaced by
+the new `call` and `target` pointcuts:
+
+....
+receptions(void Foo.m())
+==>
+target(Foo) && call(void m())
+....
+
+====== Exposing state
+
+Some receptions pointcuts exposed the receiving object by replacing the
+receiving type with a pointcut formal. These PCDs should be rewritten to
+use the new `target` pointcut to expose the receiving object.
+
+....
+pointcut fooCallees(Foo f): receptions(void f.m());
+==>
+pointcut fooCallee(Foo f): target(f) && call(void m());
+....
+
+Like xref:#1.0a1-fixing-state-access[other pointcuts], receptions
+pointcuts that exposed one or more arguments should be rewritten to use
+the `args` pointcut:
+
+....
+pointcut intPassers(int i, int j): receptions(void Foo.m(i, j));
+==>
+pointcut intPasser(int i, int j):
+    args(i, j) && target(Foo) && call(void m(int, int));
+....
+
+====== Constructor receptions
+
+There are two issues with constructor receptions in particular.
+
+Like xref:#1.0a1-constructor-calls[constructor calls], constructor
+receptions pointcuts had a dynamic character, in that
+`receptions(C.new())` would capture constructions of not only C classes,
+but also of classes that extended C.
+
+If you want this behaviour, then you need to use the new subtypes
+operator, +, on the type name in question. So,
+
+....
+receptions(C.new())
+==>
+call(C+.new())
+....
+
+Also like xref:#1.0a1-constructor-calls[constructor calls], constructor
+receptions allowed access to the constructed object in the same way as
+any other object. Since the only advice possible on constructor
+receptions join points was `after returning` advice, the object was
+always guaranteed to be there. But since constructor call join points
+allow all kinds of advice it may be that the object isn't constructed
+yet (say, in before or around advice). This is a benefit, in that it
+allows caching constructed objects
+
+....
+aspect Singleton {
+    private C theC = null;
+
+    C around(): call(C.new(..)) {
+        if (c == null) theC = proceed();
+        return theC;
+    }
+}
+....
+
+but it does require some rewriting. The new object can be accessed as
+the return value in after returning advice. So,
+
+....
+after(Point p) returning (): receptions(p.new(int, int)) { ... }
+==>
+after() returning (Point p): call(Point+.new(int, int)) { ... }
+....
+
+===== [#1.0a1-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
+the signatures of many pointcuts, leading to difficult-to-read forms. In
+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
+
+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
+its type and add an `args` pointcut.
+
+....
+pointcut intPassers(int i, int j): calls(void Foo.m(i, j));
+==>
+pointcut intPasser(int i, int j): args(i, j) && call(void Foo.m(int, int));
+....
+
+....
+pointcut stringPassers(String s): receptions(void Foo.m(s, ..));
+==>
+pointcut stringPasser(String s): args(s, ..) && call(void Foo.m(String, ..));
+....
+
+====== Rewriting calls
+
+If a calls pointcut exposed the the receiving object, such as
+
+....
+pointcut fooCallees(Foo f): calls(void f.m());
+....
+
+then the new version should use the `target` pointcut to get at that
+object
+
+....
+pointcut fooCallee(Foo f): target(f) && call(void Foo.m());
+....
+
+AspectJ's calls pointcut previously allowed the new object to be
+exposed, even though it may not have been constructed yet. AspectJ 1.0
+no longer allows this; you can access the new instance only in after
+returning advice, when it is guaranteed that the object was successfully
+constructed. So instead of using the `target` pointcut to expose the
+value, you should use the normal `after returning` mechanism:
+
+....
+after(Point p) returning (): calls(p.new(int, int)) { ... }
+==>
+after() returning (Point p): call(Point+.new(int, int)) { ... }
+....
+
+====== 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`
+pointcut.
+
+....
+before(Frame f): gets(Color f.color) { ... }
+==>
+before(Frame f): target(f) && get(Color Frame.color) { ... }
+....
+
+....
+before(Frame f): sets(Color f.color) { ... }
+==>
+before(Frame f): target(f) && set(Color Frame.color) { ... }
+....
+
+In addition, the clumsy syntax for getting the old value of the field
+has been eliminated. For before advice, the port is simple; just access
+the field yourself in the body. Depending on the rest of your system,
+you may need to restrict the advice from the aspect body to eliminiate
+the circularity.
+
+....
+aspect A {
+    before(Frame f, Color c): gets(Color f.color)[c] { ... }
+}
+==>
+aspect A {
+    before(Frame f):
+            target(f) && get(Color Frame.color) && !within(A) {
+        Color c = f.color;
+        ...
+    }
+}
+....
+
+The same can be done for `around` advice. However, the only way to port
+after advice that needs the old value is to convert it to around advice.
+
+....
+aspect A {
+    after(Frame f, Color c) returning (): gets(Color f.color)[c] { ... }
+}
+==>
+aspect A {
+    void around(Frame f):
+            target(f) && get(Color Frame.color) && !within(A) {
+        Color c = f.color;
+        proceed(f);
+        ...
+    }
+}
+....
+
+When porting `sets` pointcuts, the new value of a field is still
+available, but not the way it was previously. Instead of using the
+square bracket syntax, we use an `args` pointcut. All set join points
+are assumed to have exactly one argument, which holds the new value. So,
+
+....
+after(Color newColor): sets(Color Frame.color)[][newColor] { ... }
+==>
+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
+
+The value of the exception at an exception handler join point is now
+accessed through the `args` pointcut; all exception handler join points
+are treated as having exactly one argument, the exception value. So,
+
+....
+before(NotFoundException e): handlers(e) { ... }
+==>
+before(NotFoundException e): args(e) && handler(NotFoundException) { ... }
+....
+
+====== 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,
+it often didn't do what users expected it to. This loophole has now been
+closed, and within can only take type patterns, not pointcut or advice
+formals. A use of the `this` pointcut will capture what previous
+implementations did:
+
+....
+pointcut usesFoo(Foo f): within(f);
+==>
+pointcut usesFoo(Foo f): this(f) && within(Foo);
+....
+
+===== [#1.0a1-no-subs-in-sigs]#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
+no more parameters.
+
+Also, now that we have the `+` wildcard to pick out
+xref:#1.0a1-subtypes-to-plus[subtypes], we can make signature matching
+much more uniform.
+
+Previously, some signatures matched based on subtypes, some based on
+instanceof, and some exactly. Now, we have made all signatures match
+exactly.
+
+What does this mean for your program? Well, it means that you may have
+to add `+` to some of your signatures, depending on what you meant them
+to match.
+
+For example, the pointcut
+
+....
+calls(void m(Object))
+....
+
+previously picked out all method calls to a method named m that took one
+argument, which was a subtype of Object. Now, however, it will only pick
+out method calls to methods that are defined to take exactly the type
+Object, which may be a lot fewer join points. If you want the old
+behaviour, simply convert to
+
+....
+call(void m(Object+))
+....
+
+===== [#1.0a1-fixing-instanceof]#Removing the instanceof pointcut#
+
+The intanceof pointcut has been split into two different pointcuts,
+`this` and `target`.
+
+Typically, the instanceof pointcut would only exist in a compound
+pointcut, composed (with `&&`) with another pointcut. If the other
+pointcut was a `receptions` pointcut, then `instanceof` should be
+converted to `target` (and `receptions` converted to `call`). So,
+
+....
+pointcut stateChanges(Subject s):
+    instanceof(s) && receptions(void Button.click());
+==>
+pointcut stateChange(Subject s):
+    target(s) && call(void Button.click());
+....
+
+In all other cases, `instanceof` referred to the currently executing
+object, and so should be converted into `this`
+
+....
+before(Point p): instanceof(p) && executions(* makePolar(..)) { ... }
+==>
+before(Point p): this(p) && execution(* makePolar(..)) { ... }
+....
+
+....
+pointcut setup(Client c): instanceof(c) && calls(Remote Naming.lookup(String));
+==>
+pointcut setup(Client c): this(c) && calls(Remote Naming.lookup(String));
+....
+
+===== [#1.0a1-initializations]#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
+initialization that a class can do, after the return of its super
+constructor call (before which no initialization can happen). Previous
+versions of AspectJ had object initialization join points that only
+included initialization that was made in dynamic initializers and
+fields.
+
+The old behaviour can be recovered with a simple rewrite.
+
+....
+initializations(A)
+==>
+initialization(A.new(..)) && !execution(A.new(..))
+....
+
+===== [#1.0a1-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,
+and new `SubFoo` objects. The new `call` pointcut designator matches
+types exactly, so if you want the old behaviour, you should write
+`call(Foo+.new())`.
+
+Similarly, constructor execution join points were matched by subtypes.
+So the old `executions(Foo.new())` is now represented by
+`execution(Foo+.new())`.
+
+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#
+
+The `hasaspect` pointcut is no longer defined, but you can get the same
+behaviour using the new `if` pointcut.
+
+If the aspect whose presense you are checking for was defined
+`of eachcflow`, `of eachcflowbelow`, or, more unlikely, `of eachJVM()`,
+then the conversion is simple:
+
+....
+hasaspect(A)
+==>
+if(A.hasAspect())
+....
+
+If the aspect was defined `of eachobject`, then you will have to expose
+the current object in your pointcut or advice parameters:
+
+....
+pointcut cut(): hasaspect(A) ... ;
+==>
+pointcut cut(Object o): this(o) && if(A.hasAspect(o)) ... ;
+or
+pointcut cut(Object o): target(o) && if(A.hasAspect(o)) ... ;
+....
+
+If you were using the `hasaspect` pointcut to expose the state of the
+aspect, then you can get the same state by using `A.aspectOf()` in the
+body of the advice. For example, if the aspect A were defined
+`of eachcflow`, then
+
+....
+before(A myA): hasaspect(myA) {
+    myA.checkStatus();
+}
+==>
+before(): if(A.hasAspect()) {
+    A myA = A.aspectOf();
+    myA.checkStatus();
+}
+....
+
+===== [#1.0a1-withinall]#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],
++, instead. You'll save two characters and be using a simpler and more
+orthogonal language.
+
+....
+withinall(Foo)
+==>
+within(Foo+)
+....
+
+===== [#1.0a1-user-defined-returns]#Removing returns modifier from pointcuts#
+
+The returns keyword is no longer necessary for user-defined pointcuts.
+Simply remove it when you find it.
+
+....
+pointcut publicIntCalls() returns int: calls(public int *(..));
+==>
+pointcut publicIntCall(): call(public int *(..));
+....
+
+===== [#1.0a1-static-pointcuts]#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.
+
+Pointcuts now have that property too. Pointcuts may be declared to be
+static, in which case they can be accessed like `MyAspect.move()`, or
+they can be left non-static, in which case they can be overridden by a
+subaspect.
+
+In addition, while pointcuts can still be defined in classes, only
+`static` pointcuts can be defined in classes.
+
+Porting should be straightforward; just make all your pointcuts in
+classes `static`, and make any pointcut with a qualified reference
+static.
+
+==== [#1.0a1-type-patterns]#Type patterns#
+
+===== [#1.0a1-new-wildcards]#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
+type, and basing their meanings on the definition of a package
+hierarchy.
+
+In AspectJ 1.0, both of these wildcards are defined simply, and
+textually:
+
+* The * wildcard alone matches all types.
+* The * wildcard in a pattern matches zero or more characters, but will
+not match "."
+* The .. wildcard matches any sequence of characters that begins and
+ends with "."
+
+That's it.
+
+This change won't affect most programs, but it will make understanding
+programs easier. There is one ugly idiom, however, that this change
+disposes of. If your program includes the type pattern `*..*`, which
+used to match all types, you can replace it with the much simpler *.
+
+....
+pointcut unaryVoidMethods(): call(void *(*..*));
+==>
+pointcut unaryVoidMethod(): call(void *(*));
+....
+
+===== [#1.0a1-subtypes-to-plus]#Fixing subtypes in introduction#
+
+The new + operator is used to normalize the many places you want to use
+subtypes of some types.
+
+In introduction forms, you will need to replace `subtypes(TypePattern)`
+type patterns with the new subtype operator, +. In the case where you
+wrote `subtypes(Foo)`, i.e., the subtypes of a single type, simply
+replace this with `Foo+`. Otherwise, use the + operator as appropriate
+in `TypePattern`.
+
+....
+public void (subtypes(Target0 || Target1)).accept(Visitor v) {
+    v.visit(this);
+}
+==>
+public void (Target0+ || Target1+).accept(Visitor v) {
+    v.visit(this);
+}
+....
+
+==== [#1.0a1-advice]#Advice#
+
+===== [#1.0a1-around-returns]#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,
+
+....
+around(Point p) returns void: setters(p) { ... }
+==>
+void around(Point p): setter(p) { ... }
+....
+
+===== [#1.0a1-around-throws]#Adding a throws clause to around#
+
+Around advice must now declare the checked exceptions it throws with a
+`throws` clause, much like a method.
+
+....
+char around(char c) throws java.io.CharConversionException: converter(c) {
+    char result;
+    try { result = proceed(); }
+    catch (Exception e) {
+        throw new java.io.CharConversionException();
+    }
+    if (result == 0) throw new java.io.CharConversionException();
+    return result;
+}
+....
+
+===== [#1.0a1-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
+precedent. This made perfect sense for `before` and `around` advice, but
+was the cause of confusion (even among the AspectJ designers, more than
+once) for `after` advice, as it seemed backward.
+
+In addition, advice was ordered by kind, in that around advice always
+surrounded before and after advice.
+
+AspectJ 1.0 has changed this; precedence for `after` advice is inverted,
+and advice is no longer ordered by kind.
+
+This won't matter to you unless you write pieces of advice in the same
+aspect that apply to the same join point.
+
+If you do, here's what to think about: If you're looking at two pieces
+of advice and want to know which has precedence, if either is `after`
+advice, then the second one has precedence. Otherwise, the first does.
+
+This allows interesting advice interaction. In the following advice, for
+example, the `after throwing` advice will catch the exception thrown by
+the `before` advice
+
+....
+aspect A {
+    before(): call(void main(..)) {
+        throw new RuntimeException();
+    }
+    after() throwing(RuntimeException e): call(void main(..)) {
+         System.err.println("caught you!");
+    }
+}
+....
+
+But reversing the order will give the `before` advice more precedence,
+making its exception uncatchable by the `after throwing` advice
+
+....
+aspect A {
+    after() throwing(RuntimeException e): call(void main(..)) {
+         System.err.println("missed you!");
+    }
+    before(): call(void main(..)) {
+        throw new RuntimeException();
+    }
+}
+....
+
+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#
+
+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
+indicate that fact. So,
+
+....
+after(Formals) returning (): Pointcut { ... }
+==>
+after(Formals) returning: Pointcut { ... }
+....
+
+The same syntax is now available for after throwing advice, in case you
+do not care what `Throwable` is thrown.
+
+....
+after(Formals) throwing: Pointcut { ... }
+....
+
+===== [#1.0a1-this-static-join-point]#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#
+
+The `JoinPoint` object hierarchy has been folded into a single class,
+`org.aspectj.lang.JoinPoint`. A common pattern in logging, for example,
+was
+
+....
+before() executions(* myMethod()) {
+    ExecutionJoinPoint jp = (ExecutionJoinPoint)thisJoinPoint;
+    CodeSignature jp = (CodeSignature)jp.getSignature();
+    System.err.println(jp.getParameters());
+    System.err.println(jp.getParameterNames());
+}
+....
+
+While there is still a rich hierarchy for signatures, there is only one
+`JoinPoint` type, so this can be rewritten as:
+
+....
+before() executions(* myMethod()) {
+    JoinPoint jp = thisJoinPoint;
+    CodeSignature jp = (CodeSignature)jp.getSignature();
+    System.err.println(jp.getArgs());
+    System.err.println(jp.getParameterNames());
+}
+....
+
+Some of the method names of `JoinPoint` have been reorganized, as well.
+
+==== [#1.0a1-introduction-and-static]#Introduction and static crosscutting#
+
+===== [#1.0a1-plus-implements-extends]#Removing +implements and +extends#
+
+The keywords `+implements` and `+extends` no longer exist. Instead,
+AspectJ uses the `declare` form for exactly the same functionality.
+
+....
+Point +implements Serializable;
+=>
+declare parents: Point implements Serializable;
+....
+
+....
+MyButton +extends ButtonAdaptor;
+=>
+declare parents: MyButton extends ButtonAdaptor;
+....
+
+===== [#1.0a1-now-use-soft]#Using declare soft#
+
+Around advice advice no longer effects the static exception checking of
+Java. This means that the following code previously compiled:
+
+....
+class C {
+    void noExceptionDeclared() {
+        exceptionDeclared();
+    }
+    void exceptionDeclared() throws IOException {}
+}
+aspect A {
+    around(): call(void C.exceptionDeclared()) {
+        try { proceed(); }
+        catch (IOException e) {}
+    }
+}
+....
+
+even though the class C is not compilable on its own (because
+noExceptionDeclared actually throws an Exception).
+
+AspectJ now firmly places everything that affects the type system of
+Java, including the declared-exception checking system, into the space
+of introduction and declare. So, in order to state that the call to
+exceptionDeclared() will not, actually, throw an exception, we now
+"soften" that exception, that is, take it out of the space of declared
+exceptions.
+
+....
+declare soft: ExceptionType: Pointcut;
+....
+
+The pointcuts allowed here are limited; you cannot use pointcuts that
+would require runtime information. But picking out method calls is just
+fine. So in order to make the above example work, one new declaration is
+needed:
+
+....
+declare soft: IOException:
+    call(void C.exceptionDeclared()) &&
+    withincode(void noExceptionDeclared());
+....
+
+==== [#1.0a1-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,
+
+....
+aspect A of eachcflow(...) { ... }
+==>
+aspect A percflow(...) { ... }
+....
+
+If you have any aspects defined `of eachJVM()`, then you should either
+remove that declaration entirely (because this is the default
+behaviour), or replace the `of eachJVM()` declaration with an
+`issingleton` declaration.
+
+....
+aspect of eachJVM() { ... }
+==>
+aspect A { ... }
+or
+aspect A issingleton { ... }
+....
+
+The `of eachobject(Pointcut)` modifier has been split into two different
+forms, `of perthis(Pointcut)` and `of pertarget(Pointcut)`. Which one
+you replace with depends on the `Pointcut` you use.
+
+If you use a pointcut that picked out reception join points, then use
+`pertarget`, and rewrite the pointcut to pick out call join points. So
+
+....
+aspect Shadow
+        of eachobject(receptions(void Point.setX(int)) ||
+                      receptions(void Point.setY(int))) {
+    ...
+}
+==>
+aspect Shadow pertarget(call(void Point.setX(int)) ||
+                        call(void Point.setY(int))) {
+    ...
+}
+....
+
+Otherwise, in most cases, use `perthis`. When you convert, remember the
+meaning of each of these modifiers. `perthis(Pointcut)` indicates that
+an instance of the aspect should be associated with every object that is
+`this` at each of the join points picked out by `Pointcut`, while
+`pertarget(Pointcut)` associates with every object that is the target
+object at such join points.
+
+'''''
+
+=== [#pre08b3]#Porting pre-0.8beta3 code#
+
+* xref:#cflowTerminology[Changing cflow terminology]
+* xref:#abstractPointcuts[Overriding abstract pointcuts]
+* xref:#recursiveAdvice[Limiting recursive advice]
+
+The following changes are only required when porting code written prior
+to the 0.8beta3 release of AspectJ.
+
+==== [#cflowTerminology]#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
+
+The aspect modifier "`of eachcflowroot(Pointcut)`" should now be written
+more as "`percflow(Pointcut)`".
+
+===== cflow
+
+In previous versions of AspectJ, the pointcut `cflow(Pointcut)` picked
+out all join points in the cflow below the join points of `Pointcut`.
+That is, it did not include the join points of `Pointcut`, only the join
+points in their control flow.
+
+As of version 0.8beta3, `cflowbelow(Pointcut)` has that behavior.
+`cflow(Pointcut)` includes the join points of `Pointcut`.
+
+In many cases, you may not care whether the points of `Pointcut` are
+included or not, and so can safely leave `cflow(Pointcut)` pointcut
+designators alone. However, if you use the idiom
+
+[source,codeindent]
+----
+Pointcut && ! cflow(Pointcut)
+----
+
+to capture the non-recursive entries to a particular pointcut, you will
+definitely want to rewrite that as
+
+[source,codeindent]
+----
+Pointcut && ! cflowbelow(Pointcut)
+----
+
+===== cflowtop
+
+The primitive pointcut designator `cflowtop(Pointcut)` has been removed
+from the language, as it is expressible with `cflow` or `cflowbelow`.
+All uses of `cflowtop(Pointcut)` can be rewritten as:
+
+[source,codeindent]
+----
+cflowbelow(Pointcut && ! cflowbelow(Pointcut))
+----
+
+Though in most cases the following is sufficient
+
+[source,codeindent]
+----
+cflow(Pointcut && ! cflowbelow(Pointcut))
+----
+
+==== [#abstractPointcuts]#Overriding abstract pointcuts#
+
+In previous versions of AspectJ, a concrete aspect would implicitly
+override all of its abstract pointcuts with an empty pointcut. AspectJ
+0.8beta3 enforces the restriction that a concrete aspect may not have
+any abstract pointcuts. Thus the following extension:
+
+[source,codeindent]
+----
+abstract aspect A {
+    abstract pointcut pc();
+}
+
+aspect B {}
+----
+
+will no longer compile.
+
+Adding the new empty pointcut designator
+
+[source,codeindent]
+----
+pointcut Id();
+----
+
+in the declaration of the concrete aspect fixes this problem.
+
+[source,codeindent]
+----
+abstract aspect A {
+    abstract pointcut pc();
+}
+
+aspect B {
+    pointcut pc();
+}
+----
+
+==== [#recursiveAdvice]#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
+
+[source,codeindent]
+----
+class C {
+    static int i;
+}
+
+aspect A {
+    before(): gets(int C.i) {
+        System.err.println("C.i was " + C.i)
+    }
+}
+----
+
+The advice would trace all references of the static field `C.i` except
+those in the body of the before.
+
+The compiler has now removed this special case, and so running the above
+example will now cause a `StackOverflowException` to be thrown.
+
+Most cases of this error can be fixed by correctly specifying the
+desired pointcut: In the above example, the intention is clearly not to
+trace _all_ references of `C.i`, just those outside the aspect.
+
+[source,codeindent]
+----
+class C {
+    static int i;
+}
+
+aspect A {
+    before(): get(int C.i) && ! within(A) {
+        System.err.println("C.i was " + C.i)
+    }
+}
+----
+
+In a very few cases, you may want the advice to be applicable to other
+code in the aspect, but not in the particular piece of advice. In such
+cases, you can pull the body of the advice into a method and restrict
+away from that method (and away from calls to that method):
+
+[source,codeindent]
+----
+class C {
+    static int i;
+}
+
+aspect A {
+    public static int getCi() {
+        return C.i;                          // will be traced
+    }
+
+    before(): get(int C.i) &&
+              ! withincode(void A.traceCi())
+              ! call(void A.traceCi())      {
+        traceCi();
+    }
+    private void traceCi() {
+        System.err.println("C.i was " + C.i) // will not be traced
+    }
+}
+----
+
+'''''
+
+=== [#pre08b1]#Porting pre-0.8beta1 code#
+
+* xref:#introSyntax[Rewriting introductions]
+* xref:#staticAdvice[Removing static advice]
+* xref:#aspect-aspect[Fixing aspect-aspect inheritance]
+* xref:#usingPrivateIntroduction[Using private introduction]
+
+The following changes are only required when porting code written prior
+to the 0.8beta1 release of AspectJ.
+
+==== [#introSyntax]#Rewriting introductions#
+
+===== Syntax
+
+The syntax of introduction has changed. Porting most programs should
+require some simple editing. Anywhere you have an introduction block
+
+[source,codeindent]
+----
+introduction GTN {
+    ...
+}
+----
+
+simply move the `GTN` down into the introduction declarations and remove
+the block.
+
+For method introduction, place the `GTN` in front of the method name,
+For field introduction, place the `GTN` in front of the field name, and
+for constructor introduction, place the `GTN` in front of the `new`
+identifier.
+
+[source,codeindent]
+----
+introduction Foo {
+    public void doStuff() { this.doStuffLater(); }
+    public int calorieCount = 3;
+    public new(int x) { super(); calorieCount = x; }
+}
+
+==>
+
+public void Foo.doStuff() { this.doStuffLater(); }
+public int Foo.calorieCount= 3;
+public Foo.new(int x) { super(); calorieCount = x; }
+----
+
+For implements and extends introduction, move the `GTN` in front of the
+new identifiers `implements` or `extends`, and place that in a
+`declare parents` form.
+
+[source,codeindent]
+----
+introduction Foo {
+    implements Comparable;
+    extends Goo;
+}
+
+==>
+
+declare parents: Foo implements Comparable;
+declare parents: Foo extends Goo;
+----
+
+In all cases, if the `GTN` is just a type name, it can be moved down on
+its own. However, if the `GTN` uses any of `&&`, `||`, and `!`, it must
+be parenthesized.
+
+[source,codeindent]
+----
+introduction subtypes(Foo) && !Goo {
+    int x;
+}
+
+==>
+
+int (Foo+ && !Goo).x;
+----
+
+===== 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
+need to modify your code to avoid this accessibility issue, or you will
+need to use the `privileged` modifier on the aspect that contains the
+introduction.
+
+[source,codeindent]
+----
+class Counter {
+    private int count = 2;
+}
+
+aspect ExposeCountersPrivates {
+    introduction Counter {
+        public int getCount() { return count; }
+    }
+}
+
+==>
+// in 0.8, only privileged aspects can expose a class's privates
+privileged aspect ExposeCountersPrivates {
+    public int Counter.getCount() { return count; }
+}
+----
+
+If you have introduced private or package-protected members, you will
+probably have to re-write some code. Most previous uses of introducing
+privates can be improved by using private introduction instead.
+
+[source,codeindent]
+----
+class C {
+}
+
+aspect AddCounter {
+    introduction C {
+        private int count;
+        public int getCount() { return count; }
+    }
+}
+
+==>
+aspect AddCounter {
+    private int Counter.count;
+    public int Counter.getCount() { return count; }
+}
+----
+
+There is one case that we know of where the inability to perform the
+introduction of private members makes 0.7 code difficult to port to 0.8.
+If you were using the introduction of a `private void writeObject(..)`
+or a `private void readObject(..)` method to interact with Java's
+serialization API, you will need to come up with an alternative design.
+Using some combination of `Externalizable`, `writeReplace(..)` and/or
+`readResolve(..)` methods should allow you to port your code. If you
+find this isn't the case, we'd like to hear about it.
+
+If you were introducing either a protected member or a package-private
+member onto a class in order to override a protected member that was
+inherited from a superclass, you will have to make this introduction
+public.
+
+==== [#staticAdvice]#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
+aspect instance.
+
+If you have an aspect that only contains static advice, has no "of"
+clause or is declared "of eachJVM()", and is not extended by another
+aspect, simply remove the keyword "static" from all pieces of advice,
+and make sure the aspect is not defined with the "abstract" modifier.
+
+[source,codeindent]
+----
+aspect Tracing {
+    static before(): executions(* *(..)) {
+        System.out.println("Got Here! " + thisJoinPoint);
+    }
+}
+
+==>
+
+aspect Tracing {
+    before(): execution(* *(..)) {
+        System.out.println("Got Here! " + thisJoinPoint);
+    }
+}
+----
+
+Otherwise, if you have an aspect contains both static and non-static
+advice, is extended, or is "of eachObject(...)" or "of
+eachcflowroot(...)", you should group your static advice together and
+put it in a new aspect, possibly even an inner aspect.
+
+[source,codeindent]
+----
+aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) {
+    static before(): executions(* *(..)) {
+        System.out.println("Got Here! " + thisJoinPoint);
+    }
+    static after(): executions(* *(..)) {
+        System.out.println("Returned! " + thisJoinPoint);
+    }
+
+    // some other dynamic advice, fields, etc
+}
+
+==>
+
+aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) {
+    static aspect AlwaysTracing {
+        before(): execution(* *(..)) {
+            System.out.println("Got Here! " + thisJoinPoint);
+        }
+        after(): execution(* *(..)) {
+            System.out.println("Returned! " + thisJoinPoint);
+        }
+    }
+
+    // some other dynamic advice, fields, etc
+}
+----
+
+==== [#aspect-aspect]#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
+majority of your code the most serious change this requires is to add an
+explicit `abstract` modifier to a super-aspect that was already
+implicitly abstract.
+
+[source,codeindent]
+----
+aspect BaseTracing {
+    abstract pointcut traced();
+    before(): traced() {
+        System.out.println("Got Here! " + thisJoinPoint);
+    }
+}
+
+==>
+
+// make this abstract aspect explicitly abstract
+abstract aspect BaseTracing {
+    ...
+}
+----
+
+This change has also affected the `getAspect` static method. Now,
+`getAspect` is only defined on non-abstract aspects. Previously, you
+could call `getAspect` on an abstract superaspect and (sometimes) get an
+instance of a subaspect back.
+
+This pattern was used in the Spacewar example in the AspectJ
+distribution. We had the class hierarchy
+
+....
+  SpaceObject (abstract)
+    |- Ship
+    |- Bullet
+    |- EnergyPellet
+....
+
+And the aspect hierarchy
+
+....
+  SpaceObjectDA (abstract)
+    |- ShipDA of eachobject(instanceof(Ship))
+    |- BulletDA of eachobject(instanceof(Ship))
+    |- EnergyPacketDA of eachobject(instanceof(Ship))
+....
+
+And we would call `SpaceObjectDA.getAspect(SpaceObject)` to access the
+aspect associated with a ship, bullet, or energy pellet. This pattern
+depended on the `SpaceObjectDA` aspect hierarchy exactly mirroring the
+`SpaceObject` hierarchy, and being maintained that way.
+
+A better way to implement this kind of design aspect is to use private
+introduction, a new feature of AspectJ.
+
+==== [#usingPrivateIntroduction]#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
+defined `of eachobject(instanceof(...))`. A prime example of this was
+the `BoundPoint` aspect of the bean example: which needed to associate
+each point with a `PropertyChangeSupport` object.
+
+[source,codeindent]
+----
+aspect BoundPoint of eachobject(instanceof(Point)) {
+
+    java.beans.PropertyChangeSupport support = null;
+
+    after() returning(Point p): receptions(p.new(..)){
+        support = new PropertyChangeSupport(myPoint);
+    }
+
+    around(Point p) returns void: receptions(void p.set*(*)) {
+        // code that uses support
+    }
+}
+----
+
+In the new version of AspectJ, a better way of accomplishing many of
+these state association is to use privately introduced fields. Instead
+of creating an aspect instance for every `Point` object, store the
+`PropertyChagneSupport` object in the `Point` objects themselves.
+
+[source,codeindent]
+----
+aspect BoundPoint {
+    private PropertyChangeSupport Point.support = new PropertyChangeSupport(this);
+
+    void around(Point p): setters(p) {
+        // code that uses p.support
+    }
+}
+----
+
+Just as in the past, the PropertyChangeSupport object is not accessable
+to anyone but the aspect, but now less mechanism is needed.
+
+There are times when changing aspects that are defined
+`of eachobject(instanceof(...))` may not be reasonable. If the aspect
+instance is stored or passed to other methods, then having a real
+`of eachobject(instanceof(...))`, now written `perthis(this(...))`,
+association may capture the crosscutting concern best.
+
+'''''
+
+=== [#pre07b11]#Porting pre-0.7beta11 code#
+
+* xref:#twoArgumentCalls[Removing two-argument calls]
+* xref:#adviceInClasses[Removing advice from Class declarations]
+
+The following changes are only required when porting code written prior
+to the 0.7beta11 release of AspectJ.
+
+==== [#twoArgumentCalls]#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
+
+For pointcuts denoting calls to particular static methods, such as
+
+____
+....
+calls(String, static String valueOf(int)) // deprecated
+....
+____
+
+the transformation is easy. Simply make the desired signature explicit.
+Instead of catching all calls to any static method that happens to have
+the signature `String valueOf(int)`, catch calls to that exact method
+defined in the String class.
+
+____
+....
+call(static String String.valueOf(int))
+....
+____
+
+Pointcuts denoting calls to classes of static methods can also be
+rewritten with these rules. For example,
+
+____
+....
+calls(my.package.*, static * get*(..)) // deprecated
+....
+____
+
+should now be written
+
+____
+....
+call(static * my.package.*.get*(..))
+....
+____
+
+===== 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
+fixed. So,
+
+____
+....
+calls(Thread, int getPriority()) // deprecated
+....
+____
+
+which denotes all calls to nullary int methods named `getPriority` when
+the called object is an instance of the `Thread` type, can almost always
+be rewritten
+
+____
+....
+call(int Thread.getPriority())
+....
+____
+
+which denotes all calls to the nullary int `Thread.getPriority()`
+method.
+
+Expanding the signature picks out slightly different join points than
+the original two-argument form. This won't matter for most programs, but
+in some cases the differences may be noticable. In particular, the
+expanded-signature form only picks out those calls where the called
+object is statically typed to `Thread` when its `int getPriority()`
+method is called. If you want to capture calls to the
+`int Thread.getPriority()` method, regardless of how the called object
+is statically typed, you shoud use the different translation:
+
+____
+....
+call(int getPriority()) && target(Thread)
+....
+____
+
+This will capture all call join points of methods with signature
+`int Thread.getPriority()`.
+
+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#
+
+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
+
+____
+....
+class C {
+    static before(): executions(C.new()) { ... } // deprecated
+}
+....
+____
+
+write
+
+____
+....
+class C {
+    static aspect ConstructionProtocol {
+        static before(): executions(C.new()) { ... }
+    }
+}
+....
+____
+
+If your advice doesn't refer to any inner classes or interfaces of C,
+you can move the inner aspect out of the class entirely.
+
+____
+....
+class C { ... }
+
+aspect ConstructionProtocol {
+    static before(): execution(C.new()) { ... }
+}
+....
+____
+
+Your code will be clearer if you consider the purpose of each piece of
+advice when you make this change. It may be that some of the advice
+naturally belongs to another aspect, perhaps already existing. Or it may
+be that some pieces of advice in a class are associated to one concern
+and some to another; in which case more than aspect would be
+appropriate.
+
+'''''
+
+=== [#pre07b10]#Porting pre-0.7beta10 code#
+
+* xref:#joinPoints[Changing access to thisJoinPoint]
+
+The following changes are only required when porting code written prior
+to the 0.7beta10 release of AspectJ.
+
+==== [#joinPoints]#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
+of the `runNext()` static method, and the use of an interface hierarchy
+represent the join point object.
+
+===== [#proceed]#`thisJoinPoint.runNext()` to `proceed()`#
+
+The elimination of the `runNext()` static method requires almost no
+porting work. An automatic replacement of the string
+
+____
+`thisJoinPoint.runNext`
+____
+
+with the string
+
+____
+`proceed`
+____
+
+will do the job. However, if any around advice used the identifier
+"`proceed`" as a formal parameter or local variable, it must be renamed,
+and if any aspect used it as a field, then references to the field in
+around advice should be made explicit (prefixing the reference with the
+aspect name or "`this`", depending on whether the field is static or
+not).
+
+===== [#thisJoinPoint]#Using `thisJoinPoint`#
+
+While access to reflective information through `thisJoinPoint` is more
+powerful and regular through its interface hierarchy, the previous uses
+must be rewritten. Changing your code will likely require manual
+editing, but in doing so your code should get simpler and cleaner.
+
+Many existing uses of the fields on join points can be re-written to use
+one of:
+
+* `thisJoinPoint.toString()`
+* `thisJoinPoint.toShortString()`
+* `thisJoinPoint.toLongString()`
+* `thisJoinPoint.getSignature().toString()`
+* `thisJoinPoint.getSignature().toShortString()`
+* `thisJoinPoint.getSignature().toLongString()`
+
+For example:
+
+____
+....
+System.out.println(thisJoinPoint.className + "." +
+                   thisJoinPoint.methodName)
+....
+____
+
+can be replaced with
+
+____
+`System.out.println(thisJoinPoint)`
+____
+
+or
+
+____
+`System.out.println(thisJoinPoint.getSignature().toShortString())`
+____
+
+with comparable behavior.
+
+Accesses to the parameters field of join points should be changed as
+follows. A field access like:
+
+____
+`thisJoinPoint.parameters`
+____
+
+must be changed to:
+
+* `thisJoinPoint.getArgs()`
+
+Accesses to the methodName and className fields of join points that are
+not suitable for replacement with a toString method, should be changed
+as follows. Field accesses like:
+
+* `thisJoinPoint.className`
+* `thisJoinPoint.methodName`
+
+must be changed to:
+
+* `thisJoinPoint.getSignature().getDeclaringType().getName()`
+* `thisJoinPoint.getSignature().getName()`
+
+Accessses to the parameterNames and parameterTypes fields of join
+points, that are not suitable for conversion to one of the toString()
+methods should be changed as follows. Field access like:
+
+* `thisJoinPoint.parameterNames`
+* `thisJoinPoint.parameterTypes`
+
+must be changed to:
+
+* `((CodeSignature)thisJoinPoint.getSignature()).getParameterNames()`
+* `((CodeSignature)thisJoinPoint.getSignature()).getParameterTypes()`