diff options
Diffstat (limited to 'docs/devGuideDB/compatibility.xml')
| -rw-r--r-- | docs/devGuideDB/compatibility.xml | 125 |
1 files changed, 125 insertions, 0 deletions
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 @@ +<chapter id="compatibility" xreflabel="AspectJ version compatibility"> + + <title>AspectJ version compatibility</title> + +<sect1 id="versionCompatibility" xreflabel="Version Compatibility"> + <title>Version Compatibility</title> + + <para>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. </para> + <sect2 id="javaCompatibility" xreflabel="Java compatibility"> + <title>Java compatibility</title> + <para> + 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. + </para> + <para>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 + <literal>aspectjrt.jar</literal> 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 + <ulink url="mailto:aspectj-dev@eclipse.org">aspectj-dev@eclipse.org</ulink> + or download the runtime code to modify it for your environment. + </para> + <para> + 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. + </para> + </sect2> + + <sect2 id="runtimeCompatibility" + xreflabel="Runtime library compatibility"> + <title>Runtime library compatibility</title> + + <para> When deploying AspectJ programs, include on the classpath the + classes, aspects, and the AspectJ runtime library + (<literal>aspectjrt.jar</literal>). 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. </para> + <para> 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 <literal>aspectjrt.jar</literal> on the + bootclasspath). Third, you (unintentionally) deploy two versions + of the runtime, and the one loaded by a parent loader is used). </para> + <para> 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. </para> + </sect2> + <sect2 id="binaryCompatibility" + xreflabel="Aspect binary compatibility"> + <title>Aspect binary compatibility</title> + + <para>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). </para> + <para>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. </para> + </sect2> + <sect2 id="sourceCompatibility" + xreflabel="Aspect source compatibility"> + <title>Aspect source compatibility</title> + + <para>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 + <ulink url="../progguide/semantics.html">Semantics appendix to the + Programming Guide</ulink>.</para> + </sect2> + <sect2 id="upgrading" + xreflabel="Problems when upgrading to new AspectJ versions"> + <title>Problems when upgrading to new AspectJ versions</title> + <para> 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. </para> + <para> Another trap is deploying into the same system, when the + <literal>aspectjrt.jar</literal> has not been changed + accordingly. </para> + <para> 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. </para> + </sect2> +</sect1> +</chapter> + + |