[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] >>> aroundDefaultSignature...
+ [java] >>> aroundAnnotatedParam...
+ [java] RUNNING POJO->getIntValue(): return 10
+ [java] <<< aroundAnnotatedParam: returning 5000
+ [java] <<< aroundDefaultSignature: returning invocation.invokeNext()
+ [java] >>> afterOverwriteReturnValue: returning 5000/5
+ [java] >>> afterVoid
+ [java] RECEIVED type:int value:1000
+
+ [java] Calling POJO->getList()
+ [java] =======================
+ [java] >>> aroundDefaultSignature...
+ [java] RUNNING POJO->getList(): return [this, "element2"]
+ [java] <<< aroundDefaultSignature: returning invocation.invokeNext()
+ [java] >>> afterUnmodifiableList: returning list transformed as UnmodifiableList
+ [java] >>> afterVoid
+ [java] RECEIVED type:class java.util.Collections$UnmodifiableRandomAccessList value:[POJO at 152544e, element2]
+
+ [java] Calling POJO->doNothing()
+ [java] =========================
+ [java] >>> aroundDefaultSignature...
+ [java] >>> aroundVoid...
+ [java] RUNNING POJO->doNothing()
+ [java] <<< aroundVoid
+ [java] <<< aroundDefaultSignature: returning invocation.invokeNext()
+ [java] >>> 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