Fix for Bugzilla 37899: Document or address limitations on handler pointcut/joinpoints

 * changed "Implementation Limitations" to "Implementation Notes" inside ProgGuide
 * added section on bytecode limitations, headed by handler issues.

7 files changed, 81 insertions, 15 deletions

diff --git a/docs/dist/doc/README-11.html b/docs/dist/doc/README-11.html
index ff29e5d5b..f1d4f507f 100644
--- a/docs/dist/doc/README-11.html
+++ b/docs/dist/doc/README-11.html
@@ -1532,8 +1532,8 @@ These might be fixed during the 1.1 release cycle; find them using the query
 	       http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&keywords=info</a>
 
 For ajc's 1.1 implementation limitations, see 
-  <a href="progguide/limitations.html">
-   Programming Guide Appendix C, "Implementation Limitations"</a>.
+  <a href="progguide/implementation.html">
+   Programming Guide Appendix: "Implementation Notes"</a>.
   
 </p>
 </body> </html>
diff --git a/docs/dist/doc/index.html b/docs/dist/doc/index.html
index 3eb29ffa5..b157b34fc 100644
--- a/docs/dist/doc/index.html
+++ b/docs/dist/doc/index.html
@@ -83,7 +83,8 @@
      summarizes AspectJ syntax,
      the <a href="progguide/semantics.html">Language Semantics</a>
      best describes AspectJ usage, and 
-     <a href="progguide/limitations.html">Implementation Limitations</a> notes that
+     <a href="progguide/implementation.html">Implementation Notes</a>
+     describes how
      the current version is limited to code the compiler controls.</td>
      </tr>
 
@@ -307,7 +308,7 @@
     As you learn,
     use the compiler's <code>-Xlint</code> flags to catch some common 
     mistakes.  (Understand that the 
-    <a href="progguide/limitations.html">current implementation</a>
+    <a href="progguide/implementation.html">current implementation</a>
     is limited to code the compiler controls.)
 <p>
    To plan how to adopt AspectJ into a project, read the 
diff --git a/docs/faq/faq.xml b/docs/faq/faq.xml
index 3a1a4b351..bdf74142b 100644
--- a/docs/faq/faq.xml
+++ b/docs/faq/faq.xml
@@ -1452,8 +1452,8 @@ aspect PublicErrorLogging {
           </para>
           <para>
           To find out about known issues, see the
-          <ulink url="progguide/limitations.html">
-          AspectJ Programming Guide Appendix, "Limitations"</ulink>
+          <ulink url="progguide/implementation.html">
+          AspectJ Programming Guide Appendix, "Implementation Notes"</ulink>
           and the AspectJ bugs in the database at
           <ulink url="http://bugs.eclipse.org/bugs">http://bugs.eclipse.org/bugs</ulink>
           (using the product <literal>AspectJ</literal>).  Here are direct links to
@@ -3678,8 +3678,8 @@ vmparam -Xmx384m
           a system, so AspectJ program semantics may be limited to code
           the implementation controls.  For our implementation, these 
           limitations are stated in 
-          <ulink url="progguide/limitations.html">
-             Programming Guide Appendix C</ulink>.
+          <ulink url="progguide/implementation.html">
+             Programming Guide Appendix:  Implementation Notes</ulink>.
 		  Aside from understanding the use and limitations of the 
 		  implementation, there is no need to understand the underlying 
 		  technology when writing AspectJ programs.
diff --git a/docs/progGuideDB/limitations.xml b/docs/progGuideDB/implementation.xml
index 34d1cbd55..314c574f9 100644
--- a/docs/progGuideDB/limitations.xml
+++ b/docs/progGuideDB/implementation.xml
@@ -1,6 +1,9 @@
-<appendix id="limitations" xreflabel="Implementation Limitations">
+<appendix id="implementation" xreflabel="Implementation Notes">
 
-  <title>Implementation Limitations</title>
+  <title>Implementation Notes</title>
+
+<sect1>
+  <title>Compiler Notes</title>
 
   <para> 
     The initial implementations of AspectJ have all been
@@ -109,5 +112,67 @@
     be aware of the limitations of the ajc compiler you're using, but
     these limitations should not drive the design of your aspects.
   </para>
+</sect1>
+
+<sect1>
+  <title>Bytecode Notes</title>
+
+  <para>The end of exception handlers cannot reliably be found in Java
+  bytecode.  Instead of removing the handler join point entirely, the
+  current AspectJ compiler restricts what can be done with the handler
+  join point:
+  </para>
+
+  <itemizedlist>
+    <listitem>After and around advice cannot apply to handler
+    join points.</listitem>
+
+    <listitem>The control flow of a handler join point cannot be
+    detected. </listitem>
+  </itemizedlist>
+
+  <para>
+  The first of these is relatively straightforward.  If any piece of
+  after advice (returning, throwing, or "finally") would normally
+  apply to a handler join point, it will not in code output by the
+  current AspectJ compiler.  A compiler warning is generated whenever
+  this is detected to be the case.  Before advice is allowed.
+  </para>
+
+  <para> The second is that the control flow of a handler join point
+  is not picked out.  For example, the following pointcut
+  </para>
+
+<programlisting><![CDATA[
+  cflow(call(void foo()) || handler(java.io.IOException))
+]]></programlisting>
+
+  <para> will capture all join points in the control flow of a call to
+  <literal>void foo()</literal>, but it will <emphasis>not</emphasis>
+  capture those in the control flow of an
+  <literal>IOException</literal> handler.  It is equivalent to
+  <literal>cflow(call(void foo()))</literal>.  In general,
+  <literal>cflow(handler(<replaceable>Type</replaceable>))</literal>
+  will pick out no join points.
+  </para>
+
+  <para> This does not restrict programs from placing before advice on
+  handlers inside <emphasis>other</emphasis> control flows.  This
+  advice, for example, is perfectly fine:
+  </para>
+
+<programlisting><![CDATA[
+  before(): handler(java.io.IOException) && cflow(void parse()) {
+      System.out.println("about to handle an exception while parsing");
+  }
+]]></programlisting>
+
+  <para>
+    A source-code implementation of AspectJ (such as AspectJ 1.0.6) is
+    able to detect the endpoint of a handler join point, and as such
+    will likely have fewer such restrictions.
+  </para>
+
+</sect1>
 
 </appendix>
diff --git a/docs/progGuideDB/preface.xml b/docs/progGuideDB/preface.xml
index 1ad7b382b..5484fe5b3 100644
--- a/docs/progGuideDB/preface.xml
+++ b/docs/progGuideDB/preface.xml
@@ -24,7 +24,7 @@
 
     It includes appendices that give a reference to the syntax of AspectJ,
     a more formal description of AspectJ's semantics, and a description of
-    limitations allowed by AspectJ implementations.
+    notes about the AspectJ implementation.
   </para>
 
   <para>
@@ -60,7 +60,7 @@
     linkend="quick">quick reference</xref> to the language's syntax, a more
     in depth coverage of its <xref linkend="semantics">semantics</xref>,
     and a description of the latitude enjoyed by its <xref
-    linkend="limitations">implementations</xref>.
+    linkend="implementation">implementations</xref>.
   </para>
 
 </preface>
diff --git a/docs/progGuideDB/progguide.xml b/docs/progGuideDB/progguide.xml
index f23ca03b3..433d71585 100644
--- a/docs/progGuideDB/progguide.xml
+++ b/docs/progGuideDB/progguide.xml
@@ -11,7 +11,7 @@
 <!ENTITY pitfalls       SYSTEM "pitfalls.xml">
 <!ENTITY quickreference SYSTEM "quickreference.xml">
 <!ENTITY semantics      SYSTEM "semantics.xml">
-<!ENTITY limitations    SYSTEM "limitations.xml">
+<!ENTITY implementation SYSTEM "implementation.xml">
 ]>
 
 <book>
@@ -58,6 +58,6 @@
   &pitfalls;
   &quickreference;
   &semantics;
-  &limitations;
+  &implementation;
 
 </book>
diff --git a/docs/progGuideDB/semantics.xml b/docs/progGuideDB/semantics.xml
index 7b065f136..2fe8f7444 100644
--- a/docs/progGuideDB/semantics.xml
+++ b/docs/progGuideDB/semantics.xml
@@ -2591,7 +2591,7 @@
 
         <para> Both <literal>perthis</literal> and <literal>pertarget</literal>
         aspects may be affected by code the AspectJ compiler controls, as
-        discussed in the <xref linkend="limitations"/> appendix.  </para>
+        discussed in the <xref linkend="implementation"/> appendix.  </para>
       </sect3>
 
       <sect3>