[jboss-cvs] JBossAS SVN: r62120 - in projects/aop/trunk/aop/docs/examples: return-types and 1 other directory.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Thu Apr 5 00:52:39 EDT 2007


Author: flavia.rainone at jboss.com
Date: 2007-04-05 00:52:39 -0400 (Thu, 05 Apr 2007)
New Revision: 62120

Added:
   projects/aop/trunk/aop/docs/examples/return-types/
   projects/aop/trunk/aop/docs/examples/return-types/Aspect.java
   projects/aop/trunk/aop/docs/examples/return-types/Driver.java
   projects/aop/trunk/aop/docs/examples/return-types/POJO.java
   projects/aop/trunk/aop/docs/examples/return-types/build.xml
   projects/aop/trunk/aop/docs/examples/return-types/jboss-aop.xml
   projects/aop/trunk/aop/docs/examples/return-types/return-types.html
Log:
[JBAOP-44] Third before/after example. This one talks about advice return types.

Added: projects/aop/trunk/aop/docs/examples/return-types/Aspect.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/Aspect.java	                        (rev 0)
+++ projects/aop/trunk/aop/docs/examples/return-types/Aspect.java	2007-04-05 04:52:39 UTC (rev 62120)
@@ -0,0 +1,84 @@
+/*
+* JBoss, Home of Professional Open Source
+* Copyright 2005, JBoss Inc., and individual contributors as indicated
+* by the @authors tag. See the copyright.txt in the distribution for a
+* full listing of individual contributors.
+*
+* This is free software; you can redistribute it and/or modify it
+* under the terms of the GNU Lesser General Public License as
+* published by the Free Software Foundation; either version 2.1 of
+* the License, or (at your option) any later version.
+*
+* This software is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+* Lesser General Public License for more details.
+*
+* You should have received a copy of the GNU Lesser General Public
+* License along with this software; if not, write to the Free
+* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+*/
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import org.jboss.aop.MethodInfo;
+
+import org.jboss.aop.advice.annotation.JoinPoint;
+import org.jboss.aop.advice.annotation.Return;
+
+import org.jboss.aop.joinpoint.MethodInvocation;
+
+public class Aspect
+{
+   public Object aroundDefaultSignature(MethodInvocation invocation) throws Throwable
+   {
+      System.out.println(">>> aroundDefaultSignature...");
+      Object returnValue = invocation.invokeNext();
+      System.out.println("<<< aroundDefaultSignature: returning invocation.invokeNext()");
+      return returnValue;
+   }
+   
+   public int aroundAnnotatedParam(@JoinPoint MethodInvocation invocation) throws Throwable
+   {
+      System.out.println(">>> aroundAnnotatedParam...");
+      Object result = invocation.invokeNext();
+      System.out.println("<<< aroundAnnotatedParam: returning 5000");
+      return  5000;
+   }
+   
+   public int afterOverwriteReturnValue(@Return int returnValue)
+   {
+      System.out.println(">>> afterOverwriteReturnValue: returning " + returnValue + "/5");
+      return returnValue/5;
+   }
+   
+   public void afterVoid()
+   {
+      System.out.println(">>> afterVoid");
+   }
+   
+   public ArrayList aroundArrayList(@JoinPoint MethodInvocation invocation) throws Throwable
+   {
+      System.out.println(">>> aroundArrayList...");
+      ArrayList list = (ArrayList) invocation.invokeNext();
+      list.add("aroundCollection advice added this");
+      System.out.println("<<< aroundArrayList: returning invocation.invokeNext() with new element added");
+      return list;
+   }
+   
+   public List afterUnmodifiableList(@Return List returnValue)
+   {
+      System.out.println(">>> afterUnmodifiableList: returning list transformed as UnmodifiableList");
+      return Collections.unmodifiableList(returnValue);
+   }
+   
+   public void aroundVoid(@JoinPoint MethodInvocation invocation) throws Throwable
+   {
+      System.out.println(">>> aroundVoid...");
+      invocation.invokeNext();
+      System.out.println("<<< aroundVoid");
+   }
+}
\ No newline at end of file

Added: projects/aop/trunk/aop/docs/examples/return-types/Driver.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/Driver.java	                        (rev 0)
+++ projects/aop/trunk/aop/docs/examples/return-types/Driver.java	2007-04-05 04:52:39 UTC (rev 62120)
@@ -0,0 +1,46 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2005, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+
+import java.util.Iterator;
+import java.util.List;
+
+public class Driver
+{
+   public static void main(String[] args) throws Exception
+   {
+      POJO pojo = new POJO();
+      
+      System.out.println("\nCalling POJO->getIntValue()");
+      System.out.println("===========================");
+      System.out.println("RECEIVED type:int value:" + pojo.getIntValue());;
+      
+      System.out.println("\nCalling POJO->getList()");
+      System.out.println("=======================");
+      List list = pojo.getList();
+      System.out.println("RECEIVED type:" + list.getClass() + " value:" + list); 
+ 
+      System.out.println("\nCalling POJO->doNothing()");
+      System.out.println("=========================");
+      pojo.doNothing();
+      System.out.println("RECEIVED nothing");
+   }
+}
\ No newline at end of file

Added: projects/aop/trunk/aop/docs/examples/return-types/POJO.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/POJO.java	                        (rev 0)
+++ projects/aop/trunk/aop/docs/examples/return-types/POJO.java	2007-04-05 04:52:39 UTC (rev 62120)
@@ -0,0 +1,47 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2005, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
+ */
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class POJO
+{
+   public int getIntValue()
+   {
+      System.out.println("RUNNING POJO->getIntValue(): return 10");
+      return 10;
+   }
+   
+   public List getList()
+   {
+      System.out.println("RUNNING POJO->getList(): return [this, \"element2\"]" );
+      List list = new ArrayList();
+      list.add(this);
+      list.add("element2");
+      return list;
+   }
+   
+   public void doNothing()
+   {
+      System.out.println("RUNNING POJO->doNothing()");
+   }
+}
\ No newline at end of file

Added: projects/aop/trunk/aop/docs/examples/return-types/build.xml
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/build.xml	                        (rev 0)
+++ projects/aop/trunk/aop/docs/examples/return-types/build.xml	2007-04-05 04:52:39 UTC (rev 62120)
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project default="run" name="JBoss/AOP">
+   <target name="prepare">
+      <property name="jboss.aop.root" value="../../../.."/>
+      <property name="jboss.aop.lib" value="${jboss.aop.root}/lib"/>
+      <property name="jboss.aop.lib50" value="${jboss.aop.root}/lib-50"/>
+ 
+      <path id="jboss.aop.classpath">
+         <fileset dir="${jboss.aop.lib}">
+            <include name="*.jar"/>
+         </fileset>
+      </path>
+
+      <path id="jboss.aop.classpath50">
+         <fileset dir="${jboss.aop.lib50}">
+            <include name="*.jar"/>
+         </fileset>
+      </path>
+
+      <path id="classpath">
+         <path refid="jboss.aop.classpath"/>
+         <pathelement path="."/>
+      </path>
+	  
+      <property name="aop50jar" value="${jboss.aop.lib50}/jboss-aop-jdk50.jar"/>
+
+      <path id="classpath50">
+         <path refid="jboss.aop.classpath50"/>
+         <pathelement path="."/>
+      </path>
+
+      <taskdef name="aopc" classname="org.jboss.aop.ant.AopC" classpathref="jboss.aop.classpath"/>
+   </target>
+
+
+   <target name="compile" depends="prepare">
+      <javac srcdir="."
+         destdir="."
+         debug="on"
+         deprecation="on"
+         optimize="off"
+         includes="**">
+        <classpath refid="classpath50"/>
+      </javac>
+      <aopc compilerclasspathref="classpath50" classpathref="classpath50" verbose="true">
+         <sysproperty key="jboss.aop.path" value="jboss-aop.xml"/>
+         <sysproperty key="jboss.aop.verbose" value="true"/>
+         <classpath path="."/>
+         <src path="."/>
+         <aoppath path="jboss-aop.xml"/>
+      </aopc>
+   </target>
+
+   <target name="run" depends="compile">
+      <java fork="yes" failOnError="true" className="Driver">
+         <sysproperty key="jboss.aop.path" value="jboss-aop.xml"/>
+         <classpath refid="classpath"/>
+      </java>
+   </target>
+
+   <target name="compile50standalone" depends="prepare">
+      <javac srcdir="."
+         destdir="."
+         debug="on"
+         deprecation="on"
+         optimize="off"
+         includes="**">
+         <classpath refid="classpath50"/>
+      </javac>
+   </target>
+
+   <target name="run.50.instrumented" depends="compile50standalone">
+      <java fork="yes" failOnError="true" className="Driver">
+         <sysproperty key="jboss.aop.path" value="jboss-aop.xml"/>
+         <sysproperty key="jboss.aop.instrumentor" value="org.jboss.aop.instrument.GeneratedAdvisorInstrumentor"/>
+         <jvmarg value="-javaagent:${aop50jar}"/>
+         <classpath refid="classpath50"/>
+      </java>
+   </target>
+
+</project>

Added: projects/aop/trunk/aop/docs/examples/return-types/jboss-aop.xml
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/jboss-aop.xml	                        (rev 0)
+++ projects/aop/trunk/aop/docs/examples/return-types/jboss-aop.xml	2007-04-05 04:52:39 UTC (rev 62120)
@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<aop>
+
+   <aspect class="Aspect" scope="PER_VM"/>
+
+   <bind pointcut="execution(int POJO->*())">
+      <advice name="aroundDefaultSignature" aspect="Aspect"/>
+      <advice name="aroundAnnotatedParam" aspect="Aspect"/>
+      <after name="afterOverwriteReturnValue" aspect="Aspect"/>
+      <after name="afterVoid" aspect="Aspect"/>
+   </bind>
+   
+   <bind pointcut="execution(java.util.List POJO->*())">
+      <advice name="aroundDefaultSignature" aspect="Aspect"/>
+      <advice name="aroundCollection" aspect="Aspect"/>
+      <after name="afterUnmodifiableList" aspect="Aspect"/>
+      <after name="afterVoid" aspect="Aspect"/>
+   </bind>
+   
+   <bind pointcut="execution(void POJO->*())">
+      <advice name="aroundDefaultSignature" aspect="Aspect"/>
+      <advice name="aroundVoid" aspect="Aspect"/>
+      <after name="afterVoid" aspect="Aspect"/>
+   </bind>
+   
+</aop>
\ No newline at end of file

Added: projects/aop/trunk/aop/docs/examples/return-types/return-types.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/return-types/return-types.html	                        (rev 0)
+++ projects/aop/trunk/aop/docs/examples/return-types/return-types.html	2007-04-05 04:52:39 UTC (rev 62120)
@@ -0,0 +1,190 @@
+<html>
+<body>
+<p>
+<h2>Advice Return Types</h2>
+
+</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
+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>
+An example of this signature is <tt>Aspect.aroundDefaultSignature()</tt> advice:
+</p><p>
+<pre>
+public Object aroundDefaultSignature(MethodInvocation invocation) throws Throwable
+</pre>
+</p><p>
+Open up <tt>jboss-aop.xml</tt> and verify that this advice is applied to
+a method that returns a primitive value, a method that returns a non-primitive value,
+and a <tt>void</tt> method.
+</p><p>
+
+<h4>Annotated-Parameter Signature</h4>
+
+</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>).
+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
+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
+be <tt>void</tt> too.
+</p><p>
+To illustrate all this, let's look at the around advices contained in this example,
+by starting with this one:
+</p><p>
+<pre>
+public int aroundAnnotatedParam(@JoinPoint MethodInvocation invocation) throws Throwable
+{
+   ...
+   return  5000;
+}
+</pre>
+</p><p>
+<tt>Aspect.aroundAnnotatedParam()</tt> advice overwrites the method return value
+with the <tt>5000 int</tt> value. This advice intercepts a method that returns an
+<tt>int</tt> value, and has the same return type as it.
+</p><p>
+On the other hand, <tt>Aspect.aroundArrayList()</tt> does not return the same type
+of the joinpoint it intercepts. It returns a subtype instead:
+</p><p>
+<pre>
+public ArrayList aroundArrayList(@JoinPoint MethodInvocation invocation) throws Throwable
+{
+	...
+}
+</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>
+Finally, take a look at <tt>aroundVoid</tt>:
+</p><p>
+<pre>
+public void aroundVoid(@JoinPoint MethodInvocation invocation) throws Throwable
+{
+   ...
+}
+</pre>
+</p><p>
+This advice is <tt>void</tt> and can be applied only to joinpoints that don't return
+values. This is the case of <tt>void POJO.doNothing()</tt> method execution, and it
+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.
+They should return it only when they intend to replace the joinpoint value.
+</p><p>
+Let's take a look at a few examples;
+</p><p>
+<pre>
+public int afterOverwriteReturnValue(@Return int returnValue)
+{
+	...
+	return returnValue/5;
+}
+</pre>
+</p><p>
+This advice is applied to a joinpoit 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.
+</p><p>
+Our next advice:
+</p><p>
+<pre>
+public List afterUnmodifiableList(@Return List returnValue)
+{
+	...
+   return Collections.unmodifiableList(returnValue);
+}
+</pre>
+</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.
+</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
+joinpoint has a return value or not:
+</p><p>
+<pre>
+public void afterVoid()
+{
+   ...
+}
+</pre>
+</p><p>
+
+<h4>Run the example</h4>
+</p><p>
+<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 read as follows:
+<pre>
+run:
+     [java] Calling POJO->getIntValue()
+     [java] ===========================
+     [java] &gt;&gt;&gt; aroundDefaultSignature...
+     [java] &gt;&gt;&gt; aroundAnnotatedParam...
+     [java] RUNNING POJO->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] =======================
+     [java] &gt;&gt;&gt; aroundDefaultSignature...
+     [java] RUNNING POJO->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] =========================
+     [java] &gt;&gt;&gt; aroundDefaultSignature...
+     [java] &gt;&gt;&gt; aroundVoid...
+     [java] RUNNING POJO->doNothing()
+     [java] &lt;&lt;&lt; aroundVoid
+     [java] &lt;&lt;&lt; aroundDefaultSignature: returning invocation.invokeNext()
+     [java] &gt;&gt;&gt; afterVoid
+     [java] RECEIVED nothing
+
+</pre> 
+</p><p>
+</p><p>
+</p><p>
+</p>
+</body>
+</html>
\ No newline at end of file




More information about the jboss-cvs-commits mailing list