Added documentation for

  Bugzilla Bug 29699: call join points in 1.1b2 und 1.1b4
basically documented that the -1.4 flag can change how method
calls get generated in terms of the declaring type of the method.

1 files changed, 48 insertions, 0 deletions

diff --git a/docs/dist/doc/README-11.html b/docs/dist/doc/README-11.html
index 7417550f7..ff29e5d5b 100644
--- a/docs/dist/doc/README-11.html
+++ b/docs/dist/doc/README-11.html
@@ -280,6 +280,13 @@ programs from 1.0 to 1.1.
     clarified. </li>
   </ul>
 
+  <p> Also, it is worth noting that because AspectJ now works on bytecode,
+  it is somewhat sensitive to how different compilers generate
+  bytecode, especially when compiling with and without <a
+  href="#ONE_FOUR_METHOD_SIGNATURES">the -1.4 flag</a>. </p>
+
+  
+
 <!-- ============================== -->
 <hr>
 <h2><a name="tools">Support Tools</a></h2>
@@ -1461,6 +1468,47 @@ call(* *(int)) &amp;&amp; args(i) &amp;&amp; !within(A)
 call(* *(int)) &amp;&amp; args(i) &amp;&amp; !target(StringBuffer)
 </PRE>
 
+<h3><a name="ONE_FOUR_METHOD_SIGNATURES">The -1.4 flag and method signatures</a></h3>
+
+<p> Consider the following aspect
+</p>
+
+<PRE>
+public aspect SwingCalls {
+    
+    pointcut callingAnySwing(): call(* javax.swing..*+.*(..));
+
+    before(): callingAnySwing() {
+        System.out.println("Calling any Swing");
+    }
+}
+</PRE>
+
+<p> And then consider the two statements
+</p>
+
+<PRE>
+  JFrame frame = new JFrame();
+  frame.setTitle("Title");
+</PRE>
+
+<p> According to the Java Language Specification version 2, the call
+to <code>frame.setTitle("Title")</code> should always produce the
+bytecode for a call to <code>javax.swing.JFrame.setTitle</code>.
+However, older compilers (and eclipse when run without the
+<code>-1.4</code> flag) will generate the bytecode for a call to
+<code>java.awt.Frame.setTitle</code> instead since this method is not
+overriden by JFrame.  The AspectJ weaver depends on the correctly
+generated bytecode in order to match patterns like the one you show
+correctly.  </p>
+
+<p> This is a good example of why the pattern <code>call(* *(..)) &&
+target(JFrame)</code> is the recommended style.  In general, OO
+programmers don't want to care about the static type of an object at a
+call site, but only want to know the dynamic instanceof behavior which
+is what the target matching will handle.  </p>
+
+
 <h2><a name="knownLimitations">Known limitations</a></h2>
 
 <p>The AspectJ 1.1.0 release contains a small number of known limitations