diff options
Diffstat (limited to 'docs/adk15ProgGuideDB/varargs.xml')
| -rw-r--r-- | docs/adk15ProgGuideDB/varargs.xml | 143 |
1 files changed, 71 insertions, 72 deletions
diff --git a/docs/adk15ProgGuideDB/varargs.xml b/docs/adk15ProgGuideDB/varargs.xml index 487a8c01d..31dddde80 100644 --- a/docs/adk15ProgGuideDB/varargs.xml +++ b/docs/adk15ProgGuideDB/varargs.xml @@ -1,21 +1,21 @@ <chapter id="varargs" xreflabel="Varargs"> <title>Varargs</title> - + <sect1 id="varargs-inJava5" xreflabel="Varargs in Java 5"> <title>Variable-length Argument Lists in Java 5</title> - + <para> - Java 5 (and hence AspectJ 5) allows you to specify methods that take a + Java 5 (and hence AspectJ 5) allows you to specify methods that take a variable number of arguments of a specified type. This is achieved using - an ellipsis (...) in the method signature as shown: + an ellipsis (...) in the method signature as shown: </para> <programlisting><![CDATA[ - public void foo(int i, String... strings) { - } - ]]></programlisting> - +public void foo(int i, String... strings) { +} +]]></programlisting> + <para> A method or constructor may take at most one variable length argument, and this must always be the last declared argument in the signature. @@ -23,82 +23,81 @@ <sect2 id="calling-methods-and-constructors-with-variable-length-arguments" xreflabel="calling-methods-and-constructors-with-variable-length-arguments"> <title>Calling Methods and Constructors with variable-length arguments</title> - + <para> A <emphasis>varargs</emphasis> method may be called with zero or more arguments - in the variable argument position. For example, given the definition of + in the variable argument position. For example, given the definition of <literal>foo</literal> above, the following calls are all legal: </para> <programlisting><![CDATA[ - foo(5); - foo(5,"One String"); - foo(7,"One String","Two Strings"); - foo(3,"One String","Two Strings","Three Strings"); - ]]></programlisting> +foo(5); +foo(5,"One String"); +foo(7,"One String","Two Strings"); +foo(3,"One String","Two Strings","Three Strings"); +]]></programlisting> - <para>A <emphasis>varargs</emphasis> parameter is treated as an array within the + <para>A <emphasis>varargs</emphasis> parameter is treated as an array within the defining member. So in the body of <literal>foo</literal> we could write for example: </para> <programlisting><![CDATA[ - public void foo(int i, String... strings) { - String[] someStrings = strings; - // rest of method body - } - ]]></programlisting> +public void foo(int i, String... strings) { + String[] someStrings = strings; + // rest of method body +} +]]></programlisting> <para>One consequence of this treatment of a varargs parameter as an array is that you can also call a varargs method with an array:</para> <programlisting><![CDATA[ - foo(7,new String[] {"One String","Two Strings"}); - ]]></programlisting> - +foo(7,new String[] {"One String","Two Strings"}); +]]></programlisting> + </sect2> - + </sect1> <sect1 id="varargs-in-pcds"> <title>Using Variable-length arguments in advice and pointcut expressions</title> - + <para>AspectJ 5 allows variable-length arguments to be used for methods declared within aspects, and for inter-type declared methods and constructors, in accordance with the rules outlined in the previous section.</para> - + <para> AspectJ 5 also allows variable length arguments to be matched by pointcut expressions and bound as formals in advice. </para> - + <sect2 id="matching-signatures-based-on-variable-length-argument-types" xreflabel="matching-signatures-based-on-variable-length-argument-types"> <title>Matching signatures based on variable length argument types</title> - + <para> Recall from the definition of signature patterns given in the chapter on annotations (<xref linkend="signaturePatterns"/>), that <literal>MethodPattern</literal> and <literal>ConstructorPattern</literal> are extended to allow a <literal>varargs</literal> pattern in the last argument position of a method or constructor signature. </para> - - <programlisting><![CDATA[ - FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? | - OptionalParensTypePattern (',' FormalsPattern)* | - TypePattern '...' - - FormalsPatternAfterDotDot := - OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* | - TypePattern '...' - - ]]></programlisting> - + + <programlisting><![CDATA[ +FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? | + OptionalParensTypePattern (',' FormalsPattern)* | + TypePattern '...' + +FormalsPatternAfterDotDot := + OptionalParensTypePattern (',' FormalsPatternAfterDotDot)* | + TypePattern '...' +]]></programlisting> + <para> Method and constructor patterns are used in the <literal>call</literal>, <literal>execution</literal>, <literal>initialization</literal>, <literal>preinitialization</literal>, and <literal>withincode</literal> pointcut designators. Some examples of usage follow: - </para> - + </para> + <variablelist> <varlistentry> @@ -121,7 +120,7 @@ </para> </listitem> </varlistentry> - + <varlistentry> <term>initialization(org.xyz.*.new((Foo || Goo)...))</term> <listitem> @@ -134,30 +133,30 @@ </para> </listitem> </varlistentry> - + </variablelist> - + <para>A variable argument parameter and an array parameter are treated as distinct signature elements, so given the method definitions: </para> <programlisting><![CDATA[ - void foo(String...); - void bar(String[]); - ]]></programlisting> - +void foo(String...); +void bar(String[]); +]]></programlisting> + <para> The pointcut <literal>execution(* *.*(String...))</literal> matches the execution join point - for <literal>foo</literal>, but not <literal>bar</literal>. The pointcut + for <literal>foo</literal>, but not <literal>bar</literal>. The pointcut <literal>execution(* *.*(String[]))</literal> matches the execution join point for <literal>bar</literal> but not <literal>foo</literal>. </para> - + </sect2> - + <sect2 id="exposing-variable-length-arguments-as-context-in-pointcuts-and-advice" xreflabel="exposing-variable-length-arguments-as-context-in-pointcuts-and-advice"> <title>Exposing variable-length arguments as context in pointcuts and advice</title> - + <para> When a varargs parameter is used within the body of a method, it has an array type, as discussed in the introduction to this section. We follow the @@ -166,9 +165,9 @@ </para> <programlisting><![CDATA[ - public void foo(int i, String... strings) { - } - ]]></programlisting> +public void foo(int i, String... strings) { +} +]]></programlisting> <para> The call or execution join points for <literal>foo</literal> will be matched @@ -176,34 +175,34 @@ to use the varargs syntax within an args pointcut designator - so you <emphasis>cannot</emphasis> write <literal>args(int,String...)</literal>. </para> - + <para> Binding of a varargs parameter in an advice statement is straightforward: </para> - + <programlisting><![CDATA[ - before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) { - // varargs String... argument is accessible in advice body through ss - // ... - } - ]]></programlisting> - +before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) { + // varargs String... argument is accessible in advice body through ss + // ... +} +]]></programlisting> + <para>Since you cannot use the varargs syntax in the <literal>args</literal> pointcut designator, you also cannot use the varargs syntax to declare - advice parameters.</para> - - <para>Note: the proposal in this section does not allow you to + advice parameters.</para> + + <para>Note: the proposal in this section does not allow you to distinguish between a join point with a signature (int, String...) - and a join point with a signature (int, String[]) based + and a join point with a signature (int, String[]) based <emphasis>solely</emphasis> on the use of the <literal>args</literal> pointcut designator. If this distinction is required, <literal>args</literal> - can always be coupled with <literal>call</literal> or + can always be coupled with <literal>call</literal> or <literal>execution</literal>.</para> </sect2> - + </sect1> - + </chapter> |