1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
<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>
|
