From 241c99cde83958b7a679f7eeca9eb2a579e74d5d Mon Sep 17 00:00:00 2001 From: acolyer Date: Mon, 19 Dec 2005 09:31:04 +0000 Subject: [PATCH] migration of Wes' doc changes in HEAD into 1.5.0 release branch (but removing references to -XhasMember as that's really ready to be publically doc'd yet) --- docs/devGuideDB/ajc.xml | 51 ++++++- docs/devGuideDB/antsupport.xml | 37 +++-- docs/devGuideDB/compatibility.xml | 2 +- docs/dist/doc/README-150.html | 46 +++---- docs/dist/doc/index.html | 42 +----- docs/faq/faq.xml | 220 ++++++++++++++++++++++++++++-- 6 files changed, 306 insertions(+), 92 deletions(-) diff --git a/docs/devGuideDB/ajc.xml b/docs/devGuideDB/ajc.xml index 04393eaa5..0aa7bae93 100644 --- a/docs/devGuideDB/ajc.xml +++ b/docs/devGuideDB/ajc.xml @@ -252,23 +252,34 @@ -1.3 Set compliance level to 1.3 + This implies -source 1.3 and -target 1.1. -1.4 Set compliance level to 1.4 (default) + This implies -source 1.4 and -target 1.2. - -source [1.3|1.4] - Toggle assertions (1.3 or 1.4, default is 1.3). + -1.5 + Set compliance level to 1.5. + This implies -source 1.5 and -target 1.5. + + + + + -source [1.3|1.4|1.5] + Toggle assertions (1.3, 1.4, or 1.5 - default is 1.4). When using -source 1.3, an assert() statement valid under Java 1.4 will result in a compiler error. When using -source 1.4, treat assert as a keyword and implement assertions according to the 1.4 language spec. + When using -source 1.5, + Java 5 language features are permitted. @@ -410,7 +421,8 @@ -Xreweavable[:compress] - (Experimental) runs weaver in reweavable mode which causes + (Experimental - deprecated as now default) + Runs weaver in reweavable mode which causes it to create woven classes that can be rewoven, subject to the restriction that on attempting a reweave all the types that advised the woven type must be accessible. @@ -433,11 +445,33 @@ -XserializableAspects - (Experimental) Normally it is an error to declare + + (Experimental) Normally it is an error to declare aspects Serializable. This option removes that restriction. - + + -XnotReweavable + + (Experimental) Create class files that can't be subsequently rewoven by AspectJ. + + + + + + -Xajruntimelevel:1.2, ajruntimelevel:1.5 + + (Experimental) Allows code to be generated that targets a 1.2 or a 1.5 level AspectJ runtime (default 1.5) + + + @@ -486,7 +520,12 @@ pubwork="book">The Java Virtual Machine Specification, Second Edition and runs on any Java 2 compatible platform. The code it generates runs on any Java 1.1 or later - compatible platform. + compatible platform. + For more information on compatibility with + Java and with previous releases of AspectJ, + see + . + diff --git a/docs/devGuideDB/antsupport.xml b/docs/devGuideDB/antsupport.xml index bf295e4b7..a21268ad0 100644 --- a/docs/devGuideDB/antsupport.xml +++ b/docs/devGuideDB/antsupport.xml @@ -425,10 +425,17 @@ X - - Set experimental option(s), using comma-separated list of accepted options - (unlisted here). Options should not contain the leading X. - XLint options should be specified using the xlint... entries. + + Set experimental option(s), using comma-separated list of accepted options + Options should not contain the leading X. + Some commonly-used experimental options have their + own entries. The other permitted ones (currently) are + serializableAspects, incrementalFile, lazyTjp, + reweavable, notReweavable, noInline, + noWeave, + ajruntimelevel:1.2, and ajruntimelevel:1.5. + Of these, some were deprecated in AspectJ 5 + (reweavable, noWeave, etc.). @@ -466,6 +473,13 @@ If true, emit .ajesym symbol files for Emacs support. + + crossref + + + If true, emit .ajsym file into the output directory. + + verbose @@ -680,10 +694,11 @@ Set source compliance level to one of - [1.3 1.4] - (e.g., in 1.4 no assert identifiers - and no import from default package). - Defaults to 1.3 compliance level. + [1.3 1.4 1.5] + (default is 1.4). + 1.3 implies -source 1.3 and -target 1.1. + 1.4 implies -source 1.4 and -target 1.2. + 1.5 implies -source 1.5 and -target 1.5. @@ -1372,9 +1387,9 @@ X - comma-delimited list of extended (-X...) options, - entered without -X (e.g., - X="lint" for -Xlint). + deprecated X options include + reweavable (on by default) + reweavable:compress (compressed by default) diff --git a/docs/devGuideDB/compatibility.xml b/docs/devGuideDB/compatibility.xml index 636fc60cf..cbdacefde 100644 --- a/docs/devGuideDB/compatibility.xml +++ b/docs/devGuideDB/compatibility.xml @@ -2,7 +2,7 @@ AspectJ version compatibility - + Version Compatibility Systems, code, and build tools change over time, often not in step. diff --git a/docs/dist/doc/README-150.html b/docs/dist/doc/README-150.html index 2329a181a..f36bc132b 100644 --- a/docs/dist/doc/README-150.html +++ b/docs/dist/doc/README-150.html @@ -14,37 +14,33 @@
-© Copyright 2004 Contributors. +© 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 to extend the capabilities of AspectJ in -general. These changes are too extensive to describe in a simple readme file, -so instead we have created the AspectJ 5 -Developer's Notebook to describe them.

- -

The 1.5.0 M1 milestone release supports a subset of the changes described -in the developer's notebook. Currently implemented features are:

- -
    -
  • Varargs -
  • Enums -
  • Covariance -
  • Annotations, with the following - exceptions: declare annotation is not yet implemented, and the @pcd forms - can be used for matching, but not yet for binding of formals. -
  • Autoboxing -
  • Bridge methods created by Java compilers to support generics are treated - as synthetic and have no join points. -
- -

These are implemented as changes to the weaver, not the front-end compiler. -The 1.5.0 M1 release cannot be used to compile code using Java 5 -features, but can be used to weave (inpath) Java classes created by a Java 5 -compiler.

+in order to support Java 5 and extend the capabilities of AspectJ in +general. For language changes, see AspectJ 5 +Developer's Notebook. For tools changes, see the +AspectJ Development Environment Guide, + especially the section on +Load-time weaving. +The changes are summarized in the + 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 + + the AspectJ documentation home page + . +

For information on bug fixes in AspectJ 5 v1.5.0, see the changes document.

diff --git a/docs/dist/doc/index.html b/docs/dist/doc/index.html index 5827eb068..89b8de596 100644 --- a/docs/dist/doc/index.html +++ b/docs/dist/doc/index.html @@ -15,6 +15,7 @@ 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.

@@ -31,10 +32,7 @@ @@ -175,38 +173,6 @@ - - - - - - - - - - - @@ -313,7 +279,9 @@ Deciding to adopt AspectJ, the Development tools sections (one, - two), and + two, + Load-time weaving + ), and AspectJ as open-source.

diff --git a/docs/faq/faq.xml b/docs/faq/faq.xml index 8b87873c6..ff6acf3ad 100644 --- a/docs/faq/faq.xml +++ b/docs/faq/faq.xml @@ -22,7 +22,7 @@ 2003-2005 Contributors. All rights reserved. - Last updated October 6, 2005 + Last updated December 18, 2005 For a list of recently-updated FAQ entries, see @@ -1551,6 +1551,28 @@ aspect PublicErrorLogging { Using the AspectJ compiler + + + + Do I have to use the AspectJ compiler? + + + + The AspectJ compiler or weaver is required at some point, but + many people can use AspectJ without changing their build or + deployment process significantly. For aspects that are not + required to compile, you can use the AspectJ binary weaver, run + at build-time or class-load-time. You can write aspects using + the original code style (which must be compiled with the AspectJ + compiler) or using the annotation style new in AspectJ 5 (which + may be compiled with Javac or the AspectJ compiler). + + For more information, see + . + + + @@ -1746,7 +1768,7 @@ ajc -bootclasspath c:\jdk1.2\jre\lib\rt.jar \ Yes. As with Javac, - use the -source 1.5 option as described + use the -1.5 option as described in the Development Environment Guide @@ -3776,6 +3798,169 @@ aspect A { + + + + + What are the new features of AspectJ 5? + + + + + All the new features are documented in the + + AspectJ 5 Developer's Notebook + and the + + AspectJ Development Environment Guide. + To summarize: + + + + Java 5 support: as an extension to Java, AspectJ supports + all the new language features of Java 5, including generics + (parameterized types), autoboxing, covariant return types, + enhanced for-loops, enums, varargs, and of course + annotations. + + + Java 5 extensions: the AspectJ language has been extended + to make use of Java 5 language features. + + + Generic aspects: an abstract aspect can be declared + with a generic type parameter which can be used + in pointcuts and when declaring members on the aspect + (but not when declaring members on other types). + + + Annotations: pointcuts can now pick out join points + based on the associated annotations, annotation + values can be bound in the same way that other + context variables are bound at the join point, + and annotations may be declared on other types in + an aspect. + + + + + Annotation-style aspects: AspectJ 5 integrates AspectWerkz-style + aspects declared in annotations. This permits aspects to + be written and compiled in pure-java code and woven using + build-time or load-time weaving with the AspectJ weaver. + (The original AspectJ language aspects are distinguished + as "code-style" aspects.) + + + AspectWerkz load-time weaving: Load-time weaving is + greatly improved for all versions of Java, and now supports + an XML configuration file which can declare concrete aspects. + This means developers can deploy binary abstract aspects + that deployers configure using only XML. + + + pertypewithin instantiation model: aspects may now be instantiated + on a per-class basis. + + + Reflection and runtime support: AspectJ 5 supports reflection + on aspects using the Aspect class, and also support runtime + evaluation of pointcuts using a pointcut parser. + + + + + + + + + + Should I use code- or annotation-style aspects? + + + + + To use AspectJ, you can use the original code-style aspects + or the annotation-style aspects new in AspectJ 5. + + + The original code-style is a small extension of the Java language + designed to express crosscutting as clearly as possible + in ways familiar to most Java programmers. + To use the original code-style aspects, + compile them with the AspectJ compiler or weave + pre-compiled binary aspects using the AspectJ binary (.class) + weaver, either at build-time or at class-load-time. + Code-style aspects have excellent IDE support, allowing + you to navigate to and from affected source code. + + + Annotation-style + aspects are written (not surprisingly) using annotations. + They use the subset of the AspectJ language that works + when aspects are woven after the code is compiled. + The source files are compiled with Javac, which simply saves the + annotations in the .class files. The resulting .class files + must be woven using + the AspectJ weaver, which reads the annotations from the + .class file and uses them to define aspects. + Annotation-style aspects have the benefit of being compilable + by Javac, but you can't use the full AspectJ language, + and you don't enjoy the same level of IDE support + for viewing crosscutting structure. + + + + + + + What's new about the load-time weaving support in AspectJ 5? + + + + + While the AspectJ weaver could be used at load-time in previous + releases, the AspectJ 5 release supports much better integration + with the Java 5 VM and the BEA JRocket JVM. It also supports + an XML file for configuration that allows deployers to declare + concrete aspects using only XML. This means aspect developers + can write abstract aspects, and deployers need only configure + aop.xml and run using the AspectJ weaver in Java 5. + For example, to run Java 5 VM with load-time weaving, + + + + + + To declare a concrete aspect, add a a + concrete-aspect XML entity to META-INF/aop.xml. + This example extends a tracing aspect to apply to + every type in the application: + + + + + +]]> + + + For more information, see the + + AspectJ Development Environment Guide. + + + + Understanding AspectJ Technology @@ -3921,14 +4106,21 @@ aspect A { - AspectJ 1.1 can weave binary aspects + Since the 1.1 release, AspectJ can weave binary aspects into classes in bytecode form. Hooked up to a class loader, this can weave class bytecodes after they are read in, before the - class is defined by the VM. In the 1.1 release (or soon - thereafter) we will provide a proof-of-concept class loader, - but we expect most people will already have a custom - class loader which they will adapt to invoke our weaver. + class is defined by the VM. (This means load-time weaving + only works were aspects are not required to compile the pure-java + classes. If the aspects are required, then the Java classes + have to be compiled with the aspects using the AspectJ compiler.) + The AspectJ 1.2 release had the + WeavingURLClassLoader, and the 1.2.1 release introduced + the aj.bat script for Java 1.4. + The AspectJ 5 release introduces much better support for + load-time weaving, including declaring concrete aspects + in XML files and integrating with Java 5 and BEA JRocket + JVM's. See . Some have asked about only weaving particular classes specified at run-time. @@ -4648,6 +4840,10 @@ aspect A { Entries changed recently: + + + + @@ -4918,8 +5114,10 @@ aspect A { - 1.3 (AspectJ 5) - Support for Java 1.5 + 1.5 (AspectJ 5) + Support for Java 1.5, generic aspects, + annotations, etc. Integrates AspectWerkz-style + load-time weaving.

@@ -4936,9 +5134,7 @@ aspect A { - Yes. We will support weaving Java 5 classes and upgrade the language - to use annotations and generics. For more information, see the - documentation for the AspectJ 5 release. + Yes. Java 5 is supported in AspectJ 5. -- 2.39.5
distributions AspectJ; development environment support for - Eclipse, - Emacs, - JBuilder, - Netbeans, + Eclipse and JDeveloper.
- AspectJ for Emacs - AspectJ Development Environment support for - Emacs is available under the GPL - from the sourceforge project site - - http://aspectj4emacs.sourceforge.net -
- AspectJ for JBuilder - AspectJ Development Environment support for - JBuilder is available under the Mozilla Public License 1.1 - from the sourceforge project site - - http://aspectj4jbuildr.sourceforge.net -
- AspectJ for Netbeans - AspectJ Development Environment support for - Netbeans is available under the Mozilla Public License 1.1 - from the sourceforge project site - - http://aspectj4netbean.sourceforge.net -
Support for the JDeveloper IDE