123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125 |
- <chapter id="compatibility" xreflabel="AspectJ version compatibility">
-
- <title>AspectJ version compatibility</title>
-
- <sect1 id="versionCompatibility" xreflabel="AspectJ 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>
-
|