| <html><head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>Chapter 6. AspectJ version compatibility</title><link rel="stylesheet" href="aspectj-docs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.44"><link rel="home" href="index.html" title="The AspectJtm Development Environment Guide"><link rel="up" href="index.html" title="The AspectJtm Development Environment Guide"><link rel="previous" href="ltw-agents.html" title="Supported Agents"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. AspectJ version compatibility</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ltw-agents.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="compatibility"></a>Chapter 6. AspectJ version compatibility</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="compatibility.html#versionCompatibility">Version Compatibility</a></dt><dd><dl><dt><a href="compatibility.html#javaCompatibility">Java compatibility</a></dt><dt><a href="compatibility.html#runtimeCompatibility">Runtime library compatibility</a></dt><dt><a href="compatibility.html#binaryCompatibility">Aspect binary compatibility</a></dt><dt><a href="compatibility.html#sourceCompatibility">Aspect source compatibility</a></dt><dt><a href="compatibility.html#upgrading">Problems when upgrading to new AspectJ versions</a></dt></dl></dd></dl></div><div class="sect1"><a name="versionCompatibility"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="versionCompatibility"></a>Version Compatibility</h2></div></div><p>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. </p><div class="sect2"><a name="javaCompatibility"></a><div class="titlepage"><div><h3 class="title"><a name="javaCompatibility"></a>Java compatibility</h3></div></div><p> | |
| 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. | |
| </p><p>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 | |
| <tt>aspectjrt.jar</tt> 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 | |
| <a href="mailto:aspectj-dev@eclipse.org" target="_top">aspectj-dev@eclipse.org</a> | |
| or download the runtime code to modify it for your environment. | |
| </p><p> | |
| 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. | |
| </p></div><div class="sect2"><a name="runtimeCompatibility"></a><div class="titlepage"><div><h3 class="title"><a name="runtimeCompatibility"></a>Runtime library compatibility</h3></div></div><p> When deploying AspectJ programs, include on the classpath the | |
| classes, aspects, and the AspectJ runtime library | |
| (<tt>aspectjrt.jar</tt>). 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. </p><p> 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 <tt>aspectjrt.jar</tt> on the | |
| bootclasspath). Third, you (unintentionally) deploy two versions | |
| of the runtime, and the one loaded by a parent loader is used). </p><p> 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. </p></div><div class="sect2"><a name="binaryCompatibility"></a><div class="titlepage"><div><h3 class="title"><a name="binaryCompatibility"></a>Aspect binary compatibility</h3></div></div><p>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). </p><p>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. </p></div><div class="sect2"><a name="sourceCompatibility"></a><div class="titlepage"><div><h3 class="title"><a name="sourceCompatibility"></a>Aspect source compatibility</h3></div></div><p>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 | |
| <a href="../progguide/semantics.html" target="_top">Semantics appendix to the | |
| Programming Guide</a>.</p></div><div class="sect2"><a name="upgrading"></a><div class="titlepage"><div><h3 class="title"><a name="upgrading"></a>Problems when upgrading to new AspectJ versions</h3></div></div><p> 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. </p><p> Another trap is deploying into the same system, when the | |
| <tt>aspectjrt.jar</tt> has not been changed | |
| accordingly. </p><p> 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. </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ltw-agents.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left">Supported Agents </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr></table></div></body></html> |