diff options
Diffstat (limited to 'docs/progGuideDB/quickreference.xml')
| -rw-r--r-- | docs/progGuideDB/quickreference.xml | 1452 |
1 files changed, 769 insertions, 683 deletions
diff --git a/docs/progGuideDB/quickreference.xml b/docs/progGuideDB/quickreference.xml index 4f72dbb7c..6a5d83052 100644 --- a/docs/progGuideDB/quickreference.xml +++ b/docs/progGuideDB/quickreference.xml @@ -1,687 +1,773 @@ -<appendix id="quickreference" xreflabel="AspectJ Quick Reference"> - +<appendix id="quick" xreflabel="AspectJ Quick Reference"> <title>AspectJ Quick Reference</title> - <indexterm><primary>AspectJ</primary><secondary>semantics</secondary> - <tertiary>quick reference</tertiary> - </indexterm> - - <sect1> - <title>Pointcut Designators</title> - - <table frame="all" id="qrpointcutdesignators"> - <title>Pointcut Designators</title> - - <tgroup cols="2" align="left"> - <colspec colname="c1"/> - <colspec colname="c2"/> - <spanspec spanname="hspan" namest="c1" nameend="c2" align="left"/> - - <tbody valign="middle"> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Methods and Constructors</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>call(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Method or constructor call join points when the signature - matches <replaceable>Signature</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>execution(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Method or constructor execution join points when the - signature matches - <replaceable>Signature</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>initialization(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Object initialization join point when the first - constructor called in the type matches - <replaceable>Signature</replaceable> - </entry> - </row> - <row> - <entry> - <literal>preinitialization(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Object pre-initialization join point when the first constructor - called in the type matches <replaceable>Signature</replaceable> - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Exception Handlers</emphasis> - </entry> - </row> - - <row rowsep="1"> - <entry> - <literal>handler(<replaceable>TypePattern</replaceable>)</literal> - </entry> - <entry> - Exception handler execution join points when - try handlers for the throwable types in - <replaceable>TypePattern</replaceable> are executed. - The exception object can be accessed with an - <literal>args</literal> pointcut. - </entry> - </row> - <row> - <entry spanname="hspan"> - <emphasis role="bold">Advice</emphasis> - </entry> - </row> - - <row rowsep="1"> - <entry> - <literal>adviceexecution()</literal> - </entry> - <entry> - All advice execution join points. - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Fields</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>get(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Field reference join points when the field matches - <replaceable>Signature</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>set(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Field assignment join points when the field matches - <replaceable>Signature</replaceable>. The new value - can be accessed with an <literal>args</literal> - pointcut. - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Static Initializers</emphasis> - </entry> - </row> - - <row rowsep="1"> - <entry> - <literal>staticinitialization(<replaceable>TypePattern</replaceable>)</literal> - </entry> - <entry> - Static initializer execution join points for the types in - <replaceable>TypePattern</replaceable>. - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Objects</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>this(<replaceable>Type</replaceable>)</literal> - </entry> - <entry> - Join points when the currently executing object is an - instance of <replaceable>Type</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>target(<replaceable>Type</replaceable>)</literal> - </entry> - <entry> - Join points when the target object is an instance - of <replaceable>Type</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>args(<replaceable>Type</replaceable>, ...)</literal> - </entry> - <entry> - Join points when the argument objects are instances of - the <replaceable>Type</replaceable>s - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Lexical Extents</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>within(<replaceable>TypePattern</replaceable>)</literal> - </entry> - <entry> - Join points when the code executing is defined in the - types in <replaceable>TypePattern</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>withincode(<replaceable>Signature</replaceable>)</literal> - </entry> - <entry> - Join points when the code executing is defined in the - method or constructor with signature - <replaceable>Signature</replaceable> - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Control Flow</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>cflow(<replaceable>Pointcut</replaceable>)</literal> - </entry> - <entry> - Join points in the control flow of the join points - specified by <replaceable>Pointcut</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal> - </entry> - <entry> - Join points in the control flow below the join points - specified by <replaceable>Pointcut</replaceable> - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Conditional</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>if(<replaceable>Expression</replaceable>)</literal> - </entry> - <entry> - Join points when the boolean - <replaceable>Expression</replaceable> evaluates - to <literal>true</literal> - </entry> - </row> - - <row> - <entry spanname="hspan"> - <emphasis role="bold">Combination</emphasis> - </entry> - </row> - - <row> - <entry> - <literal>! <replaceable>Pointcut</replaceable></literal> - </entry> - <entry> - Join points that are not picked out by - <replaceable>Pointcut</replaceable> - </entry> - </row> - - <row> - <entry> - <literal><replaceable>Pointcut0</replaceable> <![CDATA[&&]]> <replaceable>Pointcut1</replaceable></literal> - </entry> - <entry> - Join points that are picked out by both - <replaceable>Pointcut0</replaceable> and - <replaceable>Pointcut1</replaceable> - </entry> - </row> - - <row> - <entry> - <literal><replaceable>Pointcut0</replaceable> || <replaceable>Pointcut1</replaceable></literal> - </entry> - <entry> - Join points that are picked out by either - <replaceable>Pointcut0</replaceable> or - <replaceable>Pointcut1</replaceable> - </entry> - </row> - - <row> - <entry> - <literal>( <replaceable>Pointcut</replaceable> )</literal> - </entry> - <entry> - Join points that are picked out by the parenthesized - <replaceable>Pointcut</replaceable> - </entry> - </row> - - </tbody> - </tgroup> - - </table> - - </sect1> - - <sect1> - <title>Type Patterns</title> - <para> - </para> - - <table frame="all" id="qrtypenamepatterns"> - <title>Type Name Patterns</title> - <tgroup cols="2" colsep="1" rowsep="0"> - <tbody> - <row> - <entry><literal>*</literal> alone</entry> - <entry>all types</entry> - </row> - <row> - <entry><literal>*</literal> in an identifier</entry> - <entry>any sequence of characters, not including "."</entry> - </row> - <row> - <entry><literal>..</literal> in an identifier</entry> - <entry>any sequence of characters starting and ending - with "."</entry> - </row> - </tbody> - </tgroup> - </table> - - <para> - The + wildcard can be appended to a type name pattern to - indicate all subtypes. - </para> - - <para> - Any number of []s can be put on a type name or subtype pattern - to indicate array types. - </para> - - <table frame="all" id="qrtypepatterns"> - <title>Type Patterns</title> - <tgroup cols="2" colsep="1" rowsep="0"> - <tbody> - <row> - <entry><replaceable>TypeNamePattern</replaceable></entry> - <entry>all types in <replaceable>TypeNamePattern</replaceable></entry> - </row> - <row> - <entry><replaceable>SubtypePattern</replaceable></entry> - <entry>all types in <replaceable>SubtypePattern</replaceable>, a - pattern with a +. </entry> - </row> - <row> - <entry><replaceable>ArrayTypePattern</replaceable></entry> - <entry>all types in <replaceable>ArrayTypePattern</replaceable>, - a pattern with one or more []s. </entry> - </row> - <row> - <entry><literal>!<replaceable>TypePattern</replaceable></literal></entry> - <entry>all types not in <replaceable>TypePattern</replaceable></entry> - </row> - <row> - <entry><literal><replaceable>TypePattern0</replaceable> - <![CDATA[&&]]> <replaceable>TypePattern1</replaceable></literal></entry> - <entry>all types in both - <replaceable>TypePattern0</replaceable> and <replaceable>TypePattern1</replaceable></entry> - </row> - <row> - <entry><literal><replaceable>TypePattern0</replaceable> || <replaceable>TypePattern1</replaceable></literal></entry> - <entry>all types in either - <replaceable>TypePattern0</replaceable> or <replaceable>TypePattern1</replaceable></entry> - </row> - <row> - <entry><literal>( <replaceable>TypePattern</replaceable> )</literal></entry> - <entry>all types in <replaceable>TypePattern</replaceable></entry> - </row> - </tbody> - </tgroup> - </table> - - </sect1> - - <sect1> - <title>Advice</title> - - <para></para> - <table frame="all" id="qradvice"> - <title>Advice</title> - <tgroup cols="2" colsep="1" rowsep="0"> - <tbody> - - <row> - <entry> - <literal>before(<replaceable>Formals</replaceable>) : </literal> - </entry> - <entry> - Run before the join point. - </entry> - </row> - - - <row> - <entry> - <literal>after(<replaceable>Formals</replaceable>) returning - [ (<replaceable>Formal</replaceable>) ] : </literal> - </entry> - <entry> - Run after the join point if it returns normally. The - optional formal gives access to the returned value. - </entry> - </row> - - <row> - <entry> - <literal>after(<replaceable>Formals</replaceable>) throwing [ - (<replaceable>Formal</replaceable>) ] : </literal> - </entry> - <entry> - Run after the join point if it throws an exception. The - optional formal gives access to the - <literal>Throwable</literal> exception value. - </entry> - </row> - - <row> - <entry> - <literal>after(<replaceable>Formals</replaceable>) : </literal> - </entry> - <entry> - Run after the join point both when it returns normally and - when it throws an exception. - </entry> - </row> - - <row> - <entry> + + <sect1 id="quick-pointcuts"> + <title>Pointcuts</title> + + <informaltable frame="none"> + <tgroup cols="2" align="left"> + <colspec colname="c1"/> + <colspec colname="c2"/> + + <tbody valign="top"> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Methods and Constructors</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>call(<replaceable>Signature</replaceable>)</literal> + </entry> + + <entry> + every call to any method or constructor matching + <replaceable>Signature</replaceable> at the call site + </entry> + </row> + + <row> + <entry> + <literal>execution(<replaceable>Signature</replaceable>)</literal> + </entry> + + <entry> + every execution of any method or constructor matching + <replaceable>Signature</replaceable> + </entry> + </row> + + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Fields</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>get(<replaceable>Signature</replaceable>)</literal> + </entry> + <entry> + every reference to any field matching <replaceable>Signature</replaceable> + </entry> + </row> + + <row> + <entry> + <literal>set(<replaceable>Signature</replaceable>)</literal> + </entry> + <entry> + every assignment to any field matching + <replaceable>Signature</replaceable>. The assigned value can + be exposed with an <literal>args</literal> pointcut + </entry> + </row> + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Exception Handlers</emphasis> + </entry> + </row> + + <row rowsep="1"> + <entry> + <literal>handler(<replaceable>TypePattern</replaceable>)</literal> + </entry> + <entry> + every exception handler for any <literal>Throwable</literal> + type in <replaceable>TypePattern</replaceable>. The exception + value can be exposed with an <literal>args</literal> pointcut + </entry> + </row> + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Advice</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>adviceexecution()</literal> + </entry> + <entry> + every execution of any piece of advice + </entry> + </row> + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Initialization</emphasis> + </entry> + </row> + + <row rowsep="1"> + <entry> + <literal>staticinitialization(<replaceable>TypePattern</replaceable>)</literal> + </entry> + <entry> + every execution of a static initializer for any type in + <replaceable>TypePattern</replaceable> + </entry> + </row> + + <row> + <entry> + <literal>initialization(<replaceable>Signature</replaceable>)</literal> + </entry> + <entry> + every initialization of an object when the first constructor + called in the type matches + <replaceable>Signature</replaceable>, encompassing the return + from the super constructor call to the return of the + first-called constructor + </entry> + </row> + <row> + <entry> + <literal>preinitialization(<replaceable>Signature</replaceable>)</literal> + </entry> + <entry> + every pre-initialization of an object when the first + constructor called in the type matches + <replaceable>Signature</replaceable>, encompassing the entry + of the first-called constructor to the call to the super + constructor + </entry> + </row> + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Lexical</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>within(<replaceable>TypePattern</replaceable>)</literal> + </entry> + <entry> + every join point from code defined in a type in + <replaceable>TypePattern</replaceable> + </entry> + </row> + + <row> + <entry> + <literal>withincode(<replaceable>Signature</replaceable>)</literal> + </entry> + <entry> + every join point from code defined in a method or constructor + matching <replaceable>Signature</replaceable> + </entry> + </row> + </tbody> + </tgroup> + + <tgroup cols="2" align="left"> + <colspec colname="c1"/> + <colspec colname="c2"/> + <tbody valign="top"> + <row> + <entry namest="c1" nameend="c2" > + <emphasis role="bold">Instanceof checks and context exposure</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>this(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal> + </entry> + <entry> + every join point when the currently executing object is an + instance of <replaceable>Type</replaceable> or + <replaceable>Id</replaceable>'s type + </entry> + </row> + + <row> + <entry> + <literal>target(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal> + </entry> + <entry> + every join point when the target executing object is an + instance of <replaceable>Type</replaceable> or + <replaceable>Id</replaceable>'s type + </entry> + </row> + + <row> + <entry> + <literal>args(<replaceable>Type</replaceable> or + <replaceable>Id</replaceable>, ...)</literal> + </entry> + <entry> + every join point when the arguments are instances of + <replaceable>Type</replaceable>s or the types of the + <replaceable>Id</replaceable>s + </entry> + </row> + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Control Flow</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>cflow(<replaceable>Pointcut</replaceable>)</literal> + </entry> + <entry> + every join point in the control flow of each join point + <replaceable>P</replaceable> picked out by + <replaceable>Pointcut</replaceable>, including + <replaceable>P</replaceable> itself + </entry> + </row> + + <row> + <entry> + <literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal> + </entry> + <entry> + every join point below the control flow of each join point + <replaceable>P</replaceable> picked out by + <replaceable>Pointcut</replaceable>; does not include + <replaceable>P</replaceable> itself + </entry> + </row> + + <!-- ===== --> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Conditional</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>if(<replaceable>Expression</replaceable>)</literal> + </entry> + <entry> + every join point when the boolean + <replaceable>Expression</replaceable> is + <literal>true</literal> + </entry> + </row> + </tbody> + </tgroup> + + <tgroup cols="2" align="left"> + <colspec colname="c1"/> + <colspec colname="c2"/> + + <tbody valign="top"> + <row> + <entry namest="c1" nameend="c2"> + <emphasis role="bold">Combination</emphasis> + </entry> + </row> + + <row> + <entry> + <literal>! <replaceable>Pointcut</replaceable></literal> + </entry> + <entry> + every join point not picked out by + <replaceable>Pointcut</replaceable> + </entry> + </row> + + <row> + <entry> + <literal><replaceable>Pointcut0</replaceable> <![CDATA[&&]]> <replaceable>Pointcut1</replaceable></literal> + </entry> + <entry> + each join point picked out by both + <replaceable>Pointcut0</replaceable> and + <replaceable>Pointcut1</replaceable> + </entry> + </row> + + <row> + <entry> + <literal><replaceable>Pointcut0</replaceable> || <replaceable>Pointcut1</replaceable></literal> + </entry> + <entry> + each join point picked out by either + <replaceable>Pointcut0</replaceable> or + <replaceable>Pointcut1</replaceable> + </entry> + </row> + + <row> + <entry> + <literal>( <replaceable>Pointcut</replaceable> )</literal> + </entry> + <entry> + each join point picked out by + <replaceable>Pointcut</replaceable> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + +<!-- ============================== --> + + <sect1 id="quick-typePatterns"> + <title>Type Patterns</title> + + <para> + A type pattern is one of + </para> + + <informaltable frame="none"> + <tgroup cols="2" > + <tbody valign="top"> + <row> + <entry><replaceable>TypeNamePattern</replaceable></entry> + <entry>all types in <replaceable>TypeNamePattern</replaceable></entry> + </row> + <row> + <entry><replaceable>SubtypePattern</replaceable></entry> + <entry>all types in <replaceable>SubtypePattern</replaceable>, a + pattern with a +. </entry> + </row> + <row> + <entry><replaceable>ArrayTypePattern</replaceable></entry> + <entry>all types in <replaceable>ArrayTypePattern</replaceable>, + a pattern with one or more []s. </entry> + </row> + <row> + <entry><literal>!<replaceable>TypePattern</replaceable></literal></entry> + <entry>all types not in <replaceable>TypePattern</replaceable></entry> + </row> + <row> + <entry><literal><replaceable>TypePattern0</replaceable> + <![CDATA[&&]]> <replaceable>TypePattern1</replaceable></literal></entry> + <entry>all types in both + <replaceable>TypePattern0</replaceable> and <replaceable>TypePattern1</replaceable></entry> + </row> + <row> + <entry><literal><replaceable>TypePattern0</replaceable> || <replaceable>TypePattern1</replaceable></literal></entry> + <entry>all types in either + <replaceable>TypePattern0</replaceable> or <replaceable>TypePattern1</replaceable></entry> + </row> + <row> + <entry><literal>( <replaceable>TypePattern</replaceable> )</literal></entry> + <entry>all types in <replaceable>TypePattern</replaceable></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + where <replaceable>TypeNamePattern</replaceable> can either be a + plain type name, the wildcard <literal>*</literal> (indicating all + types), or an identifier with embedded <literal>*</literal> and + <literal>..</literal> wildcards. + </para> + + <para> + An embedded <literal>*</literal> in an identifier matches any + sequence of characters, but does not match the package (or + inner-type) separator ".". + </para> + + <para> + An embedded <literal>..</literal> in an identifier matches any + sequence of characters that starts and ends with the package (or + inner-type) separator ".". + </para> + </sect1> + +<!-- ============================== --> + + <sect1 id="quick-advice"> + <title>Advice</title> + + <para> + Each piece of advice is of the form + + <blockquote> + <literal>[ strictfp ] <replaceable>AdviceSpec</replaceable> + [ throws <replaceable>TypeList</replaceable> ] : + <replaceable>Pointcut</replaceable> { + <replaceable>Body</replaceable> } </literal> + </blockquote> + + where <replaceable>AdviceSpec</replaceable> is one of + </para> + + <variablelist> + <varlistentry> + <term> + <literal>before( <replaceable>Formals</replaceable> ) </literal> + </term> + <listitem> + runs before each join point + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>after( <replaceable>Formals</replaceable> ) returning + [ ( <replaceable>Formal</replaceable> ) ] </literal> + </term> + <listitem> + runs after each join point that returns normally. The + optional formal gives access to the returned value + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>after( <replaceable>Formals</replaceable> ) throwing [ + ( <replaceable>Formal</replaceable> ) ] </literal> + </term> + <listitem> + runs after each join point that throws a + <literal>Throwable</literal>. If the optional formal is + present, runs only after each join point that throws a + <literal>Throwable</literal> of the type of + <replaceable>Formal</replaceable>, and + <replaceable>Formal</replaceable> gives access to the + <literal>Throwable</literal> exception value + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>after( <replaceable>Formals</replaceable> ) </literal> + </term> + <listitem> + runs after each join point regardless of whether it returns + normally or throws a <literal>Throwable</literal> + </listitem> + </varlistentry> + + <varlistentry> + <term> <literal><replaceable>Type</replaceable> - around(<replaceable>Formals</replaceable>) [ throws - <replaceable>TypeList</replaceable> ] :</literal> - </entry> - <entry> - Run instead of the join point. The join point can be - executed by calling <literal>proceed</literal>. - </entry> - </row> - - </tbody> - </tgroup> - </table> - </sect1> - - <sect1> - <title>Inter-type declarations</title> - <para> - </para> - - <table frame="all" id="qrintroduction"> - <title>Inter-type declarations</title> - - <tgroup cols="2" colsep="1" rowsep="0"> - - <tbody> - - <row> - <entry> - <replaceable>Modifiers ReturnType OnType . Id(Formals) { Body }</replaceable> - </entry> - <entry> - Defines a method on <replaceable>OnType</replaceable>. - </entry> - </row> - - <row> - <entry> - <literal>abstract <replaceable>Modifiers ReturnType OnType . Id(Formals)</replaceable>;</literal> - </entry> - <entry> - Defines an abstract method on <replaceable>OnType</replaceable>. - </entry> - </row> - - <row> - <entry> - <literal><replaceable>Modifiers OnType</replaceable>.new<replaceable>(Formals) { Body }</replaceable></literal> - </entry> - <entry> - Defines a a constructor on <replaceable>OnType</replaceable>. - </entry> - </row> - - <row> - <entry> - <replaceable>Modifiers Type OnType.Id [ = Expression ];</replaceable> - </entry> - <entry> - Defines a field on <replaceable>OnType</replaceable>. - </entry> - </row> - </tbody> - </tgroup> - </table> - - </sect1> - - <sect1> - <title>Other declarations</title> - <para> - </para> - - <table frame="all" id="qrotherdeclarations"> - <title>Other declarations</title> - - <tgroup cols="2" colsep="1" rowsep="0"> - - <tbody> - - <row> - <entry> - <literal>declare parents: <replaceable>TypePattern</replaceable> extends <replaceable>TypeList</replaceable>;</literal> - </entry> - <entry> - Declares that the types in <replaceable>TypePattern</replaceable> extend the types of <replaceable>TypeList</replaceable>. - </entry> - </row> - - <row> - <entry> - <literal>declare parents: <replaceable>TypePattern</replaceable> implements <replaceable>TypeList</replaceable>;</literal> - </entry> - <entry> - Declares that the types in <replaceable>TypePattern</replaceable> implement the types of <replaceable>TypeList</replaceable>. - </entry> - </row> - - <row> - <entry> - <literal>declare warning: <replaceable>Pointcut</replaceable>: <replaceable>String</replaceable>;</literal> - </entry> - <entry> - Declares that if any of the join points in - <replaceable>Pointcut</replaceable> possibly exist in - the program, the compiler should emit a warning of - <replaceable>String</replaceable>. - </entry> - </row> - - <row> - <entry> - <literal>declare error: <replaceable>Pointcut</replaceable>: <replaceable>String</replaceable>;</literal> - </entry> - <entry> - Declares that if any of the join points in - <replaceable>Pointcut</replaceable> possibly exist in - the program, the compiler should emit an error of - <replaceable>String</replaceable>. - </entry> - </row> - - <row> - <entry> - <literal>declare soft: - <replaceable>TypePattern</replaceable>: - <replaceable>Pointcut</replaceable>; </literal> - </entry> - <entry> - Declares that any exception of a type in - <replaceable>TypePattern</replaceable> that gets - thrown at any join point picked out by - <replaceable>Pointcut</replaceable> will be wrapped in - <literal>org.aspectj.lang.SoftException</literal>. - </entry> - </row> - <row> - <entry> - <literal>declare precedence: - <replaceable>TypePatternList</replaceable> ; </literal> - </entry> - <entry> - Declares that at any join point where multiple pieces of advice - apply, the advice precedence at that join point is in - <replaceable>TypePatternList</replaceable> order. - </entry> - </row> - - </tbody> - </tgroup> - </table> - - </sect1> - - <sect1> - <title>Aspect Associations</title> - <para> - </para> - - <table frame="all" id="qrassociations"> - <title>Associations</title> - <tgroup cols="3" align="left" colsep="1" rowsep="1"> - <thead> - <row> - <entry>modifier</entry> - <entry>Description</entry> - <entry>Accessor</entry> - </row> - </thead> - - <tbody> - - <row> - <entry> - [ <literal>issingleton</literal> ] - </entry> - <entry> - One instance of the aspect is made. This is - the default. - </entry> - <entry> - <literal>aspectOf()</literal> at all join points - </entry> - </row> - - <row> - <entry> - <literal>perthis(<replaceable>Pointcut</replaceable>)</literal> - </entry> - <entry> - An instance is associated with each object that is the - currently executing object at any join point in - <replaceable>Pointcut</replaceable>. - </entry> - <entry> - <literal>aspectOf(Object)</literal> at all join points</entry> - </row> - - <row> - <entry> - <literal>pertarget(<replaceable>Pointcut</replaceable>)</literal> - </entry> - <entry> - An instance is associated with each object that is the - target object at any join point in - <replaceable>Pointcut</replaceable>. - </entry> - <entry> - <literal>aspectOf(Object)</literal> at all join points</entry> - </row> - - <row> - <entry> - <literal>percflow(<replaceable>Pointcut</replaceable>)</literal> - </entry> - <entry> - The aspect is defined for each entrance to the control flow of - the join points defined by <replaceable>Pointcut</replaceable>. </entry> - <entry> - <literal>aspectOf()</literal> at join points in - <literal>cflow(<replaceable>Pointcut</replaceable>)</literal> - </entry> - </row> - - <row> - <entry> - <literal>percflowbelow(<replaceable>Pointcut</replaceable>)</literal> - </entry> - <entry> - The aspect is defined for each entrance to the control flow - below the join points defined by <replaceable>Pointcut</replaceable>. - </entry> - <entry> - <literal>aspectOf()</literal> at join points in - <literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal> - </entry> - </row> - </tbody> - - </tgroup> - </table> - </sect1> + around( <replaceable>Formals</replaceable> ) </literal> + </term> + <listitem> + runs in place of each join point. The join point can be + executed by calling <literal>proceed</literal>, which takes + the same number and types of arguments as the around advice. + </listitem> + </varlistentry> + </variablelist> + + <para> + Three special variables are available inside of advice bodies: + </para> + + <variablelist> + <varlistentry> + <term> + <literal>thisJoinPoint</literal> + </term> + <listitem> + an object of type <ulink + url="../api/org/aspectj/lang/JoinPoint.html"><literal>org.aspectj.lang.JoinPoint</literal></ulink> + representing the join point at which the advice is executing. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>thisJoinPointStaticPart</literal> + </term> + <listitem> + equivalent to <literal>thisJoinPoint.getStaticPart()</literal>, + but may use fewer runtime resources. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal>thisEnclosingJoinPointStaticPart</literal> + </term> + <listitem> + the static part of the dynamically enclosing join point. + </listitem> + </varlistentry> + </variablelist> + </sect1> + +<!-- ============================== --> + + <sect1 id="quick-interType"> + <title>Inter-type member declarations</title> + + <para> + Each inter-type member is one of + </para> + + <variablelist> + <varlistentry> + <term> + <literal> + <replaceable>Modifiers ReturnType OnType . Id</replaceable> + ( <replaceable>Formals</replaceable> ) + [ throws <replaceable>TypeList</replaceable> ] + { <replaceable>Body</replaceable> } + </literal> + </term> + <listitem> + a method on <replaceable>OnType</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + abstract <replaceable>Modifiers ReturnType OnType . Id</replaceable> + ( <replaceable>Formals</replaceable> ) + [ throws <replaceable>TypeList</replaceable> ] ; + </literal> + </term> + <listitem> + an abstract method on <replaceable>OnType</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + <replaceable>Modifiers OnType . </replaceable> new + ( <replaceable>Formals</replaceable> ) + [ throws <replaceable>TypeList</replaceable> ] + { <replaceable>Body</replaceable> } + </literal> + </term> + <listitem> + a constructor on <replaceable>OnType</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + <replaceable>Modifiers Type OnType . Id </replaceable> + [ = <replaceable>Expression</replaceable> ] ; + </literal> + </term> + <listitem> + a field on <replaceable>OnType</replaceable>. + </listitem> + </varlistentry> + </variablelist> + </sect1> + +<!-- ============================== --> + + <sect1 id="quick-other"> + <title>Other declarations</title> + + <variablelist> + <varlistentry> + <term> + <literal> + declare parents : + <replaceable>TypePattern</replaceable> extends + <replaceable>Type</replaceable> ; + </literal> + </term> + <listitem> + the types in <replaceable>TypePattern</replaceable> extend + <replaceable>Type</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + declare parents : <replaceable>TypePattern</replaceable> + implements <replaceable>TypeList</replaceable> ; + </literal> + </term> + <listitem> + the types in <replaceable>TypePattern</replaceable> + implement the types in <replaceable>TypeList</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + declare warning : <replaceable>Pointcut</replaceable> : + <replaceable>String</replaceable> ; + </literal> + </term> + <listitem> + if any of the join points in <replaceable>Pointcut</replaceable> + possibly exist in the program, the compiler emits the warning + <replaceable>String</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + declare error : <replaceable>Pointcut</replaceable> : + <replaceable>String</replaceable> ; + </literal> + </term> + <listitem> + if any of the join points in <replaceable>Pointcut</replaceable> + could possibly exist in the program, the compiler emits the + error <replaceable>String</replaceable>. + </listitem> + </varlistentry> + + <varlistentry> + <term> + <literal> + declare soft : + <replaceable>Type</replaceable> : + <replaceable>Pointcut</replaceable> ; + </literal> + </term> + <listitem> + any <replaceable>Type</replaceable> exception + that gets thrown at any join point picked out by + <replaceable>Pointcut</replaceable> is wrapped in <ulink + url="../api/org/aspectj/lang/SoftException.html"><literal>org.aspectj.lang.SoftException</literal></ulink>. + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal> + declare precedence : + <replaceable>TypePatternList</replaceable> ; + </literal> + </term> + <listitem> + at any join point where multiple pieces of advice + apply, the advice precedence at that join point is in + <replaceable>TypePatternList</replaceable> order. + </listitem> + </varlistentry> + </variablelist> + </sect1> + +<!-- ============================== --> + + <sect1 id="quick-aspectAssociations"> + <title>Aspects</title> + + <para> + Each aspect is of the form + + <blockquote> + <literal> + [ privileged ] <replaceable>Modifiers</replaceable> + aspect <replaceable>Id</replaceable> + [ extends <replaceable>Type</replaceable> ] + [ implements <replaceable>TypeList</replaceable> ] + [ <replaceable>PerClause</replaceable> ] + { <replaceable>Body</replaceable> } + </literal> + </blockquote> + where <replaceable>PerClause</replaceable> defines how the aspect is + instantiated and associated (<literal>issingleton</literal> by + default): + </para> + + <informaltable frame="none"> + <tgroup cols="3" align="left"> + <thead> + <row> + <entry align="left">PerClause</entry> + <entry align="left">Description</entry> + <entry align="left">Accessor</entry> + </row> + </thead> + + <tbody valign="top"> + <row> + <entry> + [ <literal>issingleton</literal> ] + </entry> + <entry> + One instance of the aspect is made. This is + the default. + </entry> + <entry> + <literal>aspectOf()</literal> at all join points + </entry> + </row> + + <row> + <entry> + <literal>perthis(<replaceable>Pointcut</replaceable>)</literal> + </entry> + <entry> + An instance is associated with each object that is the + currently executing object at any join point in + <replaceable>Pointcut</replaceable>. + </entry> + <entry> + <literal>aspectOf(Object)</literal> at all join points + </entry> + </row> + + <row> + <entry> + <literal>pertarget(<replaceable>Pointcut</replaceable>)</literal> + </entry> + <entry> + An instance is associated with each object that is the + target object at any join point in + <replaceable>Pointcut</replaceable>. + </entry> + <entry> + <literal>aspectOf(Object)</literal> at all join points + </entry> + </row> + + <row> + <entry> + <literal>percflow(<replaceable>Pointcut</replaceable>)</literal> + </entry> + <entry> + The aspect is defined for each entrance to the control flow of + the join points defined by <replaceable>Pointcut</replaceable>. </entry> + <entry> + <literal>aspectOf()</literal> at join points in + <literal>cflow(<replaceable>Pointcut</replaceable>)</literal> + </entry> + </row> + + <row> + <entry> + <literal>percflowbelow(<replaceable>Pointcut</replaceable>)</literal> + </entry> + <entry> + The aspect is defined for each entrance to the control flow + below the join points defined by <replaceable>Pointcut</replaceable>. + </entry> + <entry> + <literal>aspectOf()</literal> at join points in + <literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + </appendix> -<!-- Local variables: --> -<!-- fill-column: 79 --> -<!-- sgml-local-ecat-files: progguide.ced --> -<!-- sgml-parent-document:("progguide.sgml" "book" "appendix") --> -<!-- End: --> |