AspectJ version 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.

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.

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.

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.

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.