Bug 159854 "Problem Diagnosis Guide" (first draft)

1 files changed, 66 insertions, 3 deletions

diff --git a/docs/pdGuideDB/ltwdump.xml b/docs/pdGuideDB/ltwdump.xml
index 99240965a..36b1bea3a 100644
--- a/docs/pdGuideDB/ltwdump.xml
+++ b/docs/pdGuideDB/ltwdump.xml
@@ -4,8 +4,71 @@
     <sect1 id="ltwdump-introduction">
         <title>Introduction</title>
         
-        <para> Occasionally problems may be encountered with classes that have been load-time woven. Symptoms will
-        include incorrect program function or a Java exception such as 
-        <literal>java.lang.VerifyError</literal>.</para>
+        <para> Occasionally problems may be encountered with classes that have been load-time woven. 
+        Symptoms will include incorrect program function or a Java exception such as 
+        <literal>java.lang.VerifyError</literal>. Problems can be caused by the way 
+        an aspect or class is built, incompatibilities between AspectJ and 
+        generated byte-code 
+        e.g. <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=117854">CGLIB</ulink>
+        or a bug in the weaver.
+        When these problems occur it may be necessary to attach the class files concerned
+        to a bug report. AspectJ can be configured to dump byte-code to disk using
+        <literal>META-INF/aop.xml</literal>. The <literal>_ajdump</literal> subdirectory the the current
+        working directory is used. </para>
+    
+        <sect2 id="configuration" xreflabel="configuration">
+            <title>Configuration</title>
+            
+            <para> See the 
+				<ulink url="../devguide/ltw-configuration.html#configuring-load-time-weaving-with-aopxml-files">
+				Development Environment Guide</ulink>
+  				for details of how to configure byte-code dumping. </para>
+  		</sect2>
+
+        <sect2 id="examples" xreflabel="examples">
+            <title>Examples</title>
+        
+            <para> By default AspectJ will dump byte-code only after it is woven. This 
+            is because usually the original class file is already available. However 
+            byte-code is sometimes generated by frameworks or downloaded over the network
+            in which case AsepctJ can dump the byte-code before it is woven too. </para>
+            
+            <para> The following <literal>META-INF/aop.xml</literal> will 
+            weave classes in the <literal>com.foo</literal> package (and subpackages) but not
+            CGLIB generated classes in the <literal>com.foo.bar</literal> package (and subpackages). 
+            It will also ensure all
+            woven byte-code is dumped both before and after weaving. </para>
+	        <programlisting><![CDATA[
+	<aspectj>
+		<aspects>
+			<aspect name="ataspectj.EmptyAspect"/>
+		</aspects>
+	    <weaver options="-verbose -debug">
+	        <dump within="com.foo.bar..*" beforeandafter="true"/> 
+    	    <include within="com.foo..*"/>
+        	<exclude within="com.foo.bar..*CGLIB*"/>
+		</weaver>
+	</aspectj>
+			]]></programlisting>
+            
+            <para> You should see messages similar to this: </para>
+
+	        <programlisting><![CDATA[
+[WeavingURLClassLoader] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT
+[WeavingURLClassLoader] info register classloader org.aspectj.weaver.loadtime.WeavingURLClassLoader
+[WeavingURLClassLoader] info using configuration /C:/tempMETA-INF/aop.xml
+[WeavingURLClassLoader] info register aspect ataspectj.EmptyAspect
+[WeavingURLClassLoader] debug not weaving 'com.foo.bar.Test$$EnhancerByCGLIB$$12345'
+[WeavingURLClassLoader] debug weaving 'com.foo.bar.Test'
+			]]></programlisting>
+            
+            <para> On disk you would find the following files: </para>
+
+	        <programlisting><![CDATA[
+	_ajdump/_before/com/foo/bar/Test.class
+	_ajdump/com/foo/bar/Test.class
+			]]></programlisting>
+            
+        </sect2>
     </sect1>
 </chapter>