org.aspectj/docs/devGuideDB/compatibility.xml

<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>