From 1e815517b12de774be8e2321494a28f9f230dc0b Mon Sep 17 00:00:00 2001 From: wisberg Date: Tue, 11 Oct 2005 09:15:50 +0000 Subject: [PATCH] update for LTW and compatibility --- docs/devGuideDB/aj.xml | 55 +++++++++++ docs/devGuideDB/compatibility.xml | 125 ++++++++++++++++++++++++ docs/devGuideDB/devguide.xml | 77 ++++++--------- docs/devGuideDB/tools-intro.xml | 157 ++++++++++++++++++++++++++++++ 4 files changed, 369 insertions(+), 45 deletions(-) create mode 100644 docs/devGuideDB/aj.xml create mode 100644 docs/devGuideDB/compatibility.xml create mode 100644 docs/devGuideDB/tools-intro.xml diff --git a/docs/devGuideDB/aj.xml b/docs/devGuideDB/aj.xml new file mode 100644 index 000000000..f9627eb95 --- /dev/null +++ b/docs/devGuideDB/aj.xml @@ -0,0 +1,55 @@ + + + + aj + command-line launcher for basic load-time weaving + + + + + aj + Options + + arg... + + + + + Description + + The + aj command runs Java programs in Java 1.4 or + later by setting up + WeavingURLClassLoader as the system class + loader, to do load-time bytecode weaving. + + The arguments are the same as those used to launch the Java program. + Users should define the environment variables + CLASSPATH and + ASPECTPATH. + + For more information and alternatives for load-time weaving, + see . + + + + Examples + + + A simple example + + Use ajc to build a library, then weave at load time + + + + + + + diff --git a/docs/devGuideDB/compatibility.xml b/docs/devGuideDB/compatibility.xml new file mode 100644 index 000000000..636fc60cf --- /dev/null +++ b/docs/devGuideDB/compatibility.xml @@ -0,0 +1,125 @@ + + + AspectJ version compatibility + + + Version Compatibility + + Systems, code, and build tools change over time, often not in step. + Generally, later versions of the build tools understand earlier + versions of the code, but systems should include versions of the runtime + used to build the AspectJ program. + + Java compatibility + + AspectJ programs can run on any Java VM of the required version. + The AspectJ tools produce Java bytecode .class files that run on + Java compatible VM's. If a Java class is changed by an aspect, + the resulting class is binary compatible + (as defined in the Java Language Specification). Further, the + AspectJ compiler and weaving do all the exception checking + required of Java compilers by the Java specifications. + + Like other Java compilers, + the AspectJ compiler can target particular Java versions. Obviously, code + targeted at one version cannot be run in a VM of a lesser version. The + aspectjrt.jar is designed to take advantage + of features available in Java 2 or Java 5, but will run in a JDK 1.1.x + environment, so you can use AspectJ to target older or restricted + versions of Java. However, there may be restricted variants of + JDK 1.1.x that do not have API's used by the AspectJ runtime. If + you deploy to one of those, you can email + aspectj-dev@eclipse.org + or download the runtime code to modify it for your environment. + + + Aside from the runtime, running the AspectJ tools themselves will + require a more recent version of Java. + You might use Java 5 to run the AspectJ compiler to produce code + for Java 1.1.8. + + + + + Runtime library compatibility + + When deploying AspectJ programs, include on the classpath the + classes, aspects, and the AspectJ runtime library + (aspectjrt.jar). Use the version of the + runtime that came with the tools used to build the program. If the + runtime is earlier than the build tools used, it's very likely to + fail. If the runtime is later than the build tools used, it's possible + (but not guaranteed) that it will work. + Given that, three scenarios cause problems. First, you deploy new + aspects into an an existing system that already has aspects that were + built with a different version. Second, the runtime is already + deployed in your system and cannot be changed (e.g., some + application servers put aspectjrt.jar on the + bootclasspath). Third, you (unintentionally) deploy two versions + of the runtime, and the one loaded by a parent loader is used). + In earlier versions of AspectJ, these problems present in obscure + ways (e.g., unable to resolve a class). In later versions, a stack + trace might even specify that the runtime version is out of sync with + an aspect. To find out if the runtime you deployed is the one actually + being used, log the defining class loader for the aspects and + runtime. + + + Aspect binary compatibility + + Generally, binary aspects can be read by later versions of the + weaver if the aspects were built by version 1.2.1 or later. (Some + future weavers might have documented limitations in how far back + they go.) If a post-1.2.1 weaver reads an aspect built by a later + version, it will emit a message. If the weaver reads in a binary aspect + and writes it out again, the result will be in the form produced by that + weaver, not the original form of the aspect (just like other weaver + output). + With unreleased or development versions of the tools, there are no + guarantees for binary compatibility, unless they are stated in the + release notes. If you use aspects built with development versions of + the weaver, be careful to rebuild and redeploy with the next released + version. + + + Aspect source compatibility + + Generally, AspectJ source files can be read by later versions of + the compiler. Language features do not change in dot releases (e.g., + from 1.2.1 to 1.2.2). In some very rare cases, a language feature will + no longer be supported or may change its meaning; these cases are + documented in the release notes for that version. Some changes like + this were necessary when moving to binary weaving in the 1.1 release, + but at this time we don't anticipate more in the future. You might + also find that the program behaves differently if you relied on behavior + specific to that compiler/weaver, but which is not specified in the + Semantics appendix to the + Programming Guide. + + + Problems when upgrading to new AspectJ versions + Let's say your program behaves differently after being built with + a new version of the AspectJ tools. It could be a bug that was + introduced by the tools, but often it results from relying on + behavior that was not guaranteed by the compiler. For example, the + order of advice across two aspects is not guaranteed unless there is a + precedence relationship between the aspects. If the program + implicitly relies on a certain order that obtains in one compiler, it + can fail when built with a different compiler. + Another trap is deploying into the same system, when the + aspectjrt.jar has not been changed + accordingly. + Finally, when updating to a version that has new language + features, there is a temptation to change both the code and the tools + at the same time. It's best to validate the old code with the new tools + before updating the code to use new features. That distinguishes + problems of new engineering from those of new semantics. + + + + + diff --git a/docs/devGuideDB/devguide.xml b/docs/devGuideDB/devguide.xml index 691567609..9d66bd200 100644 --- a/docs/devGuideDB/devguide.xml +++ b/docs/devGuideDB/devguide.xml @@ -3,15 +3,15 @@ - - - - - + + + + ]> @@ -34,60 +34,47 @@ - This guide describes the tools in the AspectJ 1.2 development - environment. See also + This guide describes how to build and deploy AspectJ programs + using the AspectJ tools and facilities. See also The AspectJ Programming Guide, the documentation available with the AspectJ support available for - various integrated development environments (e.g., Eclipse, Emacs, - JBuilder, and NetBeans), + various integrated development environments (e.g., + Eclipse AJDT), and the most-recent documentation available from the AspectJ project page, at http://eclipse.org/aspectj. - + &tools-intro; - - - - Summary of command-line tools - - - Command-line tools - &ajc; - &ajdoc; - + + AspectJ command-line tools + + + <literal>ajc</literal>, the AspectJ compiler/weaver + &ajc; + + + <literal>ajdoc</literal>, the AspectJ documentation tool + ajdoc produces JavaDoc-style documentation + including crosscutting information. + &ajdoc; + + + <literal>ajdoc</literal>, the AspectJ load-time weaving script + aj launches programs, + configuring basic load-time weaving. + &aj; + + &ajbrowser; &antsupport; + <w; + &compatibility; - diff --git a/docs/devGuideDB/tools-intro.xml b/docs/devGuideDB/tools-intro.xml new file mode 100644 index 000000000..ab29d0c21 --- /dev/null +++ b/docs/devGuideDB/tools-intro.xml @@ -0,0 +1,157 @@ + + Introduction to the AspectJ tools + + The Eclipse AspectJ implementation + The AspectJ Programming Guide + describes the AspectJ language. This guide describes the AspectJ + tools produced by the AspectJ + team on + http://eclipse.org/aspectj. + The AspectJ tools include + - ajc, the compiler/weaver; + ajdoc, a documentation tool; ajbrowser, a crosscutting code viewer; + Ant support for ajc; and load-time weaving support. + These tools are delivered in the library folder of the AspectJ tools + installation, mainly in aspectjtools.jar (tools) and + aspectjrt.jar (runtime). + This guide does not describe the Eclipse AspectJ development tools + (AJDT). That is produced by another team (sharing some members) on + http://eclipse.org/ajdt. + AJDT is delivered as an Eclipse plugin, incorporating the classes in + the AspectJ tools libraries along with the Eclipse plugin interface + classes. + + + Since AspectJ 1.1, the tools have implemented the AspectJ language + using bytecode weaving, which combines aspects and classes to produce + .class files that run in a Java VM. There are other ways to implement the + language (e.g., compiler preprocessor, VM support); the AspectJ team + has always tried to distinguish the language and the implementation + so other groups could build alternative implementations of AspectJ. + To that end, + + The AspectJ Programming Guide, + Implementation Notes describes how the Java bytecode form affects + language semantics. VM- or source-based implementations may be free + of these limits or impose limits of their own, but most should be + fairly close to what's possible in Java bytecode. + + + Please be careful not to confuse any description of + weaving or of this implementation of the AspectJ language with + the AspectJ language semantics. + If you do, you might find yourself writing code that doesn't work as + expected when you compile or run it on other systems. + More importantly, if you + think about aspects in terms of weaving or of inserting or merging + code, then you can lose many of the design benefits of thinking + about an aspect as a single crosscutting module. + When the text below introduces an implementation detail, it will warn if + users make mistakes by applying it in lieu of the language semantics. + + + + + Bytecode weaving, incremental compilation, and memory usage + Bytecode weaving takes classes and aspects in .class form + and weaves them together to produce binary-compatible .class files that + run in any Java VM and implement the AspectJ semantics. + This process supports not only the compiler but also IDE's. + The compiler, given an aspect in source form, produces a binary + aspect and runs the weaver. IDE's can get information about + crosscutting in the program by subscribing to information + produced by weaver as a side-effect of weaving. + + Incremental compilation involves recompiling only what is necessary + to bring the binary form of a program up-to-date with the source form + in the shortest time possible. + Incremental weaving supports this by weaving on a per-class basis. + (Some implementations of AOP (including AspectJ 1.0) make use + of whole-program analysis that can't be done in incremental mode.) + Weaving per-class means that if the source for a pure Java class + is updated, only that class needs to be produced. However, if + some crosscutting specification may have been updated, then all + code potentially affected by it may need to be woven. The AspectJ + tools are getting better at minimizing this effect, but it is to + some degree unavoidable due to the crosscutting semantics. + + + Memory usage can seem higher with AspectJ tools. + Some aspects are written to potentially affect many classes, so each + class must be checked during the process of weaving. Programmers can + minimize this by writing the crosscutting specifications as narrowly + as possible while maintaining correctness. + (While it may seem like more memory, the proper comparison + would with with a Java program that had the same crosscutting, + with changes made to each code segment. That would likely require + more memory and more time to recompile than the corresponding + AspectJ program.) + + + Classpath, inpath, and aspectpath + AspectJ introduces two new paths for the binary input to the + weaver which you'll find referenced in , + , + , + and . + + As in Java, the classpath is where the AspectJ + tools resolve types specified in the program. When running an AspectJ + program, the classpath should contain the classes and aspects along with + the AspectJ runtime library, aspectjrt.jar. + + + In AspectJ tools, the aspectpath is where to find binary + aspects. Like the classpath, it can include archives (.jar and .zip files) + and directories containing .class files in a package layout (since + binary aspects are in .class files). These aspects affect other + classes in exactly the same way as source-level aspects, but are themselves + not affected. When deploying programs, the original aspects must be included + on the runtime classpath. + + + In AspectJ tools, the inpath is where to find binary + input - aspects and classes that weave and may be woven. + Like the classpath, it can include archives and class directories. + Like the aspectpath, it can include aspects that affect other classes + and aspects. + However, unlike the aspectpath, an aspect on the inpath may itself be + affected by aspects, as if the source were all compiled together. + When deploying aspects that were put on the inpath, only the woven output + should be on the runtime classpath. + + + Although types in the inpath and the aspectpath need to be resolved by + the AspectJ tools, you usually do not need to place them on the classpath + because this is done automatically by the compiler/weaver. But when using + the WeavingURLClassLoader, your code must explicitly add the aspects + to the classpath so they can be resolved (as you'll see in the sample + code and the aj.bat script). + + The most common mistake is failing to add + aspectjrt.jar to the classpath. Also, when + weaving with binary aspects, users forget to deploy the aspect itself + along with any classes it requires. A more subtle mistake is putting a + binary aspect (BA) on the inpath instead of the aspectpath. In this case + the aspect BA might be affected by an aspect, even itself; this can + cause the program to fail, e.g., when an aspect uses exclusion to + avoid infinite recursion but fails to exclude advice in aspect BA. + + The latter is one of many ways that mistakes in the build process + can affect aspects that are written poorly. Aspects should never + rely on the boundaries of the build specification to narrow the + scope of their crosscutting, since the build can be changed + without notice to the aspect developer. Careful users might even + avoid relying on the implementation scope, to ensure their + AspectJ code will run on other implementations. + + + + \ No newline at end of file -- 2.39.5