--- /dev/null
+<refentry id="aj-ref" xreflabel="The aj Command-line Reference">
+
+ <refnamediv>
+ <refname>aj</refname>
+ <refpurpose>command-line launcher for basic load-time weaving</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>aj</command>
+ <arg><replaceable>Options</replaceable></arg>
+ <group>
+ <arg><replaceable>arg...</replaceable></arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1 id="aj" xreflabel="aj">
+ <title>Description</title>
+
+ <para>The
+ <command>aj</command> command runs Java programs in Java 1.4 or
+ later by setting up
+ <literal>WeavingURLClassLoader</literal> as the system class
+ loader, to do load-time bytecode weaving. </para>
+
+ <para> The arguments are the same as those used to launch the Java program.
+ Users should define the environment variables
+ <literal>CLASSPATH</literal> and
+ <literal>ASPECTPATH</literal>. </para>
+
+ <para>For more information and alternatives for load-time weaving,
+ see <xref linkend="ltw"/>.
+ </para>
+
+ <refsect2>
+ <title>Examples</title>
+
+ <example id="simpleexample">
+ <title>A simple example</title>
+
+ <para>Use ajc to build a library, then weave at load time</para>
+
+ <programlisting><![CDATA[
+ REM compile library
+ ${ASPECTJ_HOME}\bin\ajc.bat -outjar lib\aspects.jar @aspects.lst
+
+ REM run, weaving into application at load-time set
+ ASPECTPATH=lib\aspects.jar set CLASSPATH=app\app.jar
+ ${ASPECTJ_HOME}\bin\aj.bat com.company.app.Main "Hello, World!"
+]]> </programlisting>
+
+ </example>
+ </refsect2>
+ </refsect1>
+</refentry>
--- /dev/null
+<chapter id="compatibility" xreflabel="AspectJ version compatibility">
+
+ <title>AspectJ version compatibility</title>
+
+<sect1 id="versionCompatibility" xreflabel="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>
+
+
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
"../../lib/docbook/docbook-dtd/docbookx.dtd"
[
+<!ENTITY aj SYSTEM "aj.xml">
<!ENTITY ajc SYSTEM "ajc.xml">
-<!ENTITY ajdb SYSTEM "ajdb.xml">
<!ENTITY ajdoc SYSTEM "ajdoc.xml">
<!ENTITY antsupport SYSTEM "antsupport.xml">
<!ENTITY ajbrowser SYSTEM "ajbrowser.xml">
-<!ENTITY ajdejbuilder SYSTEM "ajdejbuilder.xml">
-<!ENTITY ajdeforte SYSTEM "ajdeforte.xml">
-<!ENTITY aspectj-mode SYSTEM "aspectj-mode.xml">
-<!ENTITY ajdee SYSTEM "ajdee.xml">
+<!ENTITY compatibility SYSTEM "compatibility.xml">
+<!ENTITY ltw SYSTEM "ltw.xml">
+<!ENTITY tools-intro SYSTEM "tools-intro.xml">
+<!ENTITY weaving SYSTEM "weaving.xml">
]>
<book>
<abstract>
<para>
- This guide describes the tools in the AspectJ 1.2 development
- environment. See also
+ This guide describes how to build and deploy AspectJ programs
+ using the AspectJ tools and facilities. See also
<ulink url="../progguide/index.html">The
AspectJ Programming Guide</ulink>,
the documentation available with the AspectJ support available for
- various integrated development environments (e.g., Eclipse, Emacs,
- JBuilder, and NetBeans),
+ various integrated development environments (e.g.,
+ <ulink url="http://eclipse.org/AJDT">Eclipse AJDT</ulink>),
and the most-recent documentation available from
the AspectJ project page, at
<ulink url="http://eclipse.org/aspectj">
http://eclipse.org/aspectj</ulink>.
- <!--
- <itemizedlist>
- <listitem><para><ulink url="../progguide/index.html">the
- AspectJ Programming Guide</ulink></para>
- </listitem>
- <listitem><para>the
- documentation available with the AspectJ support available for
- various integrated development environments (e.g., Eclipse, Emacs,
- JBuilder, and NetBeans)</para>
- </listitem>
- <listitem><para>the most-recent documentation available from
- the AspectJ project page, at
- <ulink url="http://eclipse.org/aspectj">
- http://eclipse.org/aspectj</ulink>.</para>
- </listitem>
- </itemizedlist>
- -->
</para>
</abstract>
</bookinfo>
+ &tools-intro;
- <reference>
- <referenceinfo>
- <abstract>
- <title>Summary of command-line tools</title><para/>
- </abstract>
- </referenceinfo>
- <title>Command-line tools</title>
- &ajc;
- &ajdoc;
- </reference>
+<chapter id="command-line-tools" xreflabel="AspectJ command-line tools">
+ <title>AspectJ command-line tools</title>
+
+ <sect1 id="ajc-ref-top">
+ <title><literal>ajc</literal>, the AspectJ compiler/weaver</title>
+ &ajc;
+ </sect1>
+ <sect1 id="ajdoc-ref-top">
+ <title><literal>ajdoc</literal>, the AspectJ documentation tool</title>
+ <para><literal>ajdoc</literal> produces JavaDoc-style documentation
+ including crosscutting information.</para>
+ &ajdoc;
+ </sect1>
+ <sect1 id="aj-ref-top">
+ <title><literal>ajdoc</literal>, the AspectJ load-time weaving script</title>
+ <para><literal>aj</literal> launches programs,
+ configuring basic load-time weaving.</para>
+ &aj;
+ </sect1>
+</chapter>
&ajbrowser;
&antsupport;
+ <w;
+ &compatibility;
</book>
-<!--
-Local Variables:
-compile-command:"ant -quiet dev-html"
-fill-column: 79
-sgml-indent-step: 3
-sgml-local-ecat-files:devguide.ced
-sgml-namecase-general: t
-End:
--->
--- /dev/null
+<chapter id="tools-intro"
+ xreflabel="Introduction to the AspectJ tools">
+ <title>Introduction to the AspectJ tools</title>
+<sect1
+ id="eclipse-aspectj"
+ xreflabel="The Eclipse AspectJ implementation">
+ <title>The Eclipse AspectJ implementation</title>
+ <para>The <ulink url="../progguide/index.html">AspectJ Programming Guide</ulink>
+ describes the AspectJ language. This guide describes the AspectJ
+ tools produced by the AspectJ
+ team on
+ <ulink url="http://eclipse.org/aspectj">http://eclipse.org/aspectj</ulink>.
+ The AspectJ tools include
+ - ajc, the compiler/weaver;
+ ajdoc, a documentation tool; ajbrowser, a crosscutting code viewer;
+ Ant support for ajc; and load-time weaving support.
+ These tools are delivered in the library folder of the AspectJ tools
+ installation, mainly in <literal>aspectjtools.jar</literal> (tools) and
+ <literal>aspectjrt.jar</literal> (runtime).
+ This guide does not describe the Eclipse AspectJ development tools
+ (AJDT). That is produced by another team (sharing some members) on
+ <ulink url="http://eclipse.org/aspectj">http://eclipse.org/ajdt</ulink>.
+ AJDT is delivered as an Eclipse plugin, incorporating the classes in
+ the AspectJ tools libraries along with the Eclipse plugin interface
+ classes.
+ </para>
+ <para>
+ Since AspectJ 1.1, the tools have implemented the AspectJ language
+ using bytecode weaving, which combines aspects and classes to produce
+ .class files that run in a Java VM. There are other ways to implement the
+ language (e.g., compiler preprocessor, VM support); the AspectJ team
+ has always tried to distinguish the language and the implementation
+ so other groups could build alternative implementations of AspectJ.
+ To that end,
+
+ <ulink url="../progguide/implementation.html">The AspectJ Programming Guide,
+ Implementation Notes</ulink> describes how the Java bytecode form affects
+ language semantics. VM- or source-based implementations may be free
+ of these limits or impose limits of their own, but most should be
+ fairly close to what's possible in Java bytecode.
+ </para>
+ <para>
+ Please be careful not to confuse any description of
+ weaving or of this implementation of the AspectJ language with
+ the AspectJ language semantics.
+ If you do, you might find yourself writing code that doesn't work as
+ expected when you compile or run it on other systems.
+ More importantly, if you
+ think about aspects in terms of weaving or of inserting or merging
+ code, then you can lose many of the design benefits of thinking
+ about an aspect as a single crosscutting module.
+ When the text below introduces an implementation detail, it will warn if
+ users make mistakes by applying it in lieu of the language semantics.
+ </para>
+</sect1>
+ <!-- graphic for bytecode weaving -->
+<sect1
+ id="bytecode-concepts"
+ xreflabel="Bytecode weaving, incremental compilation, and memory usage">
+ <title>Bytecode weaving, incremental compilation, and memory usage</title>
+ <para>Bytecode weaving takes classes and aspects in .class form
+ and weaves them together to produce binary-compatible .class files that
+ run in any Java VM and implement the AspectJ semantics.
+ This process supports not only the compiler but also IDE's.
+ The compiler, given an aspect in source form, produces a binary
+ aspect and runs the weaver. IDE's can get information about
+ crosscutting in the program by subscribing to information
+ produced by weaver as a side-effect of weaving.
+ </para>
+ <para>Incremental compilation involves recompiling only what is necessary
+ to bring the binary form of a program up-to-date with the source form
+ in the shortest time possible.
+ Incremental weaving supports this by weaving on a per-class basis.
+ (Some implementations of AOP (including AspectJ 1.0) make use
+ of whole-program analysis that can't be done in incremental mode.)
+ Weaving per-class means that if the source for a pure Java class
+ is updated, only that class needs to be produced. However, if
+ some crosscutting specification may have been updated, then all
+ code potentially affected by it may need to be woven. The AspectJ
+ tools are getting better at minimizing this effect, but it is to
+ some degree unavoidable due to the crosscutting semantics.
+ </para>
+ <para>
+ Memory usage can seem higher with AspectJ tools.
+ Some aspects are written to potentially affect many classes, so each
+ class must be checked during the process of weaving. Programmers can
+ minimize this by writing the crosscutting specifications as narrowly
+ as possible while maintaining correctness.
+ (While it may seem like more memory, the proper comparison
+ would with with a Java program that had the same crosscutting,
+ with changes made to each code segment. That would likely require
+ more memory and more time to recompile than the corresponding
+ AspectJ program.)
+ </para>
+<sect2
+ id="classpathInpathAndAspectpath"
+ xreflabel="Classpath, inpath, and aspectpath">
+ <title>Classpath, inpath, and aspectpath</title>
+ <para>AspectJ introduces two new paths for the binary input to the
+ weaver which you'll find referenced in <xref linkend="ajc-ref"/>,
+ <xref linkend="ajbrowser"/>,
+ <xref linkend="antTasks"/>,
+ and <xref linkend="ltw"/>.
+ </para>
+ <para>As in Java, the <literal>classpath</literal> is where the AspectJ
+ tools resolve types specified in the program. When running an AspectJ
+ program, the classpath should contain the classes and aspects along with
+ the AspectJ runtime library, <literal>aspectjrt.jar</literal>.
+ </para>
+ <para>
+ In AspectJ tools, the <literal>aspectpath</literal> is where to find binary
+ aspects. Like the classpath, it can include archives (.jar and .zip files)
+ and directories containing .class files in a package layout (since
+ binary aspects are in .class files). These aspects affect other
+ classes in exactly the same way as source-level aspects, but are themselves
+ not affected. When deploying programs, the original aspects must be included
+ on the runtime classpath.
+ </para>
+ <para>
+ In AspectJ tools, the <literal>inpath</literal> is where to find binary
+ input - aspects and classes that weave and may be woven.
+ Like the classpath, it can include archives and class directories.
+ Like the aspectpath, it can include aspects that affect other classes
+ and aspects.
+ However, unlike the aspectpath, an aspect on the inpath may itself be
+ affected by aspects, as if the source were all compiled together.
+ When deploying aspects that were put on the inpath, only the woven output
+ should be on the runtime classpath.
+ </para>
+ <para>
+ Although types in the inpath and the aspectpath need to be resolved by
+ the AspectJ tools, you usually do not need to place them on the classpath
+ because this is done automatically by the compiler/weaver. But when using
+ the <literal>WeavingURLClassLoader</literal>, your code must explicitly add the aspects
+ to the classpath so they can be resolved (as you'll see in the sample
+ code and the <literal>aj.bat</literal> script).
+ </para>
+ <para>The most common mistake is failing to add
+ <literal>aspectjrt.jar</literal> to the classpath. Also, when
+ weaving with binary aspects, users forget to deploy the aspect itself
+ along with any classes it requires. A more subtle mistake is putting a
+ binary aspect (BA) on the inpath instead of the aspectpath. In this case
+ the aspect BA might be affected by an aspect, even itself; this can
+ cause the program to fail, e.g., when an aspect uses exclusion to
+ avoid infinite recursion but fails to exclude advice in aspect BA.
+ </para>
+ <para>The latter is one of many ways that mistakes in the build process
+ can affect aspects that are written poorly. Aspects should never
+ rely on the boundaries of the build specification to narrow the
+ scope of their crosscutting, since the build can be changed
+ without notice to the aspect developer. Careful users might even
+ avoid relying on the implementation scope, to ensure their
+ AspectJ code will run on other implementations.
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
\ No newline at end of file
projects / aspectj.git / commitdiff