1.6.1 done?V1_6_1rc1

6 files changed, 80 insertions, 546 deletions

diff --git a/docs/dist/doc/README-161.html b/docs/dist/doc/README-161.html
index b6bdbe8fd..35b58ea3b 100644
--- a/docs/dist/doc/README-161.html
+++ b/docs/dist/doc/README-161.html
@@ -20,17 +20,15 @@ All rights reserved.
 
 <h1>AspectJ 1.6.1 Readme</h1>
 
-WORK IN PROGRESS
-
-<p>The main themes of AspectJ1.6.1 are better memory consumption and faster weaving.
-This has been achieved through in depth profiling of the weaving process and has
-resulted in a radical refactoring of the weaver component within AspectJ.  It provides
-exactly the same functionality as in previous releases, it just weaves faster now
-(and in less space!).  This readme will give an overview of the kind of changes
+<p>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.</p>
 
 <p>The complete list of issues resolved for AspectJ 1.6.1 can be found with
-these bugzilla queries.  The first lists bugs addressed whilst the second details
+these bugzilla queries.  The first lists bugs addressed (more than 60!) whilst the second details
 enhancements made in this release.</p>
 <ul>
 <li><a href="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</a>
@@ -40,22 +38,88 @@ enhancements made in this release.</p>
 
 <h2>Refactored (<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=231396">bug 231396</a>)</h2>
 
-<p>The bugzilla entry goes into more specifics on what has changed, the end result is that aspectjweaver.jar has had 290 classes removed (about XX%) and has slimmed down by 400k (about XX%).  In terms
-of performance for different scenarios:
+<p>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:
 
 <h4>Straight compilation</h4>
-<p>Building the internal AspectJ compiler - where aspects are used to modify the Eclipse JDT Compiler. 1150 source files, aspects applying at 859 join points. 256M heap (fails in 64M): 28s    161=28s
-verbosegc on 160 (502gcs,21 full).   161=28s.... (473gcs, 21 full) 
+<p>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).
+<ol>
+<li>1100 source files, few aspects that target 859 join points.
+<li>1100 source files, code style trace aspect targeting public methods (22000 join points)
+<li>1100 source files, annotation style trace aspect (22000 join points)
+<li>1100 source files, insane aspect (before(): within(*) {}) (203000 join points)
+</ol>
+<p>
+<center>
+<img src="perfSourceCompile_161.PNG"></img>
+</center>
+
 <h4>Binary weaving</h4>
-<h4>AJDT Project Building</h4>
+<p>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.
+<ol>
+<li>Binary weaving rt.jar (~12000 classes) with a simple aspect (1200 join points)
+<li>Binary weaving rt.jar (~12000 classes) with a code style trace aspect (121000 join points)
+<li>Binary weaving rt.jar (~12000 classes) with an annotation style trace aspect (121000 join points)
+<li>Binary weaving rt.jar (~12000 classes) with an insane aspect (before(): within(*) {}) (352000 join points)
+</ol>
+<center>
+<img src="perfBinaryWeave_161.PNG"></img>
+</center>
+
 <h4>Loadtime weaving</h4>
+<p>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.
+<ol>
+<li>Binary weaving tools.jar (~1900 classes) with a code style trace aspect
+<li>Binary weaving tools.jar (~1900 classes) with an insane aspect (before(): within(*) {})
+</ol>
+<center>
+<img src="perfLTW_161.PNG"></img>
+</center>
+<p>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
+<ol>
+<li>First, the number of kilobytes of memory allocated from the heap during a weave of tools.jar with a code style trace aspect
+<li>Second, another run of the same thing
+<li>Third, this time using the insane aspect
+</ol>
+<center>
+<img src="heapContents_161.PNG"></img>
+</center>
+<p>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.
+
 <h4>Loadtime weaving stress</h4>
-<hr>
+<p>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 <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=210470">bug 210470</a> 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.
+<center>
+<img src="memLtwStress_161.PNG"></img>
+</center>
+<p>In 1.6.0 the memory was never correctly recovered and so an OutOfMemory problem would always occur eventually.
+
+
+<h2>Incremental compilation</h2>
+<p>Following on from the work done to improve compilation under Eclipse in AspectJ 1.6.0 (<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=221427">Bug 221427</a>
+) - we now support the building of 'broken code' (<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=102733">bug 102733</a>).  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.
 
 <h2>Language changes</h2>
 <h4>Optmized syntax for annotation value binding (<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=234943">Bug234943</a>)</h4>
-<p>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:
+<p>If only binding an annotation at a method-execution join point in order to access an <b>enum value</b>
+within it, there is a more optimal syntax that can be used to produce faster code.
 Given this setup:</p>
 <code><pre>
 enum Colour { RED,GREEN,BLUE;}
@@ -81,537 +145,7 @@ before(Colour col): execution(* *(..)) && @annotation(ColouredAnnotation(col)) {
 
 <hr>
 
-<p>AspectJ 1.6.1 includes some minor new features in the language, but 
- 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 <a href="progguide/index.html">AspectJ Programming Guide</a>
-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 <a href="porting.html">porting.html</a>.
-</p>
-
-<p>This document first summarizes changes from the 1.1.1 release in
-</p>
-
-<ul>
-  <li><a href="#compiler">the compiler</a>,</li>
-  <li><a href="#tools">the support tools</a>,</li>
-  <li><a href="#runtime">the runtime</a>,</li>
-  <li><a href="#devenv">the development environment support</a>,</li>
-</ul>
-
-<p> then <a href="#details">details</a> some of the changes,
-    and finally points readers to the bug database for 
-    <a href="#allchanges">all the changes</a>.
-</p>
-
-<!-- ============================== -->
-
-<!-- ============================== -->
-<hr>
-<h2><a name="compiler">The Compiler</a></h2>
-
-  Compared to AspectJ 1.1.1, the AspectJ 1.2 compiler...
-  
-  <ul>
-  <li><a href="#WEAVE_TIME">Is faster</a>, with weaving completing in less than half the time it
-      used to take in many cases.
-      <a name="WEAVE_CHART"><img src="images/AspectJ11v12.JPG"></img></a>.</li>
-  <li>Supports the <a href="#LAZY_TJP">-XlazyTjp option</a> which produces code that runs 
-  faster and uses less memory in some common cases.</li>
-  <li>Has <a href="#INCREMENTAL">much better support for incremental compilation</a>.</li>
-  <li>Produces <a href="#ERROR_MESSAGES">better error messages</a>.</li>
-  <li>Has some <a href="#LINT">new lint warnings</a> to catch common mistakes and changes to serializability.</li>
-  <li>Supports the <a href="#REWEAVABLE">-Xreweavable option</a> that allows classes to be woven more
-  than once.<li>
-  <li>Supports the <a href="#INPATH">-inpath option</a> which allows both directories and jars
-  containing class files to be specified as input to the weaver.</li>
-  <li><a href="#COMPLIANCE">Changes the default compiler compliance mode</a> from -1.3 to -1.4.
-  </ul>
-
-  <p> A short description of the options ajc accepts is available with
-  "<code>ajc -help</code>". 
-  Longer descriptions are available in the 
-  <a href="devguide/ajc-ref.html">Development Environment Guide
-  section on ajc</a>. </p>
-  <p> </p>
-
-
-<!-- ============================== -->
-<hr>
-<h2><a name="tools">Support Tools</a></h2>
-
-  <p>AspectJ 1.2 contains two important changes to the supporting tools:</p>
-  
-  <ul>
-  <li><a href="#AJDOC">ajdoc</a> is back<li>A sample script is supplied for <a href="#LTW">load-time weaving</a> from the command-line.
-  </ul> 
-<!-- ============================== -->
-<hr>
-<h2><a name="runtime">The Runtime Library</a></h2>
-
-  <p>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.</p>
-
-  <ul>
-  <li><a href="#SOFTEX"><code>SoftException</code></a> now supports <code>getCause()</code>.</li>
-  
-  <li>Although not part of <code>aspectjrt.jar</code> this release also provides a new set of
-  tools APIs in the <a href="#LTW2"><code>org.aspectj.weaver.tools</code></a> that provide a weaving class loader
-  and an adapter that can be used to integrate load-time weaving into an existing class loader
-  hierarchy.</li>
-  <li>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.
-  </ul>
-
-<!-- ============================== -->
-<hr>
-<h2><a name="devenv">The AJDE Tools</a></h2>
-
-  <p> 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.</p>
-  
-  <p>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 <a href="http://www.eclipse.org/ajdt">
-  AJDT project website</a>.
-
-<!-- ============================== -->
-<hr>
-<h2><a name="details">Details</a> of some compiler changes</h2>
-
-  <h3><a name="WEAVE_TIME">Compilation (weave) times reduced.</a></h3>
-  
-  <p>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 <a href="#WEAVE_CHART">chart above</a>). 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.</p>
-  
-  <p>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.</p>
-  
-  <h3><a name="LAZY_TJP">The -XlazyTjp option.</a></h3>  
-  
-  <p>Under AspectJ 1.1.1, if the body of an advice contained a reference to a 
-  non-statically determinable portion of <code>thisJoinPoint</code> (such as for example a call
-  to <code>getArgs()</code>), then a JoinPoint object was always creating before entering the advice.
-  This was the case even if the advice was guarded with an <code>if()</code> pointcut that 
-  evaluated to false. </p>
-  
-  <p>AspectJ 1.2 now supports the <code>-XlazyTjp</code> option that only creates the JoinPoint object just
-  before dispatching to the advice body. By promoting the guard to a test in an <code>if()</code> pointcut,
-  the creation of the JoinPoint object can be avoided altogether in the case where the test returns false.</p>
-  
-  <p>Consider a simple tracing aspect as follows:</p>
-  
-  <pre>
-  
-  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....
-    }
-  }
-  
-  </pre>
-  
-  <p> The most important consideration is the system overhead when tracing is turned off. Using the 
-  <code>-XlazyTjp</code> 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.
-  </p>
-
-  <h3><a name="INCREMENTAL">Improvements to incremental compilation.</a></h3>  
-  
-  <p>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 <code>inpath</code> 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.  
-  
-  <p>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.</p>
-
-  <h3><a name="ERROR_MESSAGES">Improved error messages.</a></h3>  
-  
-  <p>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 <code>declare error</code> statement might look as follows under AspectJ 1.1.1: </p>
-
-  <font color="red">
-  <pre>
-
-  BadClass.java:6 should not be calling bad methods
-  </pre>
-  </font>
-  
-  <p>whereas in AspectJ 1.2 you will see:</p>
-  
-  <font color="red">
-  <pre>
-
-  BadClass.java:6 error should not be calling bad methods
-  new C().bad();
-  ^^^^^^^^^^^^^^
-       method-call(void C.bad())
-       see also: DeclareError.java:5
-  </pre>
-  </font>
-  
-  <p>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 <code>declare error</code> and 
-  <code>declare warning</code> statements, AspectJ now shows not only the location of the 
-  error or warning, but also the location of the <code>declare</code> statement itself. 
-  Finally, note that messages produced as a result of <code>declare error</code> and 
-  <code>declare warning</code> statements now also display the matched join point at the 
-  location of the error:</p>
-  
-  <p>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: </p>  
-  <font color="red">
-  <pre>
-
-  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
-  </pre>
-  </font>
-
-  <p>This error message tells us that <code>BadClass.class</code> contained in a jar on the inpath called <code>bin-input.jar</code>,
-  and originally compiled from a source file called <code>BadClass.java</code>, contains a join point 
-  (<code>method-call(void C.bad())</code> matched by a <code>declare error</code> statement on line 5 of the file 
-  <code>DeclareError.java</code>.
-
-  <h3><a name="LINT">New lint warnings.</a></h3>  
-  
-  <p>Consider the program:</p>
-  
-  <pre>
-  <code>
-  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 }
-  </code>
-  </pre>
-  
-  <p>Because the static type of <code>bInDisguise</code> is <code>A</code> (line 14), the call on line
-  17 is never matched by the pointcut expression on 24, even though the runtime type of 
-  <code>bInDisguise</code> is <code>B</code>. Type patterns matched in <code>call</code> 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 
-  (<code><b>unmatchedSuperTypeInCall</b></code>) which is enabled by default.</p>
-
-  <p>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:</p>
-
-  <pre>
-  <code>
-  <font color="red">
-  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
-  </font>
-  <font color="blue">
-  1 warning
-  </font>
-  </code>
-  </pre>
-
-  <p> 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 <code>bInDisguise.doIt()</code>. Since the 
-  static type of <code>bInDisguise</code> is <code>A</code>, 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 
-  <code>call(* doIt(..) && target(B)</code>.</p>
-
-  <p>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 <code>target</code> designator in place of a type pattern in the <code>call</code> 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 <code>target</code> expression. Also note that <code>target</code> cannot be used in <code>declare</code> statements.
-  </p>
-  
-  <p>A new Xlint warning, <code><b>needsSerialVersionUIDField</b></code> (disabled by default) will produce a 
-  warning at compile time if the process of weaving changes the default <code>serialVersionUID</code> of
-  a serializable class, and the class does not define a <code>serialVersionUID</code>. By defining a 
-  <code>serialVersionUID</code> 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.</p>
-  
-  <p>A complimentary Xlint warning, <code><b>brokeSerialVersionCompatibility</b></code> (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). 
-
-  <h3><a name="REWEAVABLE">The -Xreweavable option.</a></h3>  
-  
-  <p>The new <code>-Xreweavable</code> 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
-  <code>-Xnoweave</code> 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. 
-  
-  <p>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.
-  
-  <h3><a name="INPATH">The -inpath option.</a></h3>  
-  
-  <p>The new <code>-inpath</code> option replaces the <code>-injars</code> 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. 
-
-  <h3><a name="COMPLIANCE">The default compliance mode of the compiler has changed from -1.3 to -1.4.</a></h3>  
-  
-  <p>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: 
-   <ul>
-   <li> 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).
-   <li> <code>call</code> pointcuts may match more join points than in the same
-   program compiled at compliance level 1.3.
-   </ul>
-   <p>The AspectJ compiler can be restored to 1.3 compliance settings by specifying the
-   "-1.3" option on the command-line.
-   </p>
-   <p>Consider again the following example program which illustrates the differences in join point matching
-   with the <code>call</code> pointcut designator between 1.4 and 1.3 compliance levels. 
-
-   <pre>
-   <code>
-   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 }
-   </code>
-   </pre>
-
-   <p>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:</p>
-   <p><code>About to call B.doIt(...)</code></p>
-   <p>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 <i>is</i> matched by the call pcd.
-
-   <p>This is a good example of why the recommended style is to use <code>call(* doIt(..)) && target(B)</code>,
-   which always matches based on the actual type of the receiver.
-  
-<!-- ============================== -->
-<hr>
-
-  <h3><a name="AJDOC">The ajdoc tool makes a comeback in the AspectJ 1.2 distribution.</a></h3>  
 
-  <p><code>ajdoc</code> (the AspectJ replacement for the <code>javadoc</code> tool) is once again included in
-  the AspectJ distribution.  The <code>ajdoc</code> 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. </p>
-<p><b>Known limitations: </b>Please note that <code>ajdoc</code> documents 
-advice and pointcut members, shows where advice applies and links affected 
-members back to the advice.&nbsp; It currently does not document or add 
-structural links for any inter-type declarations or other declare forms.</p>
-<p>Run the &quot;ajdoc.bat&quot; script just 
-	as you run javadoc.&nbsp; For a list of accepted parameters run &quot;ajdoc 
-	-help&quot;.&nbsp; For example, to document everything in the Spacewar example 
-	run:<br>
-	<tt>&gt; cd examples<br>
-	&gt; ajdoc -d doc -private spacewar coordination</tt></p>
-  
-  <p><code>ajdoc</code> sample output for an aspect source file:</p>
-  
-  <p><img src="images/ajdoc1.JPG"/></p>
-  
-  <p><code>ajdoc</code> sample output for advised methods:</p>
-  
-  <p><img src="images/ajdoc2.JPG"/></p>
-
-  <h3><a name="LTW">A sample script is supplied that supports load-time weaving from the command-line</a></h3>  
-  
-  <p>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 
-  <code>doc/examples/ltw</code> directory of your AspectJ installation. </p>
-  
-  <p>The scripts allow you to set an environment variable, <code>ASPECTPATH</code>, containing a path-separator
-  delimited list of aspect-library jar files. A Java application can then be launched using the "<code>aj</code>"
-  script ("<code>aj</code>" is to "<code>ajc</code>" as "<code>java</code>" is to "<code>javac</code>"). If the
-  <code>ASPECTPATH</code> is unset or empty, "<code>aj</code>" behaves exactly the same as "<code>java</code>",
-  but if the <code>ASPECTPATH</code> contains one or more aspect libraries, the aspects in the library will be 
-  linked (woven) with the application code as it is loaded.<p>
-  
-  <p>The <code>doc/examples/ltw</code> directory of your AspectJ installation contains a sample application that
-  demonstrates these capabilities. Following the instructions in the <code>README</code> file in that directory,
-  running "<code>aj tracing.ExampleMain</code>" with <code>ASPECTPATH</code> unset produces the output:</p>
-  
-  <font color="blue">
-  <pre>
-  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)
-  </pre>
-  </font>
-  
-  <p>If you set <code>ASPECTPATH</code> to include <code>../jars/tracingLib.jar</code>, and run
-  "<code>aj tracing.ExampleMain</code>" again, the output will be:</p>
-  
-  
-  <font color="blue">
-  <pre>
-  --> 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...
-  </pre>
-  </font>
-  
-  <p>The scripts only support JDK 1.4 and above - attempting to use them with a 1.3 or lower JDK will most
-  likely produce <code>NoClassDefFound</code> errors. We welcome contributions from users to improve these
-  scripts.</p>
-  
 <!-- ============================== -->
-<hr/>
-  
-  <h3><a name="SOFTEX">SoftException now supports getCause()</a></h3>  
-  
-  <p><code>org.aspectj.lang.SoftException</code> now supports the <code>getCause()</code> method, which returns the
-  original exception wrapped by the <code>SoftException</code>. This means that exception chains will print correctly
-  on 1.4 and later JREs.
-
-  <h3><a name="LTW2">org.aspectj.weaver.tools package added</a></h3>  
-  
-  <p>A new set of public APIs are exported by the 
-  <a href="api/index.html"><code>org.aspectj.weaver.tools</code></a> package that can be used
-  to integrate load-time weaving into an existing class loader hierachy. The package implementation
-  is included in <code>aspectjtools.jar</code>. For an example of how to use these APIs, see the
-  <code>org.aspectj.weaver.WeavingURLClassLoader</code> implementation.
-
-<hr/>
-	<a name="allchanges"></a>
-	<h2>All changes are listed in the bug database</h2>
-	For a complete list of changes in the 1.2 release, search for 
-	<code>target 1.2</code> in the bug database:
-	<a href="https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&target_milestone=1.2">
-		https://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&component=Compiler&target_milestone=1.2
-	</a>
   
 </body> </html>
diff --git a/docs/dist/doc/heapContents_161.PNG b/docs/dist/doc/heapContents_161.PNG
new file mode 100644
index 000000000..5f1fc8be7
--- /dev/null
+++ b/docs/dist/doc/heapContents_161.PNG
diff --git a/docs/dist/doc/memLtwStress_161.PNG b/docs/dist/doc/memLtwStress_161.PNG
new file mode 100644
index 000000000..20e687b08
--- /dev/null
+++ b/docs/dist/doc/memLtwStress_161.PNG
diff --git a/docs/dist/doc/perfBinaryWeave_161.PNG b/docs/dist/doc/perfBinaryWeave_161.PNG
new file mode 100644
index 000000000..f90df40b5
--- /dev/null
+++ b/docs/dist/doc/perfBinaryWeave_161.PNG
diff --git a/docs/dist/doc/perfLTW_161.PNG b/docs/dist/doc/perfLTW_161.PNG
new file mode 100644
index 000000000..2f5599286
--- /dev/null
+++ b/docs/dist/doc/perfLTW_161.PNG
diff --git a/docs/dist/doc/perfSourceCompile_161.PNG b/docs/dist/doc/perfSourceCompile_161.PNG
new file mode 100644
index 000000000..b5c55bb58
--- /dev/null
+++ b/docs/dist/doc/perfSourceCompile_161.PNG