[jboss-cvs] JBossAS SVN: r62310 - in projects/aop/trunk/aop/docs/examples: beforeafter and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Apr 12 18:10:20 EDT 2007
Author: flavia.rainone at jboss.com
Date: 2007-04-12 18:10:19 -0400 (Thu, 12 Apr 2007)
New Revision: 62310
Added:
projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.wiki
projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.wiki
Modified:
projects/aop/trunk/aop/docs/examples/annotated-parameters/Driver.java
projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html
projects/aop/trunk/aop/docs/examples/beforeafter/MutexAspect.java
projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html
projects/aop/trunk/aop/docs/examples/beforeafter/jboss-aop.xml
projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html
projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki
Log:
[JBAOP-44] Review of documents
Modified: projects/aop/trunk/aop/docs/examples/annotated-parameters/Driver.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/annotated-parameters/Driver.java 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/annotated-parameters/Driver.java 2007-04-12 22:10:19 UTC (rev 62310)
@@ -30,7 +30,7 @@
POJO pojo = new POJO("Driver");
System.out.println("\nSetting POJO->field with \"text\" value");
- System.out.println("=======================================");
+ System.out.println("=====================================");
pojo.field = "text";
System.out.println("\nReading POJO->field value");
Modified: projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html 2007-04-12 22:10:19 UTC (rev 62310)
@@ -5,15 +5,16 @@
</p><p>
<h4>Overview</h4>
+
In generated advisor (default) mode, before, after and around advices can receive
annotated parameters. The use of annotations provides maximum flexibility to the
signature of advices, since an advice can receive only the values that are relevant
to its execution. These parameters can be in any order and their type can be the type
that is the most suitable to the advice functionality, according to the joinpoints it
intercepts.
-
</p><p>
<h4>Annotated Parameter Signature</h4>
+
</p><p>
The annotated parameter signature is defined as:
</p><p>
@@ -23,28 +24,27 @@
</p><p>
This signature is available for all kinds of advices in JBoss AOP (when running in
the generated advisor instrumentation mode). Besides this one, JBoss AOP supports the
-default around signature, introduced in the <a href="../aspect/aspect.html">Aspect
-example</a>. The default signature can only be used to write around advices, and is
-supported on all instrumentation modes.
+default around signature, introduced in the <a href="../aspect/aspect.html"">Aspect example</a>.
+The default signature can only be used to write around advices, and is supported on
+all instrumentation modes.
</p><p>
Basicaly, this signature allows an advice to receive zero or more annotated
parameters, in any order, and with any valid type. Regarding the exception types, an
-advice is allowed to declare any exception in its signature. <tt>
-RuntimeException</tt>s are rethrown by JBoss AOP as is. The same goes for exceptions
+advice is allowed to declare any exception in its signature. <tt>RuntimeException</tt>s
+are rethrown by JBoss AOP as is. The same goes for exceptions
that are not runtime, if they are declared in the joinpoint exceptions list (
supposing the joinpoint has an exception list). Otherwise, the exception will be
wrapped in a <tt>RuntimeException</tt>. In all cases, the application would get the
exception as if the joinpoint itself had thrown it.
</p><p>
-A concrete example of this signature has been shown in the
-<a href="../beforeafter/beforeafter.html">before/after</a> example:
+A concrete example of this signature has been shown in the <a href="../beforeafter/beforeafter.html">before/after</a> example:
</p><p>
<pre>
public void beforeAdvice(@JoinPoint Joinpoint joinPoint)
</pre>
</p><p>
As we can see, this advice receives one parameter annotated with
-<tt>@JoinPoint</tt>.
+<tt>@JoinPoint</tt>.
</p><p>
Next, we will see all parameter annotations that can be used by an advice. Notice
that an empty parameter list is also valid, as in the following signatures:
@@ -57,8 +57,9 @@
public void afterNoParameters()
</pre>
</p><p>
-
+</p><p>
<h4>Parameter Annotations</h4>
+
</p><p>
JBoss AOP demands the use of parameter annotations to identify advice parameters.
These parameters can represent several values, like the joinpoint target, a joinpoint
@@ -68,12 +69,12 @@
</p><p>
The type of an annotated parameter can be chosen accordingly to the value it refers
to. For example, suppose you are intercepting a jointpoint with an argument of type
-<tt>ArrayList<String></tt>. Advices that refer to this argument as being of
-type <tt>ArrayList<String></tt>, or <tt>Collection<String></tt> or <tt>
-Object</tt> would all be considered correct. This is useful because you can access
-specific operations and fields of the argument, without performing a cast, and yet you
-can receive a super type like <tt>Object</tt> and refer to arguments of different
-types when your advice is applied to different joinpoints.
+<tt>ArrayList<String></tt>. Advices that refer to this argument as being of type
+<tt>ArrayList<String></tt>, or <tt>Collection<String></tt> or <tt>Object</tt> would all be
+considered correct. This is useful because you can access specific operations and
+fields of the argument, without performing a cast, and yet you can receive a super
+type like <tt>Object</tt> and refer to arguments of different types when your advice is
+applied to different joinpoints.
</p><p>
Notice that, as a convention, we named the advices of this example after the names of
parameter annotations. Besides, all advices names are prefixed with their types names
@@ -81,13 +82,13 @@
to point out that, as all previous examples, the name of advices can be chosen freely
and JBoss AOP won't use these names to identify annotated parameters.
</p><p>
-<h5>@JoinPoint</h5>
+<b>@JoinPoint</b>
</p><p>
This annotation is used on objects that represent a joinpoint. If the advice
is an around advice, the type of this object belongs to the
<a href="../../misc/invocation.html">Invocation class hierarchy</a>. On all other
-advices, joinpoints are represented by types of the <a href="../../misc/joinpoint.html">
-JoinPoint interface hierarchy</a>, as follows:
+advices, joinpoints are represented by types of the
+<a href="../../misc/joinpoint.html">JoinPoint interface hierarchy</a>, as follows:
</p><p>
<pre>
public void beforeJoinPoint(@JoinPoint JoinPointInfo joinPointInfo)
@@ -102,9 +103,9 @@
specific type <tt>ConstructorInfo</tt>, valid only on constructor execution
joinpoints.
To see these and all other advice examples, open up the <tt>Aspect.java</tt> file.
-</p></p>
-<h5>@Target</h5>
</p><p>
+<b>@Target</b>
+</p><p>
This annotation is used on parameters that refer to the joinpoint target. The
joinpoint target is defined according to the joinpoint type. For example, the target
of a method execution is the object whose method is being executed. On a call
@@ -129,7 +130,7 @@
perfectly valid, and useful when an advice intercepts joinpoints with different
target types.
</p><p>
-<h5>@Caller</h5>
+<b>@Caller</b>
</p><p>
This annotation is used on parameters that refer to the caller object, during a call
joinpoint interception. This should be used only on call joinpoints. If the call is
@@ -144,7 +145,7 @@
public void afterCaller(@Caller Object target)
</pre>
</p><p>
-<h5>@Return</h5>
+<b>@Return</b>
</p><p>
Use this annotation only on after advices, to refer to the joinpoint return value:
</p><p>
@@ -154,7 +155,7 @@
public void afterMethodReturn(@Return boolean joinPointReturn)
</pre>
</p><p>
-<h5>@Arg</h5>
+<b>@Arg</b>
</p><p>
This annotation is used to refer to a joinpoint argument. Since a joinpoint can
receive more than one argument, this is the only annotation that can be used on more
@@ -170,7 +171,7 @@
</pre>
</p><p>
When the joinpoint receives multiple arguments, JBoss AOP infers to which
-argument an <tt>@Arg</tt> annotated parameter refers. In this example, both
+argument an <tt>@Arg</tt> annotated parameter refers. In this example, both
<tt>beforeConstructorArg</tt> and <tt>aroundConstructorArg</tt> are applied to
<tt>POJO</tt> constructor, whose unique argument is of type <tt>java.lang.String</tt>.
So, the parameters of these advices will refer to this constructor argument.
@@ -196,13 +197,12 @@
}
</pre>
</p><p>
-Wen intercepting <tt>POJO.someMethod(int)</tt> execution, the parameter of <tt>
-afterArg</tt> will contain the value of the single argument <tt>someMethod</tt>
-received, as it happens with <tt>beforeConstructorArg</tt> and <tt>
-aroundConstructorArg</tt> advices. But, when intercepting <tt>
-POJO.method(long,int,long,String)</tt>, JBoss AOP will automatically associate <tt>
-afterArg</tt> parameter with the parameter at index position <tt>1</tt>, of type <tt>
-int</tt>.
+Wen intercepting <tt>POJO.someMethod(int)</tt> execution, the parameter of <tt>afterArg</tt>
+will contain the value of the single argument <tt>someMethod</tt> received, as it happens
+with <tt>beforeConstructorArg</tt> and <tt>aroundConstructorArg</tt> advices. But, when
+intercepting <tt>POJO.method(long,int,long,String)</tt>, JBoss AOP will automatically
+associate <tt>afterArg</tt> parameter with the parameter at index position <tt>1</tt>, of type
+<tt>int</tt>.
</p><p>
Associating the <tt>int</tt> value is easy, because there is only one joinpoint
argument of that type. The same doesn't apply to the following advice:
@@ -211,22 +211,21 @@
public void beforeMethodArg(@Arg long argument)
</pre>
</p><p>
-Given that <tt>POJO->method(long,int,long,String)</tt> has two arguments of type <tt>
-long</tt>, JBoss AOP will pick the first <tt>long</tt> typed argument. If you want to
-refer to the second <tt>long</tt> typed argument, in position <tt>2</tt>, you can use
-the optional <tt>@Arg.index</tt> element as is shown below:
+Given that <tt>POJO->method(long,int,long,String)</tt> has two arguments of type <tt>long</tt>,
+JBoss AOP will pick the first <tt>long</tt> typed argument. If you want to refer to the
+second <tt>long</tt> typed argument, in position <tt>2</tt>, you can use the optional
+<tt>@Arg.index</tt> element as is shown below:
</p><p>
<pre>
public void beforeMethodArg2(@Arg(index=2) long argument)
</pre>
-This element can be set everytime JBoss AOP does not associate your <tt>@Arg</tt>
+This element can be set everytime JBoss AOP does not associate your <tt>@Arg</tt>
annotated parameter with the joinpoint argument you want to receive.
</p><p>
-<h5>@Arguments</h5>
+<b>@Arguments</b>
</p><p>
-Finally, this annotation is used on advice parameters of type <tt>java.lang.Object[]
-</tt>, that contain the complete list of the joinpoint arguments.
-</p<p>
+Finally, this annotation is used on advice parameters of type <tt>java.lang.Object TODO ARRAY </tt>, that contain the complete list of the joinpoint arguments.
+</p><p>
Look at these examples:
</p><p>
<pre>
@@ -238,11 +237,10 @@
</pre>
</p><p>
Use this annotation when you need a generic advice, that receives all arguments
-without knowing how many arguments there are, or their types. Using <tt>@Arguments
-</tt> instead of a list of <tt>@Arg</tt> annotated parameters is useful when you
-need to change one or more joinpoint argument values. An example is the <tt>
-beforeArgs</tt> advice, that ovewrites two argument values of <tt>
-POJO.method(long,int,long,String)</tt> execution:
+without knowing how many arguments there are, or their types. Using <tt>@Arguments
+</tt> instead of a list of <tt>@Arg</tt> annotated parameters is useful when you need to
+change one or more joinpoint argument values. An example is the <tt>beforeArgs</tt> advice,
+that ovewrites two argument values of <tt>POJO.method(long,int,long,String)</tt> execution:
</p><p>
<pre>
public void beforeArgs(@Args Object[] arguments)
@@ -254,11 +252,11 @@
}
</pre>
</p><p>
-Avoid using <tt>@Arguments</tt> when none of those conditions apply. This
+Avoid using <tt>@Arguments</tt> when none of those conditions apply. This
parameter type can incur in the creation of an array and of wrapper objects (as is
the case of argument 1 above). Besides, you have the extra cost of downcasting
the arguments.
-<h4>Run the example</h4>
+<h4>Run the example</h4>
</p><p>
<b>THIS EXAMPLE REQUIRES JDK 1.5!!</b> To compile and run:
<pre>
@@ -275,59 +273,57 @@
[java] RUNNING new POJO("Driver")
[java] >>> afterJoinPoint: ConstructorInfo Constructor[constructor=public POJO(java.lang.String)]
- [java] Setting POJO->field with "text" value
+ [java] Setting POJO->field with "text" value
[java] =======================================
[java] >>> beforeJoinPoint: FieldInfo Field Write[field=public java.lang.Object POJO.field]
[java] >>> aroundTarget: POJO POJO at 19209ea
[java] >>> aroundArgs: arguments [text]
- [java] Reading POJO->field value
+ [java] Reading POJO->field value
[java] =========================
[java] >>> aroundArgs: arguments null
[java] >>> aroundNoParameters
[java] >>> afterFieldReturn: Object text
[java] >>> afterNoParameters
- [java] Calling POJO->method(int)
+ [java] Calling POJO->method(int)
[java] =========================
[java] >>> aroundArgs: arguments [17]
- [java] RUNNING POJO->method(17)
+ [java] RUNNING POJO->method(17)
[java] >>> afterArg: int 17
[java] >>> afterArgs: arguments [17]
- [java] Calling POJO->method(long, int, long, String)
+ [java] Calling POJO->method(long, int, long, String)
[java] =============================================
[java] >>> beforeMethodArg: long 20L
[java] >>> beforeMethodArg2: long 1000L
[java] >>> beforeArgs changing arguments: from [20, 2, 1000, Driver]
[java] to [20, -48, 1000, overridenString]
[java] >>> aroundArgs: arguments [20, -48, 1000, overridenString]
- [java] RUNNING POJO->method(20L, -48, 1000L, "overridenString")
+ [java] RUNNING POJO->method(20L, -48, 1000L, "overridenString")
[java] >>> afterArg: int -48
[java] >>> afterArgs: arguments [20, -48, 1000, overridenString]
- [java] Calling POJO->someMethod(int)
+ [java] Calling POJO->someMethod(int)
[java] =============================
[java] >>> beforeNoParameters
- [java] RUNNING POJO->someMethod()
+ [java] RUNNING POJO->someMethod()
[java] >>> afterMethodReturn: boolean true
[java] >>> afterArg: int 10
- [java] Calling POJO->callMethod()
+ [java] Calling POJO->callMethod()
[java] ==========================
[java] >>> aroundCaller: Driver null
[java] >>> aroundArgs: arguments []
- [java] RUNNING POJO->callMethod()
+ [java] RUNNING POJO->callMethod()
[java] >>> beforeTarget: Object POJO at 19209ea
[java] >>> beforeCaller: POJO POJO at 19209ea
[java] >>> aroundJoinPoint: CallerInvocation JoinPoint_MByM__N_6287195452448676113POJO_N_1153034853916900765_8 at f99ff5
- [java] RUNNING POJO->calledMethod()
+ [java] RUNNING POJO->calledMethod()
[java] >>> afterTarget: POJO POJO at 19209ea
[java] >>> afterCaller: Object POJO at 19209ea
</pre>
</p><p>
-</p><p>
-</p><p>
</p>
</body>
-</html>
\ No newline at end of file
+</html>
Added: projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.wiki
===================================================================
--- projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.wiki (rev 0)
+++ projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.wiki 2007-04-12 22:10:19 UTC (rev 62310)
@@ -0,0 +1,319 @@
+!!!Annotated Advice Parameters
+
+!Overview
+In generated advisor (default) mode, before, after and around advices can receive
+annotated parameters. The use of annotations provides maximum flexibility to the
+signature of advices, since an advice can receive only the values that are relevant
+to its execution. These parameters can be in any order and their type can be the type
+that is the most suitable to the advice functionality, according to the joinpoints it
+intercepts.
+
+!Annotated Parameter Signature
+
+The annotated parameter signature is defined as:
+
+{{{
+public <return-value> <any-method-name>(@<Annotation> <any type> arg0, @<Annotation> <any type> arg1, ... , @<Annotation> <any type> argN) throws <Exception1>,<Exception2>,...,<ExceptionN>
+}}}
+
+This signature is available for all kinds of advices in JBoss AOP (when running in
+the generated advisor instrumentation mode). Besides this one, JBoss AOP supports the
+default around signature, introduced in the [Aspect example|../aspect/aspect.html"].
+The default signature can only be used to write around advices, and is supported on
+all instrumentation modes.
+
+Basicaly, this signature allows an advice to receive zero or more annotated
+parameters, in any order, and with any valid type. Regarding the exception types, an
+advice is allowed to declare any exception in its signature. {{RuntimeException}}s
+are rethrown by JBoss AOP as is. The same goes for exceptions
+that are not runtime, if they are declared in the joinpoint exceptions list (
+supposing the joinpoint has an exception list). Otherwise, the exception will be
+wrapped in a {{RuntimeException}}. In all cases, the application would get the
+exception as if the joinpoint itself had thrown it.
+
+A concrete example of this signature has been shown in the [before/after|../beforeafter/beforeafter.html] example:
+
+{{{
+public void beforeAdvice(@JoinPoint Joinpoint joinPoint)
+}}}
+
+As we can see, this advice receives one parameter annotated with
+{{@JoinPoint}}.
+
+Next, we will see all parameter annotations that can be used by an advice. Notice
+that an empty parameter list is also valid, as in the following signatures:
+
+{{{
+public void beforeNoParameters()
+
+public Object aroundNoParameters() throws Throwable
+
+public void afterNoParameters()
+}}}
+
+
+!Parameter Annotations
+
+JBoss AOP demands the use of parameter annotations to identify advice parameters.
+These parameters can represent several values, like the joinpoint target, a joinpoint
+argument, or its return value. In this example, we show all parameter annotations
+that can be used by before, after and around advices. These annotations are located
+in the {{org.jboss.aop.advice.annotation}} package.
+
+The type of an annotated parameter can be chosen accordingly to the value it refers
+to. For example, suppose you are intercepting a jointpoint with an argument of type
+{{ArrayList<String>}}. Advices that refer to this argument as being of type
+{{ArrayList<String>}}, or {{Collection<String>}} or {{Object}} would all be
+considered correct. This is useful because you can access specific operations and
+fields of the argument, without performing a cast, and yet you can receive a super
+type like {{Object}} and refer to arguments of different types when your advice is
+applied to different joinpoints.
+
+Notice that, as a convention, we named the advices of this example after the names of
+parameter annotations. Besides, all advices names are prefixed with their types names
+(before advice names start with {{"before"}}, and so on). It is also important
+to point out that, as all previous examples, the name of advices can be chosen freely
+and JBoss AOP won't use these names to identify annotated parameters.
+
+__ at JoinPoint__
+
+This annotation is used on objects that represent a joinpoint. If the advice
+is an around advice, the type of this object belongs to the
+[Invocation class hierarchy|../../misc/invocation.html]. On all other
+advices, joinpoints are represented by types of the
+[JoinPoint interface hierarchy|../../misc/joinpoint.html], as follows:
+
+{{{
+public void beforeJoinPoint(@JoinPoint JoinPointInfo joinPointInfo)
+
+public Object aroundJoinPoint(@JoinPoint CallerInvocation invocation) throws Throwable
+
+public void afterJoinPoint(@JoinPoint ConstructorInfo joinPointInfo)
+}}}
+
+Notice how {{beforeJoinPoint}} advice receives a parameter of the supertype
+{{JoinPointInfo}} while, in {{afterJoinPoint}}, the parameter is of the more
+specific type {{ConstructorInfo}}, valid only on constructor execution
+joinpoints.
+To see these and all other advice examples, open up the {{Aspect.java}} file.
+
+__ at Target__
+
+This annotation is used on parameters that refer to the joinpoint target. The
+joinpoint target is defined according to the joinpoint type. For example, the target
+of a method execution is the object whose method is being executed. On a call
+joinpoint, the target is the object whose method is being called. On a field access
+joinpoint, the target is the object that contains the field. Notice that not all
+joinpoints have a target. Static method executions and calls, static field reads
+and writes, and constructor executions and calls don't have a target.
+
+Examples of usage of this annotation follow:
+
+{{{
+public void beforeTarget(@Target Object target)
+
+public Object aroundTarget(@Target POJO target) throws Throwable
+
+public void afterTarget(@Target POJO target) throws Throwable
+}}}
+
+By opening up {{jboss-aop.xml}}, you can see that the target of all these
+advices is of type {{POJO}}, yet {{beforeTarget}} advice receives a target
+of type {{Object}}. Since {{POJO}} extends {{Object}}, this is
+perfectly valid, and useful when an advice intercepts joinpoints with different
+target types.
+
+__ at Caller__
+
+This annotation is used on parameters that refer to the caller object, during a call
+joinpoint interception. This should be used only on call joinpoints. If the call is
+inside a static method, the caller will be {{null}}.
+Examples follow:
+
+{{{
+public void beforeCaller(@Caller POJO caller)
+
+public Object aroundCaller(@Caller Driver target) throws Throwable
+
+public void afterCaller(@Caller Object target)
+}}}
+
+__ at Return__
+
+Use this annotation only on after advices, to refer to the joinpoint return value:
+
+{{{
+public void afterFieldReturn(@Return Object joinPointReturn)
+
+public void afterMethodReturn(@Return boolean joinPointReturn)
+}}}
+
+__ at Arg__
+
+This annotation is used to refer to a joinpoint argument. Since a joinpoint can
+receive more than one argument, this is the only annotation that can be used on more
+than one advice parameters.
+Look at these examples:
+
+{{{
+public void beforeConstructorArg(@Arg Object argument)
+
+public Object aroundConstructorArg(@Arg String argument) throws Throwable
+
+public void afterArg(@Arg int argument)
+}}}
+
+When the joinpoint receives multiple arguments, JBoss AOP infers to which
+argument an {{@Arg}} annotated parameter refers. In this example, both
+{{beforeConstructorArg}} and {{aroundConstructorArg}} are applied to
+{{POJO}} constructor, whose unique argument is of type {{java.lang.String}}.
+So, the parameters of these advices will refer to this constructor argument.
+On the other hand, {{afterArg}} advice is applied to more than one method
+executions:
+
+{{{
+public class POJO
+{
+ ...
+
+ public boolean someMethod(int argument)
+ {
+ ...
+ }
+
+ public void method(long arg0, int arg1, long arg2, String arg3)
+ {
+ ...
+ }
+
+ ...
+}
+}}}
+
+Wen intercepting {{POJO.someMethod(int)}} execution, the parameter of {{afterArg}}
+will contain the value of the single argument {{someMethod}} received, as it happens
+with {{beforeConstructorArg}} and {{aroundConstructorArg}} advices. But, when
+intercepting {{POJO.method(long,int,long,String)}}, JBoss AOP will automatically
+associate {{afterArg}} parameter with the parameter at index position {{1}}, of type
+{{int}}.
+
+Associating the {{int}} value is easy, because there is only one joinpoint
+argument of that type. The same doesn't apply to the following advice:
+
+{{{
+public void beforeMethodArg(@Arg long argument)
+}}}
+
+Given that {{POJO->method(long,int,long,String)}} has two arguments of type {{long}},
+JBoss AOP will pick the first {{long}} typed argument. If you want to refer to the
+second {{long}} typed argument, in position {{2}}, you can use the optional
+{{@Arg.index}} element as is shown below:
+
+{{{
+public void beforeMethodArg2(@Arg(index=2) long argument)
+}}}
+This element can be set everytime JBoss AOP does not associate your {{@Arg}}
+annotated parameter with the joinpoint argument you want to receive.
+
+__ at Arguments__
+
+Finally, this annotation is used on advice parameters of type <tt>java.lang.Object TODO ARRAY </tt>, that contain the complete list of the joinpoint arguments.
+
+Look at these examples:
+
+{{{
+public void beforeArgs(@Args Object[] arguments)
+
+public Object aroundArgs(@Args Object[] arguments) throws Throwable
+
+public void afterArgs(@Args Object[] arguments)
+}}}
+
+Use this annotation when you need a generic advice, that receives all arguments
+without knowing how many arguments there are, or their types. Using {{@Arguments
+}} instead of a list of {{@Arg}} annotated parameters is useful when you need to
+change one or more joinpoint argument values. An example is the {{beforeArgs}} advice,
+that ovewrites two argument values of {{POJO.method(long,int,long,String)}} execution:
+
+{{{
+public void beforeArgs(@Args Object[] arguments)
+{
+ ...
+ arguments[3] = "overridenString";
+ arguments[1] = Integer.valueOf(((Integer)arguments[1]).intValue() - 50);
+ ...
+}
+}}}
+
+Avoid using {{@Arguments}} when none of those conditions apply. This
+parameter type can incur in the creation of an array and of wrapper objects (as is
+the case of argument 1 above). Besides, you have the extra cost of downcasting
+the arguments.
+<h4>Run the example</h4>
+
+__THIS EXAMPLE REQUIRES JDK 1.5!!__ To compile and run:
+{{{
+ $ ant
+}}}
+It will javac the files and then run the AOPC precompiler to manipulate the bytecode, then finally run the example. The output should read as follows:
+{{{
+run:
+
+ [java] Calling POJO constructor
+ [java] ========================
+ [java] >>> beforeConstructorArg: Object "Driver"
+ [java] >>> aroundConstructorArg: String "Driver"
+ [java] RUNNING new POJO("Driver")
+ [java] >>> afterJoinPoint: ConstructorInfo Constructor[constructor=public POJO(java.lang.String)]
+
+ [java] Setting POJO->field with "text" value
+ [java] =======================================
+ [java] >>> beforeJoinPoint: FieldInfo Field Write[field=public java.lang.Object POJO.field]
+ [java] >>> aroundTarget: POJO POJO at 19209ea
+ [java] >>> aroundArgs: arguments [text]
+
+ [java] Reading POJO->field value
+ [java] =========================
+ [java] >>> aroundArgs: arguments null
+ [java] >>> aroundNoParameters
+ [java] >>> afterFieldReturn: Object text
+ [java] >>> afterNoParameters
+
+ [java] Calling POJO->method(int)
+ [java] =========================
+ [java] >>> aroundArgs: arguments [17]
+ [java] RUNNING POJO->method(17)
+ [java] >>> afterArg: int 17
+ [java] >>> afterArgs: arguments [17]
+
+ [java] Calling POJO->method(long, int, long, String)
+ [java] =============================================
+ [java] >>> beforeMethodArg: long 20L
+ [java] >>> beforeMethodArg2: long 1000L
+ [java] >>> beforeArgs changing arguments: from [20, 2, 1000, Driver]
+ [java] to [20, -48, 1000, overridenString]
+ [java] >>> aroundArgs: arguments [20, -48, 1000, overridenString]
+ [java] RUNNING POJO->method(20L, -48, 1000L, "overridenString")
+ [java] >>> afterArg: int -48
+ [java] >>> afterArgs: arguments [20, -48, 1000, overridenString]
+
+ [java] Calling POJO->someMethod(int)
+ [java] =============================
+ [java] >>> beforeNoParameters
+ [java] RUNNING POJO->someMethod()
+ [java] >>> afterMethodReturn: boolean true
+ [java] >>> afterArg: int 10
+
+ [java] Calling POJO->callMethod()
+ [java] ==========================
+ [java] >>> aroundCaller: Driver null
+ [java] >>> aroundArgs: arguments []
+ [java] RUNNING POJO->callMethod()
+ [java] >>> beforeTarget: Object POJO at 19209ea
+ [java] >>> beforeCaller: POJO POJO at 19209ea
+ [java] >>> aroundJoinPoint: CallerInvocation JoinPoint_MByM__N_6287195452448676113POJO_N_1153034853916900765_8 at f99ff5
+ [java] RUNNING POJO->calledMethod()
+ [java] >>> afterTarget: POJO POJO at 19209ea
+ [java] >>> afterCaller: Object POJO at 19209ea
+}}}
+
Property changes on: projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.wiki
___________________________________________________________________
Name: svn:executable
+ *
Modified: projects/aop/trunk/aop/docs/examples/beforeafter/MutexAspect.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/MutexAspect.java 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/MutexAspect.java 2007-04-12 22:10:19 UTC (rev 62310)
@@ -19,7 +19,6 @@
* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
*/
-package mypackage;
import org.jboss.aop.advice.annotation.JoinPoint;
@@ -30,11 +29,6 @@
private Object lock = new Object();
private boolean locked = false;
- public MutexAspect()
- {
- System.out.println("CONSTRUCTOR!!!!!");
- }
-
public void beforeAdvice(@JoinPoint JoinPointInfo joinPoint)
{
synchronized(lock)
Modified: projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html 2007-04-12 22:10:19 UTC (rev 62310)
@@ -2,20 +2,23 @@
<body>
<p>
<h2>Before and After Advices</h2>
+
</p><p>
-<h4>Overview</h4>
+<h3>Overview</h3>
+
JBoss AOP provides several types of advices. The advices seen on the previous
section, as well as JBoss AOP interceptors, provide around join point interception.
In this example we introduce before and after advices, and compare their roles to
around advices' role.
</p><p>
-<h4>Writing Before/After Advices</h4>
+<h3>Writing Before/After Advices</h3>
+
</p><p>
Before and after advices are lightweight advices when compared to around advices.
JBoss AOP invokes these advices before or after the joinpoint execution.
</p><p>
-As we will see in the next <a href="../annotated-parameters/annotated-parameters.html">
-example</a>, these advices can have several different signatures. However, in our
+As we will see in the next <a href="../annotated-parameters/annotated-parameters.html">example</a>,
+these advices can have several different signatures. However, in our
first example, we will use signatures that are closest to what has been shown on
previous examples.
@@ -29,26 +32,26 @@
not necessary, because these advices do not wrap a joinpoint.
</p><p>
Instead of <tt>Invocation</tt> instances, before/after advices receive instances
-of <a href="../../misc/joinpoint.html"><tt>org.jboss.aop.IJoinpointInfo</tt> and
-subinterfaces</a> as parameters.
+of <a href="../../misc/joinpoint.html"><tt>org.jboss.aop.IJoinpointInfo</tt> and subinterfaces</a>
+as parameters.
</p><p>
-Furthermore, one can notice the presence of the parameter annotation <tt>
-@org.jboss.aop.advice.annotation.JoinPoint</tt>. This is necessary because
+Furthermore, one can notice the presence of the parameter annotation <tt>@org.jboss.aop.advice.annotation.JoinPoint</tt>. This is necessary because
before/after advices can receive values with several semantic roles as parameters.
As we will see <a href="../annotated-parameters/annotated-parameters.html">next</a>,
this annotation is used to distinguish this parameter type from the other ones, so we
can achieve flexibility on the type, order and presence of advice parameters.
</p><p>
-<h4>Binding Before/After Advices</h4>
+<h3>Binding Before/After Advices</h3>
+
</p><p>
To bind a before/after advice to a pointcut, you only need to declare an xml binding as
follows (open up <tt>jboss-aop.xml</tt> to see this example):
</p><p>
<pre>
-<bind pointcut="execution(public void $instanceof{Transaction}->run())">
+<bind pointcut="execution(public void $instanceof{Transaction}->run())">
<before name="beforeAdvice" aspect="mypackage.MutexAspect"/>
<after name="afterAdvice" aspect="mypackage.MutexAspect"/>
-</bind>
+</bind>
</pre>
</p><p>
As you can see, you just need to declare a usual bind tag, and add to it
@@ -57,9 +60,9 @@
after advices declarations in a single binding.
</p><p>
-<h4>Around, Before and After Advices</h4>
-</p><p>
+<h3>Around, Before and After Advices</h3>
+</p><p>
As seen on previous sections, around advices wrap the joinpoint execution. An around
advice replaces the joinpoint execution in the base system, and is responsible for
forwarding execution to the joinpoint itself, as well as for returning a value to the
@@ -75,20 +78,20 @@
public Object aroundAdvice(Invocation invocation) throws Throwable
{
Object result;
- <font color="808080"> <i>
- // part 1: retrive lock before joinpoint execution </i></font>
+
+ // part 1: retrive lock before joinpoint execution
synchronized(this)
{
System.out.println(">>> Retrieved concurrency lock");
- <font color="808080"> <i>
- // part 2: proceed to joinpoint execution</i></font>
+
+ // part 2: proceed to joinpoint execution
result = invocation.invokeNext();
- <font color="808080"> <i>
- // part 3: release lock after joinpoint execution</i></font>
+
+ // part 3: release lock after joinpoint execution
System.out.println("<<< Releasing concurrency lock");
}
- <font color="808080"> <i>
- // part 4: return result</i></font>
+
+ // part 4: return result
return result;
}
}
@@ -100,17 +103,14 @@
</p><p>
As we can see, <tt>SynchronizationAspect.aroundAdvice()</tt> is composed of four
steps:
-
-<list>
- <li>retrieving a lock before the joinpoint execution, achieved by entering the
- <tt>synchronized</tt> block;</li>
- <li>proceeding to joinpoint execution;</li>
- <li>releasing the lock after the joinpoint execution, achieved by exiting the
- <tt>synchronized</tt> block;</li>
- <li>and returning the joinpoint result.</li>
-</list>
-
</p><p>
+<ul>
+<li> retrieving a lock before the joinpoint execution, achieved by entering the <tt>synchronized</tt> block;</li>
+<li> proceeding to joinpoint execution;</li>
+<li> releasing the lock after the joinpoint execution, achieved by exiting the <tt>synchronized</tt> block;</li>
+<li> and returning the joinpoint result.</li>
+</ul>
+</p><p>
Notice that this advice does not alter joinpoint execution (the advice does not
skip it) nor its return result (the advice could overwrite this value, but returns
the joinpoint return value itself instead). Hence, we can say that the relevant part
@@ -130,8 +130,8 @@
public Object aroundAdvice(Invocation invocation) throws Throwable
{
Object result;
- <font color="808080"> <i>
- // part 1: retrive lock before joinpoint execution</i></font>
+
+ // part 1: retrive lock before joinpoint execution
synchronized(lock)
{
while (locked)
@@ -149,25 +149,24 @@
locked = true;
System.out.println(">>> Retrieved concurrency lock");
}
- <font color="808080"> <i>
- // part 2: proceed to joinpoint execution</i></font>
+
+ // part 2: proceed to joinpoint execution
result = invocation.invokeNext();
- <font color="808080"> <i>
- // part 3: release lock after joinpoint execution</i></font>
+
+ // part 3: release lock after joinpoint execution
synchronized(lock)
{
locked = false;
lock.notify();
System.out.println("<<< Releasing concurrency lock");
}
- <font color="808080"> <i>
- // part 4: return result</i></font>
+
+ // part 4: return result
return result;
}
}
-</pre>
+</pre>
</p><p>
-
As much as <tt>SynchronizedAspect</tt>, <tt>MutexAspect</tt> avoids simultaneous
access to the intercepted joinpoint, and is also composed of the four steps
(getting a lock, proceeding to joinpoint execution and releasing the lock).
@@ -176,8 +175,7 @@
the lock, and another one that releases it. We wish to run the first one before a
joinpoint, and the other one, after it.
</p><p>
-The example that follows is a copy of the previous one, except that, now, <tt>
-MutexAspect.aroundAdvice()</tt> has been splitten into <tt>MutexAspect.beforeAdvice()
+The example that follows is a copy of the previous one, except that, now, <tt>MutexAspect.aroundAdvice()</tt> has been splitten into <tt>MutexAspect.beforeAdvice()
</tt> and <tt>MutexAspect.afterAdvice()</tt>:
</p><p>
<pre>
@@ -222,10 +220,10 @@
Notice that, in this version, parts 2 and 4 are gone (proceeding to joinpoint
execution and returning its result). This is due to the fact that before and after
advices don't wrap a joinpoint, they are just executed before or after it.
+</p><p>
+<h3>Around vs Before/After</h3>
</p><p>
-<h4>Around vs Before/After</h4>
-</p><p>
As is shown in this example, around advices can generally be broken into two related
before and after advices. The reverse is also true.
However, there are some subtleties that can help you to choose one form or the
@@ -233,14 +231,11 @@
</p><p>
First of all, these are features that are available only to around advices:
</p><p>
-<list>
-<li>capability of replacing the entire joinpoint execution, by skipping the call to
- <tt>Invocation.invokeNext() method</tt>;</li>
-<li>capability of skipping the invocation of subsequent around advices and
- interceptors, by calling <tt>Invocation.invokeTarget()</tt> instead of
- <tt>Invocation.invokeNext()</tt>;</li>
-<li>addition of meta-data, available on Invocation objects only.</li>
-</list>
+<ul>
+<li> capability of replacing the entire joinpoint execution, by skipping the call to <tt>Invocation.invokeNext() method</tt>;</li>
+<li> capability of skipping the invocation of subsequent around advices and interceptors, by calling <tt>Invocation.invokeTarget()</tt> instead of <tt>Invocation.invokeNext()</tt>;</li>
+<li> addition of meta-data, available on Invocation objects only.</li>
+</ul>
</p><p>
When you need one of those advanced features, you should use an around advice or
interceptor. Besides, there are aspects that cannot be implemented as a
@@ -254,11 +249,10 @@
On the other hand, before and after advices also provide some advantages. A pair of
related before/after advices:
</p><p>
-<list>
-<li>is lightweight, when compared to around advices</li>
-<li>can be bound to different joinpoints. The before advice can be invoked before
-joinpoint A and the after advice, after joinPoint B</li>
-</list>
+<ul>
+<li> is lightweight, when compared to around advices</li>
+<li> can be bound to different joinpoints. The before advice can be invoked before joinpoint A and the after advice, after joinPoint B</li>
+</ul>
</p><p>
Since they are more lighweight, prefer using a pair of before/after advices, unless
you have a reason to do otherwise.
@@ -272,7 +266,8 @@
advices and interceptors. An after advice can also return a value (for more on this,
refer to the <a href="../return-types/return-types.html">Return Types</a> example).
</p><p>
-<h4>Unrelated Before and After Advices</h4>
+<h3>Unrelated Before and After Advices</h3>
+
</p><p>
Despite the application of before and after advices shown in this example, these
advices can also be used in an unrelated, independent manner.
@@ -286,9 +281,10 @@
Examples of unrelated before and after advices will be shown in the next examples of
this tutorial.
</p><p>
-<h4>Applying MutexAspect</h4>
+<h3>Applying MutexAspect</h3>
+
</p><p>
-In our example, we apply <tt>MutexAspect</tt> to a classic example of sinchronization
+In our example, we apply <tt>MutexAspect</tt> to a classic example of synchronization
and concurrent programming application.
</p><p>
Suppose you have bank accounts and operations on accounts can be performed
@@ -299,19 +295,21 @@
is a deposit of $30.00, while the other one is a withdrawal of $10.00. If these
operations are run in an unsynchronized manner, like follows:
</p><p>
-<list>
-<li>deposit: read balance: $50.00</li>
-<li>withdrawal: read balance: $50.00</li>
-<li>deposit: add $30.00</li>
-<li>withdrawal: subtract $10.00</li>
-<li>deposit: write final balance of $80.00</li>
-<li>withdrawal: write final balance of $40.00</li>
-</list>
+<ul>
+<li> deposit: read balance: $50.00</li>
+<li> withdrawal: read balance: $50.00</li>
+<li> deposit: add $30.00</li>
+<li> withdrawal: subtract $10.00</li>
+<li> deposit: write final balance of $80.00</li>
+<li> withdrawal: write final balance of $40.00</li>
+</ul>
+</p><p>
The final balance of the account would be $40.00, and the deposit of $50.00 would
have been completely ignored, since its final balance has been overwritten by
the withdrawal operation.
</p><p>
-<h4>Running</h4>
+<h3>Running</h3>
+
</p><p>
<b>THIS EXAMPLE REQUIRES JDK 1.5!!</b> To compile and run:
<pre>
@@ -364,4 +362,4 @@
<tt>input.txt</tt> file.
</p>
</body>
-</html>
\ No newline at end of file
+</html>
Added: projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.wiki
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.wiki (rev 0)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.wiki 2007-04-12 22:10:19 UTC (rev 62310)
@@ -0,0 +1,342 @@
+!!!Before and After Advices
+
+!!Overview
+JBoss AOP provides several types of advices. The advices seen on the previous
+section, as well as JBoss AOP interceptors, provide around join point interception.
+In this example we introduce before and after advices, and compare their roles to
+around advices' role.
+
+!!Writing Before/After Advices
+
+Before and after advices are lightweight advices when compared to around advices.
+JBoss AOP invokes these advices before or after the joinpoint execution.
+
+As we will see in the next [example|../annotated-parameters/annotated-parameters.html],
+these advices can have several different signatures. However, in our
+first example, we will use signatures that are closest to what has been shown on
+previous examples.
+
+So, we introduce a before and after advices as being of the form:
+
+{{{
+public void <any-method-name>(@JoinPoint <any Joinpoint type>)
+}}}
+
+Differently from around advices and interceptors, throwing a {{Throwable}} is
+not necessary, because these advices do not wrap a joinpoint.
+
+Instead of {{Invocation}} instances, before/after advices receive instances
+of [{{org.jboss.aop.IJoinpointInfo}} and subinterfaces|../../misc/joinpoint.html]
+as parameters.
+
+Furthermore, one can notice the presence of the parameter annotation {{@org.jboss.aop.advice.annotation.JoinPoint}}. This is necessary because
+before/after advices can receive values with several semantic roles as parameters.
+As we will see [next|../annotated-parameters/annotated-parameters.html],
+this annotation is used to distinguish this parameter type from the other ones, so we
+can achieve flexibility on the type, order and presence of advice parameters.
+
+!!Binding Before/After Advices
+
+To bind a before/after advice to a pointcut, you only need to declare an xml binding as
+follows (open up {{jboss-aop.xml}} to see this example):
+
+{{{
+<bind pointcut="execution(public void $instanceof{Transaction}->run())">
+ <before name="beforeAdvice" aspect="mypackage.MutexAspect"/>
+ <after name="afterAdvice" aspect="mypackage.MutexAspect"/>
+</bind>
+}}}
+
+As you can see, you just need to declare a usual bind tag, and add to it
+{{<before>}} and {{<after>}} tags for before and after advices
+respectively. We can also mix interceptor declarations and around, before, and
+after advices declarations in a single binding.
+
+
+!!Around, Before and After Advices
+
+As seen on previous sections, around advices wrap the joinpoint execution. An around
+advice replaces the joinpoint execution in the base system, and is responsible for
+forwarding execution to the joinpoint itself, as well as for returning a value to the
+base system.
+
+Around advices can be composed by four parts at most: a before joinpoint execution
+block, a proceed to joinpoint step, an after joinpoint execution block, and, finally,
+a return value step. To see an example, consider this {{PER_VM}} scoped aspect:
+
+{{{
+public class SynchronizationAspect
+{
+ public Object aroundAdvice(Invocation invocation) throws Throwable
+ {
+ Object result;
+
+ // part 1: retrive lock before joinpoint execution
+ synchronized(this)
+ {
+ System.out.println(">>> Retrieved concurrency lock");
+
+ // part 2: proceed to joinpoint execution
+ result = invocation.invokeNext();
+
+ // part 3: release lock after joinpoint execution
+ System.out.println("<<< Releasing concurrency lock");
+ }
+
+ // part 4: return result
+ return result;
+ }
+}
+}}}
+
+{{SynchronizationAspect}} synchronizes all intercepted joinpoints (in a
+concurrent programming application), avoiding that two or more intercepted joinpoints
+run at the same time.
+
+As we can see, {{SynchronizationAspect.aroundAdvice()}} is composed of four
+steps:
+
+* retrieving a lock before the joinpoint execution, achieved by entering the {{synchronized}} block;
+* proceeding to joinpoint execution;
+* releasing the lock after the joinpoint execution, achieved by exiting the {{synchronized}} block;
+* and returning the joinpoint result.
+
+Notice that this advice does not alter joinpoint execution (the advice does not
+skip it) nor its return result (the advice could overwrite this value, but returns
+the joinpoint return value itself instead). Hence, we can say that the relevant part
+of it is only what is performed before and after the joinpoint (parts 1 and 3). To
+illustrate the before/after concept, we wish to replace this single around advice
+by a couple of before/after advices. However, we cannot do that by using the
+previous example. A synchronized block cannot be splitten into two parts and still
+achieve the same effect. So, lets first replace this around advice by one that uses a
+mutex intead of a synchronized block:
+
+{{{
+public class MutexAspect
+{
+ private Object lock = new Object();
+ private boolean locked = false;
+
+ public Object aroundAdvice(Invocation invocation) throws Throwable
+ {
+ Object result;
+
+ // part 1: retrive lock before joinpoint execution
+ synchronized(lock)
+ {
+ while (locked)
+ {
+ try
+ {
+ lock.wait();
+ }
+ catch(InterruptedException e)
+ {
+ Thread.currentThread().interrupt();
+ return;
+ }
+ }
+ locked = true;
+ System.out.println(">>> Retrieved concurrency lock");
+ }
+
+ // part 2: proceed to joinpoint execution
+ result = invocation.invokeNext();
+
+ // part 3: release lock after joinpoint execution
+ synchronized(lock)
+ {
+ locked = false;
+ lock.notify();
+ System.out.println("<<< Releasing concurrency lock");
+ }
+
+ // part 4: return result
+ return result;
+ }
+}
+}}}
+
+As much as {{SynchronizedAspect}}, {{MutexAspect}} avoids simultaneous
+access to the intercepted joinpoint, and is also composed of the four steps
+(getting a lock, proceeding to joinpoint execution and releasing the lock).
+
+Now we can easily split this around advice into two advices: one that retrieves
+the lock, and another one that releases it. We wish to run the first one before a
+joinpoint, and the other one, after it.
+
+The example that follows is a copy of the previous one, except that, now, {{MutexAspect.aroundAdvice()}} has been splitten into {{MutexAspect.beforeAdvice()
+}} and {{MutexAspect.afterAdvice()}}:
+
+{{{
+public class MutexAspect
+{
+ private Object lock = new Object();
+ private boolean locked = false;
+
+ public void beforeAdvice(@JoinPoint Joinpoint joinPoint)
+ {
+ synchronized(lock)
+ {
+ while (locked)
+ {
+ try
+ {
+ lock.wait();
+ }
+ catch(InterruptedException e)
+ {
+ Thread.currentThread().interrupt();
+ return;
+ }
+ }
+ locked = true;
+ System.out.println(">>> Retrieved concurrency lock");
+ }
+ }
+
+ public void afterAdvice(@JoinPoint Joinpoint joinPoint)
+ {
+ synchronized(lock)
+ {
+ locked = false;
+ lock.notify();
+ System.out.println("<<< Releasing concurrency lock");
+ }
+ }
+}
+}}}
+
+Notice that, in this version, parts 2 and 4 are gone (proceeding to joinpoint
+execution and returning its result). This is due to the fact that before and after
+advices don't wrap a joinpoint, they are just executed before or after it.
+
+!!Around vs Before/After
+
+As is shown in this example, around advices can generally be broken into two related
+before and after advices. The reverse is also true.
+However, there are some subtleties that can help you to choose one form or the
+other.
+
+First of all, these are features that are available only to around advices:
+
+* capability of replacing the entire joinpoint execution, by skipping the call to {{Invocation.invokeNext() method}};
+* capability of skipping the invocation of subsequent around advices and interceptors, by calling {{Invocation.invokeTarget()}} instead of {{Invocation.invokeNext()}};
+* addition of meta-data, available on Invocation objects only.
+
+When you need one of those advanced features, you should use an around advice or
+interceptor. Besides, there are aspects that cannot be implemented as a
+pair of before and after advices. An example would be the {{SynchronizedAspect}}
+shown before. A synchronized block cannot be broken into two blocks and achieve the
+same result as one single synchronized block. In the example, we wrote a similar,
+more complex aspect to illustrate the before/after advice concept. In real
+applications, however, this aspect would not be replaced by a more complex one,
+unless this could bring advantages to the application.
+
+On the other hand, before and after advices also provide some advantages. A pair of
+related before/after advices:
+
+* is lightweight, when compared to around advices
+* can be bound to different joinpoints. The before advice can be invoked before joinpoint A and the after advice, after joinPoint B
+
+Since they are more lighweight, prefer using a pair of before/after advices, unless
+you have a reason to do otherwise.
+Regarding the second item in the list, it can be extremely useful in the case of
+MutexAspect. Instead of controling the multi-threaded access to a single joinpoint,
+we could obtain the lock before a joinpoint, and release it later, after a different
+joinpoint execution. This allows the synchronization of a sequence of joinpoints as
+if they were a single unit.
+
+Lets remark that replacing the joinpoint return value is not a feature exclusive to around
+advices and interceptors. An after advice can also return a value (for more on this,
+refer to the [Return Types|../return-types/return-types.html] example).
+
+!!Unrelated Before and After Advices
+
+Despite the application of before and after advices shown in this example, these
+advices can also be used in an unrelated, independent manner.
+
+An aspect whose code needs to run only before the joinpoint execution should contain
+only before advices. The same applies to an aspect that needs to execute after
+a joinpoint execution, regarding after advices. Furthermore, an aspect that provides
+functionalities that need to be run before a joinpoint execution, and functionalities
+that need to be run after, should contain a mix of unrelated before and after advices.
+
+Examples of unrelated before and after advices will be shown in the next examples of
+this tutorial.
+
+!!Applying MutexAspect
+
+In our example, we apply {{MutexAspect}} to a classic example of synchronization
+and concurrent programming application.
+
+Suppose you have bank accounts and operations on accounts can be performed
+concurrently. If we don't synchronize those operations we can end up with an invalid
+account balance.
+
+An example would be two operations on account {{A}}. Suppose one of them
+is a deposit of $30.00, while the other one is a withdrawal of $10.00. If these
+operations are run in an unsynchronized manner, like follows:
+
+* deposit: read balance: $50.00
+* withdrawal: read balance: $50.00
+* deposit: add $30.00
+* withdrawal: subtract $10.00
+* deposit: write final balance of $80.00
+* withdrawal: write final balance of $40.00
+
+The final balance of the account would be $40.00, and the deposit of $50.00 would
+have been completely ignored, since its final balance has been overwritten by
+the withdrawal operation.
+
+!!Running
+
+__THIS EXAMPLE REQUIRES JDK 1.5!!__ To compile and run:
+{{{
+ $ ant
+}}}
+It will javac the files and then run the AOPC precompiler to manipulate the bytecode, then finally run the example. The output should be similar to this:
+{{{
+run:
+ [java] SETUP
+ [java] =====
+ [java] Creating account 'A' with initial balance of $30.0
+ [java] Creating account 'B' with initial balance of $50.0
+ [java] Creating account 'C' with initial balance of $0.0
+
+ [java] TRANSACTIONS
+ [java] ============
+ [java] Using context classloader sun.misc.Launcher$AppClassLoader at 133056f to load aspect mypackage.MutexAspect
+ [java] Using context classloader sun.misc.Launcher$AppClassLoader at 133056f to load aspect mypackage.MutexAspect
+ [java] >>> Retrieved concurrency lock
+ [java] Depositing US$ 50.00 to account A
+ [java] <<< Releasing concurrency lock
+ [java] >>> Retrieved concurrency lock
+ [java] Transfering US$ 100.00 from account B to account C
+ [java] <<< Releasing concurrency lock
+ [java] >>> Retrieved concurrency lock
+ [java] Withdrawing US$ 10.00 from account A
+ [java] <<< Releasing concurrency lock
+ [java] >>> Retrieved concurrency lock
+ [java] Transfering US$ 89.11 from account C to account A
+ [java] <<< Releasing concurrency lock
+ [java] >>> Retrieved concurrency lock
+ [java] Depositing US$ 51.00 to account B
+ [java] <<< Releasing concurrency lock
+ [java] >>> Retrieved concurrency lock
+ [java] Withdrawing US$ 0.11 from account C
+ [java] <<< Releasing concurrency lock
+ [java] >>> Retrieved concurrency lock
+ [java] Withdrawing US$ 5.00 from account B
+ [java] <<< Releasing concurrency lock
+
+ [java] FINAL BALANCE
+ [java] ===== =======
+ [java] A: US$ 159.11
+ [java] C: US$ 10.78
+ [java] B: -US$ 4.00
+
+}}}
+
+You can add accounts and transactions to this example application by editing the
+{{input.txt}} file.
Property changes on: projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.wiki
___________________________________________________________________
Name: svn:executable
+ *
Modified: projects/aop/trunk/aop/docs/examples/beforeafter/jboss-aop.xml
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/jboss-aop.xml 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/jboss-aop.xml 2007-04-12 22:10:19 UTC (rev 62310)
@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="UTF-8"?>
<aop>
- <aspect class="mypackage.MutexAspect" scope="PER_VM"/>
+ <aspect class="MutexAspect" scope="PER_VM"/>
<bind pointcut="execution(public void $instanceof{Transaction}->run())">
- <before name="beforeAdvice" aspect="mypackage.MutexAspect"/>
- <after name="afterAdvice" aspect="mypackage.MutexAspect"/>
+ <before name="beforeAdvice" aspect="MutexAspect"/>
+ <after name="afterAdvice" aspect="MutexAspect"/>
</bind>
</aop>
Modified: projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html 2007-04-12 22:10:19 UTC (rev 62310)
@@ -22,22 +22,22 @@
if (invocation instanceof ConstructorInvocation)
{
System.out.println(">>> aroundAdvice on constructor of class: " +
- invocation.getConstructor().getDeclaringClass().getName());
+ (ConstructorInvocation) invocation).getConstructor().getDeclaringClass().getName());
}
else if (invocation instanceof MethodInvocation)
{
System.out.println(">>> aroundAdvice on method execution: " +
- invocation.getMehod().getName());
+ ((MethodInvocation) invocation).getMethod().getName());
}
else if (invocation instanceof FieldReadInvocation)
{
System.out.println(">>> aroundAdvice on field read: " +
- invocation.getField().getName());
+ ((FieldReadInvocation) invocation).getField().getName());
}
else if (invocation instanceof FieldWriteInvocation)
{
System.out.println(">>> aroundAdvice on field write: " +
- invocation.getField().getName());
+ ((FieldWriteInvocation) invocation).getField().getName());
}
return invocation.invokeNext();
@@ -171,7 +171,7 @@
Run the example to see how this advice is applied to the different POJO joinpoints.
</p><p>
To see all rules JBoss AOP uses to pick an overloaded advice version, please, read
-the corresponding chapter at the Reference Manual.
+the corresponding chapter of the Reference Manual.
</p><p>
<h4>Run the example</h4>
Modified: projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki 2007-04-12 20:07:01 UTC (rev 62309)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki 2007-04-12 22:10:19 UTC (rev 62310)
@@ -16,22 +16,22 @@
if (invocation instanceof ConstructorInvocation)
{
System.out.println(">>> aroundAdvice on constructor of class: " +
- invocation.getConstructor().getDeclaringClass().getName());
+ (ConstructorInvocation) invocation).getConstructor().getDeclaringClass().getName());
}
else if (invocation instanceof MethodInvocation)
{
System.out.println(">>> aroundAdvice on method execution: " +
- invocation.getMehod().getName());
+ ((MethodInvocation) invocation).getMethod().getName());
}
else if (invocation instanceof FieldReadInvocation)
{
System.out.println(">>> aroundAdvice on field read: " +
- invocation.getField().getName());
+ ((FieldReadInvocation) invocation).getField().getName());
}
else if (invocation instanceof FieldWriteInvocation)
{
System.out.println(">>> aroundAdvice on field write: " +
- invocation.getField().getName());
+ ((FieldWriteInvocation) invocation).getField().getName());
}
return invocation.invokeNext();
@@ -164,7 +164,7 @@
Run the example to see how this advice is applied to the different POJO joinpoints.
To see all rules JBoss AOP uses to pick an overloaded advice version, please, read
-the corresponding chapter at the Reference Manual.
+the corresponding chapter of the Reference Manual.
!Run the example
More information about the jboss-cvs-commits
mailing list