[jboss-cvs] JBossAS SVN: r62119 - in projects/aop/trunk/aop/docs/examples: beforeafter and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Apr 5 00:51:48 EDT 2007
Author: flavia.rainone at jboss.com
Date: 2007-04-05 00:51:48 -0400 (Thu, 05 Apr 2007)
New Revision: 62119
Modified:
projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html
projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html
Log:
[JBAOP-44] First text revision.
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-05 03:06:25 UTC (rev 62118)
+++ projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html 2007-04-05 04:51:48 UTC (rev 62119)
@@ -22,15 +22,19 @@
</pre>
</p><p>
This signature is available for all kinds of advices in JBoss AOP (when running in
-the default generated advisor mode). Basicaly, it allows an advice to receive zero
-or more annotated parameters, in any order, and with any valid type.
+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.
</p><p>
-Regarding the exception types, an advice is allowed to declare any exception in its
-signature. If the exception is declared in the joinpoint exceptions list (and if
-the joinpoint has an exception list), JBoss AOP rethrows the exception as is. If
-the exception is not part of the joinpoint exception list, JBoss AOP will wrap it in
-a <tt>RuntimeException</tt>. In both cases, the application would get the exception
-as if the joinpoint itself had thrown it.
+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
+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:
@@ -39,12 +43,11 @@
public void beforeAdvice(@JoinPoint Joinpoint joinPoint)
</pre>
</p><p>
-As we can see, this advice receives one parameter, annotated with
+As we can see, this advice receives one parameter annotated with
<tt>@JoinPoint</tt>.
</p><p>
-In the next topics 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:
+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:
</p><p>
<pre>
public void beforeNoParameters()
@@ -63,8 +66,8 @@
that can be used by before, after and around advices. These annotations are located
in the <tt>org.jboss.aop.advice.annotation</tt> package.
</p><p>
-The type of an annotated parameter can be chosen accordingly to the value it refers.
-For example, suppose you are intercepting a jointpoint with an argument of type
+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
@@ -73,9 +76,10 @@
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. It is important to point 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. The same applies to the names of advice parameters.
+parameter annotations. Besides, all advices names are prefixed with their types names
+(before advice names start with <tt>"before"</tt>, 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.
</p><p>
<h5>@JoinPoint</h5>
</p><p>
@@ -197,8 +201,8 @@
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>, which is the
-second <tt>POJO.method()</tt> parameter, of type <tt>int</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:
@@ -238,7 +242,7 @@
</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> method execution:
+POJO.method(long,int,long,String)</tt> execution:
</p><p>
<pre>
public void beforeArgs(@Args Object[] arguments)
@@ -250,9 +254,13 @@
}
</pre>
</p><p>
+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>
</p><p>
-To compile and run:
+<b>THIS EXAMPLE REQUIRES JDK 1.5!!</b> To compile and run:
<pre>
$ ant
</pre>
@@ -275,7 +283,7 @@
[java] Reading POJO->field value
[java] =========================
- [java] >>> aroundArgs: arguments []
+ [java] >>> aroundArgs: arguments null
[java] >>> aroundNoParameters
[java] >>> afterFieldReturn: Object text
[java] >>> afterNoParameters
Modified: projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html 2007-04-05 03:06:25 UTC (rev 62118)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html 2007-04-05 04:51:48 UTC (rev 62119)
@@ -14,7 +14,7 @@
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="../annotatedparam-return/annotatedparam-return.html">
+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.
@@ -32,17 +32,17 @@
of <a href="../../misc/joinpoint.html"><tt>org.jboss.aop.IJoinpointInfo</tt> and
subinterfaces</a> as parameters.
</p><p>
-Besides this difference, one can notice the presence of parameter annotation <tt>
+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="../annotatedparam-return/annotatedparam-return.html">next</a>,
+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>
</p><p>
To bind a before/after advice to a pointcut, you only need to declare an xml binding as
-follows (please, open up <tt>jboss-aop.xml</tt> to see this example):
+follows (open up <tt>jboss-aop.xml</tt> to see this example):
</p><p>
<pre>
<bind pointcut="execution(public void $instanceof{Transaction}->run())">
@@ -53,7 +53,7 @@
</p><p>
As you can see, you just need to declare a usual bind tag, and add to it
<tt><before></tt> and <tt><after></tt> tags for before and after advices
-respectively. Notice that we can mix interceptor declarations and around, before, and
+respectively. We can also mix interceptor declarations and around, before, and
after advices declarations in a single binding.
</p><p>
@@ -75,20 +75,20 @@
public Object aroundAdvice(Invocation invocation) throws Throwable
{
Object result;
-
- // part 1: retrive lock before joinpoint execution
+ <font color="808080"> <i>
+ // part 1: retrive lock before joinpoint execution </i></font>
synchronized(this)
{
System.out.println(">>> Retrieved concurrency lock");
-
- // part 2: proceed to joinpoint execution
+ <font color="808080"> <i>
+ // part 2: proceed to joinpoint execution</i></font>
result = invocation.invokeNext();
-
- // part 3: release lock after joinpoint execution
+ <font color="808080"> <i>
+ // part 3: release lock after joinpoint execution</i></font>
System.out.println("<<< Releasing concurrency lock");
}
-
- // part 4: return result
+ <font color="808080"> <i>
+ // part 4: return result</i></font>
return result;
}
}
@@ -107,7 +107,7 @@
<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 joinpoint result.</li>
+ <li>and returning the joinpoint result.</li>
</list>
</p><p>
@@ -115,7 +115,7 @@
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
-ilustrate the before/after concept, we wish to replace this single around advice
+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
@@ -130,8 +130,8 @@
public Object aroundAdvice(Invocation invocation) throws Throwable
{
Object result;
-
- // part 1: retrive lock before joinpoint execution
+ <font color="808080"> <i>
+ // part 1: retrive lock before joinpoint execution</i></font>
synchronized(lock)
{
while (locked)
@@ -149,19 +149,19 @@
locked = true;
System.out.println(">>> Retrieved concurrency lock");
}
-
- // part 2: proceed to joinpoint execution
+ <font color="808080"> <i>
+ // part 2: proceed to joinpoint execution</i></font>
result = invocation.invokeNext();
-
- // part 3: release lock after joinpoint execution
+ <font color="808080"> <i>
+ // part 3: release lock after joinpoint execution</i></font>
synchronized(lock)
{
locked = false;
lock.notify();
System.out.println("<<< Releasing concurrency lock");
}
-
- // part 4: return result
+ <font color="808080"> <i>
+ // part 4: return result</i></font>
return result;
}
}
@@ -172,7 +172,7 @@
access to the intercepted joinpoint, and is also composed of the four steps
(getting a lock, proceeding to joinpoint execution and releasing the lock).
</p><p>
-However, we can easily split this around advice into two advices: one that retrieves
+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.
</p><p>
@@ -231,7 +231,7 @@
However, there are some subtleties that can help you to choose one form or the
other.
</p><p>
-First of all, these are advantages of using around advices:
+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
@@ -242,35 +242,35 @@
<li>addition of meta-data, available on Invocation objects only.</li>
</list>
</p><p>
-Besides this list, there are aspects that cannot be implemented as a pair of before
-and after advices. An example would be the <tt>SynchronizedAspect</tt> shown before.
-A synchronized block cannot be broken into two blocks and achieve the
+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 <tt>SynchronizedAspect</tt>
+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 ilustrate the before/after advice concept. In real
+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.
</p><p>
-When one needs one or more of the cited capabilities, or has an aspect that needs
-to be written as an around advice, we advise the use of around advices.
-</p><p>
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 after advice, after joinPoint B</li>
+joinpoint A and the after advice, after joinPoint B</li>
</list>
</p><p>
-Regarding the second item in the list, notice that this 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.
+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.
</p><p>
-Notice that replacing the joinpoint return value is not inherent to around advices
-and interceptors. An after advice can also return a value (for more on this, refer to
-<a href="../returnvalue/returnvalue.html">Return Value</a>).
+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 <a href="../return-types/return-types.html">Return Types</a> example).
</p><p>
<h4>Unrelated Before and After Advices</h4>
</p><p>
@@ -283,7 +283,7 @@
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.
</p><p>
-Examples of unrelated before and after advices will be shown in the next topics of
+Examples of unrelated before and after advices will be shown in the next examples of
this tutorial.
</p><p>
<h4>Applying MutexAspect</h4>
@@ -313,14 +313,20 @@
</p><p>
<h4>Running</h4>
</p><p>
-To compile and run:
+<b>THIS EXAMPLE REQUIRES JDK 1.5!!</b> To compile and run:
<pre>
$ ant
</pre>
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:
<pre>
run:
- [java] TRANSACTIONS
+ [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
@@ -354,6 +360,8 @@
</pre>
</p><p>
+You can add accounts and transactions to this example application by editing the
+<tt>input.txt</tt> file.
</p>
</body>
</html>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list