update for LTW and compatibility

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;
+  &ltw;
+  &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