diff options
| -rw-r--r-- | docs/dist/doc/README-11.html | 4 | ||||
| -rw-r--r-- | docs/dist/doc/index.html | 5 | ||||
| -rw-r--r-- | docs/faq/faq.xml | 8 | ||||
| -rw-r--r-- | docs/progGuideDB/implementation.xml (renamed from docs/progGuideDB/limitations.xml) | 69 | ||||
| -rw-r--r-- | docs/progGuideDB/preface.xml | 4 | ||||
| -rw-r--r-- | docs/progGuideDB/progguide.xml | 4 | ||||
| -rw-r--r-- | docs/progGuideDB/semantics.xml | 2 |
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> |