[[compatibility]]
= AspectJ version compatibility

[[versionCompatibility]]
== 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.

[[javaCompatibility]]
=== 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.

[[runtimeCompatibility]]
=== 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.

[[binaryCompatibility]]
=== 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.

[[sourceCompatibility]]
=== 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
xref:../progguide/semantics.html[Semantics appendix to the Programming
Guide].

[[upgrading]]
=== 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.