123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112 |
- [[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.
|