diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/devGuideDB/aj.xml | 55 | ||||
| -rw-r--r-- | docs/devGuideDB/compatibility.xml | 125 | ||||
| -rw-r--r-- | docs/devGuideDB/devguide.xml | 77 | ||||
| -rw-r--r-- | docs/devGuideDB/tools-intro.xml | 157 |
4 files changed, 369 insertions, 45 deletions
diff --git a/docs/devGuideDB/aj.xml b/docs/devGuideDB/aj.xml new file mode 100644 index 000000000..f9627eb95 --- /dev/null +++ b/docs/devGuideDB/aj.xml @@ -0,0 +1,55 @@ +<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> diff --git a/docs/devGuideDB/compatibility.xml b/docs/devGuideDB/compatibility.xml new file mode 100644 index 000000000..636fc60cf --- /dev/null +++ b/docs/devGuideDB/compatibility.xml @@ -0,0 +1,125 @@ +<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> + + diff --git a/docs/devGuideDB/devguide.xml b/docs/devGuideDB/devguide.xml index 691567609..9d66bd200 100644 --- a/docs/devGuideDB/devguide.xml +++ b/docs/devGuideDB/devguide.xml @@ -3,15 +3,15 @@ <!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> @@ -34,60 +34,47 @@ <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: ---> diff --git a/docs/devGuideDB/tools-intro.xml b/docs/devGuideDB/tools-intro.xml new file mode 100644 index 000000000..ab29d0c21 --- /dev/null +++ b/docs/devGuideDB/tools-intro.xml @@ -0,0 +1,157 @@ +<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 |