--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html> <head>
+<title>AspectJ 1.6.1 Readme</title>
+<style type="text/css">
+<!--
+ P { margin-left: 20px; }
+ PRE { margin-left: 20px; }
+ LI { margin-left: 20px; }
+ H4 { margin-left: 20px; }
+ H3 { margin-left: 10px; }
+-->
+</style>
+</head>
+
+<body>
+<div align="right"><small>
+© Copyright 2008 Contributors.
+All rights reserved.
+</small></div>
+
+<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
+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
+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>
+<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=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</a>
+</ul>
+<hr>
+
+<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:
+
+<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)
+<h4>Binary weaving</h4>
+<h4>AJDT Project Building</h4>
+<h4>Loadtime weaving</h4>
+<h4>Loadtime weaving stress</h4>
+<hr>
+
+<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:
+Given this setup:</p>
+<code><pre>
+enum Colour { RED,GREEN,BLUE;}
+
+@interface ColouredAnnotation { Colour value(); }
+
+@ColouredAnnotation(Colour.RED)
+public void colouredMethod() { }
+</pre></code>
+
+<p>Current syntax:</p>
+<pre><code>
+before(ColouredAnnotation anno): execution(* *(..)) && @annotation(anno) {
+ printTheColour(anno.value());
+}
+</pre></code>
+<p>New optional syntax:</p>
+<code><pre>
+before(Colour col): execution(* *(..)) && @annotation(ColouredAnnotation(col)) {
+ printTheColour(col);
+}
+</pre></code>
+
+<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. It currently does not document or add
+structural links for any inter-type declarations or other declare forms.</p>
+<p>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:<br>
+ <tt>> cd examples<br>
+ > 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>
projects / aspectj.git / commitdiff