[jboss-cvs] JBossAS SVN: r62855 - in projects/aop/trunk/aop/docs/examples: annotated-parameters and 4 other directories.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Tue May 8 02:12:35 EDT 2007 

Author: flavia.rainone at jboss.com
Date: 2007-05-08 02:12:34 -0400 (Tue, 08 May 2007)
New Revision: 62855

Modified:
   projects/aop/trunk/aop/docs/examples/after-throwing/after-throwing.html
   projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html
   projects/aop/trunk/aop/docs/examples/aspect/aspect.html
   projects/aop/trunk/aop/docs/examples/beforeafter/SynchronizedAspect.java
   projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html
   projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html
   projects/aop/trunk/aop/docs/examples/return-types/return-types.html
Log:
[JBAOP-44] More corrections and refactoring to the examples.

Modified: projects/aop/trunk/aop/docs/examples/after-throwing/after-throwing.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/after-throwing/after-throwing.html	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/after-throwing/after-throwing.html	2007-05-08 06:12:34 UTC (rev 62855)
@@ -7,22 +7,25 @@
 <h4>Overview</h4>
 
 Besides before, after and around advices, you can also write after-throwing advices.
-These advices intercept joinpoints throwing an exception. In this example, we will see
-how to write that type of advices.
+These advices intercept joinpoints throwing an exception. In this example, we will
+see how to write that type of advices, and when they are executed.
 </p><p>
 <h4>Writing After Throwing Advices</h4>
 
 </p><p>
 </p><p>
-After-throwing advices are written using the annotated parameter signature.
+After-throwing advices are written using the
+<a href="../annotated-parameters/annotated-parameters.html">annotated parameter signature</a>.
 The only difference is that these advices feature an additional annotated parameter:
 <tt>@Thrown</tt>. This mandatory parameter will hold the thrown exception.
 So, an after-throwing advice should be of the form:
 </p><p>
 <pre>
-public void &lt;any-method-name&gt;(@Thrown Throwable arg0, @&lt;Annotation&gt; &lt;any type&gt; arg1, @&lt;Annotation&gt; &lt;any type&gt; arg1, ... , @&lt;Annotation&gt; &lt;any type&gt; argN) throws &lt;Exception1&gt;,&lt;Exception2&gt;,...,&lt;ExceptionN&gt;
+public void &lt;any-method-name&gt;(@&lt;Annotation&gt; &lt;any type&gt; arg0, @&lt;Annotation&gt; &lt;any type&gt; arg1, ... @Thrown Throwable argi, ...  @&lt;Annotation&gt; &lt;any type&gt; argN) throws &lt;Exception1&gt;,&lt;Exception2&gt;,...,&lt;ExceptionN&gt;
 </pre>
 </p><p>
+Where 0 &lt;= i &lt;= N.
+</p><p>
 <h4>Binding After Throwing Advices</h4>
 
 </p><p>
@@ -35,7 +38,7 @@
 &lt;/bind&gt;
 </pre>
 </p><p>
-Differently from other advice types, after-throwing advices aren't called everytime
+Differently from other advice types, after-throwing advices are not called everytime
 an intercepted joinpoint gets executed. On the contrary, after-throwing advices are
 invoked only when the joinpoint throws an exception. So, in the binding example
 above, this means that <tt>afterThrowing</tt> will be invoked only after a <tt>POJO</tt> method

Modified: projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/annotated-parameters/annotated-parameters.html	2007-05-08 06:12:34 UTC (rev 62855)
@@ -10,7 +10,7 @@
 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
+that is most suitable to the advice functionality, according to the joinpoints it
 intercepts.
 </p><p>
 <h4>Annotated Parameter Signature</h4>
@@ -32,8 +32,8 @@
 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
+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>
@@ -64,8 +64,8 @@
 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 <tt>org.jboss.aop.advice.annotation</tt> package.
+that can be used by before, after and around advices to identify those values. 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
 to. For example, suppose you are intercepting a jointpoint with an argument of type
@@ -76,9 +76,9 @@
 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
+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 <tt>"before"</tt>, and so on). It is also important
+(before advice names start with <tt>"before"</tt>, and so on). But it is 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>
@@ -111,8 +111,8 @@
 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, and static field reads
-and writes don't have a target.
+joinpoints have a target; namelly: static method executions and calls, static field
+reads and writes, and constructor executions and calls.
 </p><p>
 Examples of usage of this annotation follow:
 </p><p>
@@ -204,8 +204,9 @@
 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:
+Associating the <tt>int</tt> value to to an argument of
+<tt>POJO.method(long,int,long,String)</tt> is easy, because there is only one joinpoint
+argument of that type. The same does not apply to the following advice:
 </p><p>
 <pre>
 public void beforeMethodArg(@Arg long argument)
@@ -238,7 +239,7 @@
 </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
+</tt> instead of a list of <tt>@Arg</tt> annotated parameters is also 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>
@@ -256,8 +257,14 @@
 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.
-&lt;h4&gt;Run the example&lt;/h4&gt;
 </p><p>
+Needless to say, extreme care is needed when changing the arguments array. If an
+argument value is overriden with one of a different type, an error will be thrown.
+</p><p>
+</p><p>
+<h3>Run the example</h3>
+
+</p><p>
 <b>THIS EXAMPLE REQUIRES JDK 1.5!!</b> To compile and run:
 <pre>
   $ ant

Modified: projects/aop/trunk/aop/docs/examples/aspect/aspect.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/aspect/aspect.html	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/aspect/aspect.html	2007-05-08 06:12:34 UTC (rev 62855)
@@ -18,7 +18,7 @@
   public Object &lt;any-method-name&gt;(&lt;any Invocation type&gt;) Throwable
 </pre>
 </p><p>
-You can also overload methods.  
+You can also <a href="../overloaded-advices/overloaded-advices.html">overload methods</a>.  
 </p><p>
 <h4>Scope and XML definitions</h4>
 

Modified: projects/aop/trunk/aop/docs/examples/beforeafter/SynchronizedAspect.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/SynchronizedAspect.java	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/SynchronizedAspect.java	2007-05-08 06:12:34 UTC (rev 62855)
@@ -28,7 +28,7 @@
    {
       Object result;
 
-      // part 1: retrive lock before joinpoint execution
+      // part 1: retrieve lock before joinpoint execution
       synchronized(this)
       {
          System.out.println("&gt;&gt;&gt; Retrieved concurrency lock");

Modified: projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/beforeafter/beforeafter.html	2007-05-08 06:12:34 UTC (rev 62855)
@@ -22,16 +22,16 @@
 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:
+So, we introduce before and after advices as being of the form:
 </p><p>
 <pre>
 public void &lt;any-method-name&gt;(@JoinPoint &lt;any Joinpoint type&gt;)
 </pre>
 </p><p>
-Differently from around advices and interceptors, throwing a <tt>Throwable</tt> is
-not necessary, because these advices do not wrap a joinpoint.
+Differently from around advices and interceptors, throwing a <tt>java.lang.Throwable</tt>
+is not necessary, because these advices do not wrap a joinpoint.
 </p><p>
-Instead of <tt>Invocation</tt> instances, before/after advices receive instances
+Instead of <a href="../../misc/invocation.html"><tt>Invocation</tt></a> instances, before/after advices receive instances
 of <a href="../../misc/joinpoint.html"><tt>org.jboss.aop.IJoinpointInfo</tt> and subinterfaces</a>
 as parameters.
 </p><p>
@@ -79,7 +79,7 @@
    {
       Object result;
 
-      // part 1: retrive lock before joinpoint execution
+      // part 1: retrieve lock before joinpoint execution
       synchronized(this)
       {
          System.out.println("&gt;&gt;&gt; Retrieved concurrency lock");
@@ -131,7 +131,7 @@
    {
       Object result;
 
-      // part 1: retrive lock before joinpoint execution
+      // part 1: retrieve lock before joinpoint execution
       synchronized(lock)
       {
          while (locked)
@@ -169,13 +169,15 @@
 </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).
+(getting a lock, proceeding to joinpoint execution, releasing the lock, and returning
+a result).
 </p><p>
 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>
-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 for that, now,
+<tt>MutexAspect.aroundAdvice()</tt> has been splitten into <tt>MutexAspect.beforeAdvice()
 </tt> and <tt>MutexAspect.afterAdvice()</tt>:
 </p><p>
 <pre>
@@ -291,13 +293,13 @@
 concurrently. If we don't synchronize those operations we can end up with an invalid
 account balance.
 </p><p>
-An example would be two operations on account <tt>A</tt>. 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:
+An example would be two operations on account <tt>A</tt>. One of them is a $30.00 deposit,
+while the other one is a $10.00 withdrawal. If these operations are run in an
+unsynchronized manner, like follows:
 </p><p>
 <ul>
-<li> deposit: read balance: $50.00</li>
-<li> withdrawal: read balance: $50.00</li>
+<li> deposit: read initial balance $50.00</li>
+<li> withdrawal: read initial 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>

Modified: projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html	2007-05-08 06:12:34 UTC (rev 62855)
@@ -51,11 +51,12 @@
 </pre>
 </p><p>
 As you can see, <tt>aroundAdvice</tt> is a simple advice that logs constructor and method
-executions, field reads and field writes. Despite that, its implementation doesn't
+executions, field reads and field writes. Despite that, its implementation does not
 look so simple as a logging advice should be. This advice does a check on the
 <tt>invocation</tt> parameter type so it can display the correct message and access
-methods specific to the joinpoint type being intercepted. This can be avoided by
-overloading <tt>aroundAdvice</tt>, so that we have a version for each <tt>Invocation</tt> type:
+methods that are specific to the joinpoint type being intercepted. This can be
+avoided by overloading <tt>aroundAdvice</tt>, so that we have a version for each
+<tt>Invocation</tt> type:
 </p><p>
 <pre>
 public Object aroundAdvice(ConstructorInvocation invocation) throws Throwable
@@ -121,7 +122,7 @@
 &lt;/bind&gt;
 </pre>
 </p><p>
-Notice that <tt>IFieldInfo</tt> is used fro both field read and write joinpoints. The
+Notice that <tt>IFieldInfo</tt> is used for both field read and write joinpoints. The
 <tt>otherTypeOfAdvice</tt> advice is applied as a before advice in the example. However,
 it could have been applied as an after advice, or a finally advice. And it could
 also have been applied as an after-throwing advice if we added a <tt>@Thrown</tt>
@@ -165,7 +166,7 @@
 </pre>
 </p><p>
 <tt>MixedParametersAspect.overloadedAdvice()</tt> has five different versions, and each one
-receives different parameter types. In that case, JBoss AOP will try to find the most
+receives different parameter types. In this scenario, JBoss AOP will select the most
 appropriate version for each case.
 </p><p>
 Run the example to see how this advice is applied to the different POJO joinpoints.

Modified: projects/aop/trunk/aop/docs/examples/return-types/return-types.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/return-types.html	2007-05-08 06:10:55 UTC (rev 62854)
+++ projects/aop/trunk/aop/docs/examples/return-types/return-types.html	2007-05-08 06:12:34 UTC (rev 62855)
@@ -5,17 +5,19 @@
 
 </p><p>
 <h4>Overview</h4>
+
 Around and after advices can return values and overwrite the joinpoint value. In
 this example we show how to do that.
 </p><p>
 <h4>Default Signature</h4>
+
 </p><p>
 This signature, for around advices only, demands a <tt>java.lang.Object</tt> return
 type.
-Notice that this signature is valid for any joipoints, no matter whether it has a
+Notice that this signature is valid for any joipoint, no matter whether it has a
 return value, and, if it does, whether this value is primitive or not (a wrapper
 object is expected if the joinpoint returns a primitive value).
-<p>
+</p><p>
 An example of this signature is <tt>Aspect.aroundDefaultSignature()</tt> advice:
 </p><p>
 <pre>
@@ -26,23 +28,24 @@
 a method that returns a primitive value, a method that returns a non-primitive value,
 and a <tt>void</tt> method.
 </p><p>
-
+</p><p>
 <h4>Annotated-Parameter Signature</h4>
 
 </p><p>
+</p><p>
 In this signature, return types are safely checked. Differently than the default
 signature, an advice can't return an invalid typed value. For example, by declaring
-to return <tt>java.lang.Object</tt> when the joinpoint return type is <tt>
-java.util.Collection</tt>, an advice could return a <tt>java.lang.String</tt> value
-(this would result in a <tt>RuntimeException</tt>).
+to return <tt>java.lang.Object</tt> when the joinpoint return type is
+<tt>java.util.Collection</tt>, an advice could return a <tt>java.lang.String</tt> value (this
+would result in a <tt>RuntimeException</tt>).
 When using annotated-parameter signature, this code wouldn't compile.
 In that case, an advice could, however, return a <tt>java.util.List</tt> typed value,
 since this class is a subtype of the joinpoint return type.
 </p><p>
-
-<h5>Around Advices</h5>
-
-When using an annotated-parameter signature, around advices are obligated to return
+</p><p>
+<b>Around Advices</b>
+</p><p>
+When using an annotated-parameter signature, around advices are obliged to return
 a value. This is pretty much the same as with the default signature. However, here
 it must return a value with the same type as the joinpoint return value, or a subtype.
 Notice that, if the joinpoint return type is <tt>void</tt>, the around advice should
@@ -73,12 +76,12 @@
 }
 </pre>
 </p><p>
-This advice intercepts a method whose return type is <tt>java.util.List</tt> and, so,
-its return type is valid. It wouldn't be valid if it was a superclass of <tt>
-java.util.List</tt>, like <tt>java.util.Collection</tt>. This avoids the advice
-returning a <tt>java.util.Vector</tt>, for example, when the joinpoint return value
-is expected to be of type <tt>java.util.List</tt>.
-</p></p>
+This advice intercepts a method whose return type is <tt>java.util.List</tt> and, so, its
+return type is valid. It wouldn't be valid if it was a superclass of
+<tt>java.util.List</tt>, like <tt>java.util.Collection</tt>. This avoids the advice returning a
+<tt>java.util.Vector</tt>, for example, when the joinpoint return value is expected to be
+of type <tt>java.util.List</tt>.
+</p><p>
 Finally, take a look at <tt>aroundVoid</tt>:
 </p><p>
 <pre>
@@ -93,11 +96,11 @@
 would also be the case of a <tt>void</tt> method call, or a field read/write
 joinpoint.
 </p><p>
-
-<h5>After Advices</h5>
-
 </p><p>
-Different than around advices, after advices are not forced to return a value.
+<b>After Advices</b>
+</p><p>
+</p><p>
+Differently from around advices, after advices are not forced to return a value.
 They should return it only when they intend to replace the joinpoint value.
 </p><p>
 Let's take a look at a few examples;
@@ -110,7 +113,7 @@
 }
 </pre>
 </p><p>
-This advice is applied to a joinpoit that returns an <tt>int</tt> value. Notice that it
+This advice is applied to a joinpoint that returns an <tt>int</tt> value. Notice that it
 receives the value returned by the joinpoint (or by an advice that has executed
 before this one, if there are other advices involved), and returns one fifith of its
 value.
@@ -127,7 +130,7 @@
 </p><p>
 Intercepts <tt>POJO.getList()</tt> method, that returns a <tt>java.util.List</tt>
 object. The same return type is used by this advice, that overwrites the joinpoint
-return value with an unmodified version of the original list.
+return value with an unmodifiable version of the original list.
 </p><p>
 Since after advices are not enforced to return values, <tt>afterVoid</tt> advice, of
 type <tt>void</tt>, can be used to intercept any joinpoint, no matter wheter the
@@ -140,8 +143,9 @@
 }
 </pre>
 </p><p>
+</p><p>
+<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>
@@ -151,31 +155,31 @@
 then finally run the example.  The output should read as follows:
 <pre>
 run:
-     [java] Calling POJO->getIntValue()
+     [java] Calling POJO-&gt;getIntValue()
      [java] ===========================
      [java] &gt;&gt;&gt; aroundDefaultSignature...
      [java] &gt;&gt;&gt; aroundAnnotatedParam...
-     [java] RUNNING POJO->getIntValue(): return 10
+     [java] RUNNING POJO-&gt;getIntValue(): return 10
      [java] &lt;&lt;&lt; aroundAnnotatedParam: returning 5000
      [java] &lt;&lt;&lt; aroundDefaultSignature: returning invocation.invokeNext()
      [java] &gt;&gt;&gt; afterOverwriteReturnValue: returning 5000/5
      [java] &gt;&gt;&gt; afterVoid
      [java] RECEIVED type:int value:1000
 
-     [java] Calling POJO->getList()
+     [java] Calling POJO-&gt;getList()
      [java] =======================
      [java] &gt;&gt;&gt; aroundDefaultSignature...
-     [java] RUNNING POJO->getList(): return [this, "element2"]
+     [java] RUNNING POJO-&gt;getList(): return [this, "element2"]
      [java] &lt;&lt;&lt; aroundDefaultSignature: returning invocation.invokeNext()
      [java] &gt;&gt;&gt; afterUnmodifiableList: returning list transformed as UnmodifiableList
      [java] &gt;&gt;&gt; afterVoid
      [java] RECEIVED type:class java.util.Collections$UnmodifiableRandomAccessList value:[POJO at 152544e, element2]
 
-     [java] Calling POJO->doNothing()
+     [java] Calling POJO-&gt;doNothing()
      [java] =========================
      [java] &gt;&gt;&gt; aroundDefaultSignature...
      [java] &gt;&gt;&gt; aroundVoid...
-     [java] RUNNING POJO->doNothing()
+     [java] RUNNING POJO-&gt;doNothing()
      [java] &lt;&lt;&lt; aroundVoid
      [java] &lt;&lt;&lt; aroundDefaultSignature: returning invocation.invokeNext()
      [java] &gt;&gt;&gt; afterVoid
@@ -183,8 +187,6 @@
 
 </pre> 
 </p><p>
-</p><p>
-</p><p>
 </p>
 </body>
-</html>
\ No newline at end of file
+</html>

More information about the jboss-cvs-commits mailing list