From 9f8fdd6e73ae4995d195cc5637307ee7b5d9b057 Mon Sep 17 00:00:00 2001 From: ehilsdal Date: Tue, 2 Dec 2003 19:31:52 +0000 Subject: [PATCH] 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. --- docs/dist/doc/README-11.html | 4 +- docs/dist/doc/index.html | 5 +- docs/faq/faq.xml | 8 +-- .../{limitations.xml => implementation.xml} | 69 ++++++++++++++++++- docs/progGuideDB/preface.xml | 4 +- docs/progGuideDB/progguide.xml | 4 +- docs/progGuideDB/semantics.xml | 2 +- 7 files changed, 81 insertions(+), 15 deletions(-) rename docs/progGuideDB/{limitations.xml => implementation.xml} (68%) 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 For ajc's 1.1 implementation limitations, see - - Programming Guide Appendix C, "Implementation Limitations". + + Programming Guide Appendix: "Implementation Notes".

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 Language Semantics best describes AspectJ usage, and - Implementation Limitations notes that + Implementation Notes + describes how the current version is limited to code the compiler controls. @@ -307,7 +308,7 @@ As you learn, use the compiler's -Xlint flags to catch some common mistakes. (Understand that the - current implementation + current implementation is limited to code the compiler controls.)

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 { To find out about known issues, see the - - AspectJ Programming Guide Appendix, "Limitations" + + AspectJ Programming Guide Appendix, "Implementation Notes" and the AspectJ bugs in the database at http://bugs.eclipse.org/bugs (using the product AspectJ). 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 - - Programming Guide Appendix C. + + Programming Guide Appendix: Implementation Notes. 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 similarity index 68% rename from docs/progGuideDB/limitations.xml rename to docs/progGuideDB/implementation.xml index 34d1cbd55..314c574f9 100644 --- a/docs/progGuideDB/limitations.xml +++ b/docs/progGuideDB/implementation.xml @@ -1,6 +1,9 @@ - + - Implementation Limitations + Implementation Notes + + + Compiler Notes 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. + + + + Bytecode Notes + + 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: + + + + After and around advice cannot apply to handler + join points. + + The control flow of a handler join point cannot be + detected. + + + + 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. + + + The second is that the control flow of a handler join point + is not picked out. For example, the following pointcut + + + + + will capture all join points in the control flow of a call to + void foo(), but it will not + capture those in the control flow of an + IOException handler. It is equivalent to + cflow(call(void foo())). In general, + cflow(handler(Type)) + will pick out no join points. + + + This does not restrict programs from placing before advice on + handlers inside other control flows. This + advice, for example, is perfectly fine: + + + + + + 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. + + + 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. @@ -60,7 +60,7 @@ linkend="quick">quick reference to the language's syntax, a more in depth coverage of its semantics, and a description of the latitude enjoyed by its implementations. + linkend="implementation">implementations. 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 @@ - + ]> @@ -58,6 +58,6 @@ &pitfalls; &quickreference; &semantics; - &limitations; + &implementation; 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 @@ Both perthis and pertarget aspects may be affected by code the AspectJ compiler controls, as - discussed in the appendix. + discussed in the appendix. -- 2.39.5