[jboss-cvs] JBossAS SVN: r62182 - in projects/aop/trunk/aop/docs/examples: overloaded-advices and 1 other directory.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Apr 9 01:33:00 EDT 2007
Author: flavia.rainone at jboss.com
Date: 2007-04-09 01:32:59 -0400 (Mon, 09 Apr 2007)
New Revision: 62182
Added:
projects/aop/trunk/aop/docs/examples/overloaded-advices/
projects/aop/trunk/aop/docs/examples/overloaded-advices/Driver.java
projects/aop/trunk/aop/docs/examples/overloaded-advices/JoinPointAspect.java
projects/aop/trunk/aop/docs/examples/overloaded-advices/MixedParametersAspect.java
projects/aop/trunk/aop/docs/examples/overloaded-advices/POJO.java
projects/aop/trunk/aop/docs/examples/overloaded-advices/build.xml
projects/aop/trunk/aop/docs/examples/overloaded-advices/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] Overloaded advices example.
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/Driver.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/Driver.java (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/Driver.java 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,61 @@
+/*
+ * 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.
+ */
+
+public class Driver
+{
+ public void runExample()
+ {
+ System.out.println("\nCalling POJO constructor");
+ System.out.println("========================");
+ POJO pojo = new POJO();
+
+ System.out.println("\nSetting POJO->intField with 1751 value");
+ System.out.println("======================================");
+ pojo.intField = 1751;
+
+ System.out.println("\nReading POJO->intField value");
+ System.out.println("============================");
+ int myIntValue = pojo.intField;
+
+ System.out.println("\nSetting POJO->stringField with \"text\" value");
+ System.out.println("===========================================");
+ pojo.stringField = "text";
+
+ System.out.println("\nReading POJO->stringField value");
+ System.out.println("===============================");
+ String myStringValue = pojo.stringField;
+
+ System.out.println("\nCalling POJO->voidMethod()");
+ System.out.println("==========================");
+ pojo.voidMethod();
+
+ System.out.println("\nCalling POJO->methodWithStringArg()");
+ System.out.println("===================================");
+ pojo.methodWithStringArg("stringArg");
+ }
+
+ public static void main(String[] args) throws Exception
+ {
+ Driver driver = new Driver();
+ driver.runExample();
+ }
+}
\ No newline at end of file
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/JoinPointAspect.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/JoinPointAspect.java (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/JoinPointAspect.java 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,81 @@
+/*
+* 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 org.jboss.aop.advice.annotation.JoinPoint;
+
+import org.jboss.aop.joinpoint.ConstructorInvocation;
+import org.jboss.aop.joinpoint.FieldReadInvocation;
+import org.jboss.aop.joinpoint.FieldWriteInvocation;
+import org.jboss.aop.joinpoint.IConstructorInfo;
+import org.jboss.aop.joinpoint.IFieldInfo;
+import org.jboss.aop.joinpoint.IMethodInfo;
+import org.jboss.aop.joinpoint.MethodInvocation;
+
+public class JoinPointAspect
+{
+ public Object aroundAdvice(ConstructorInvocation invocation) throws Throwable
+ {
+ System.out.println(">>> aroundAdvice on constructor of class: " +
+ invocation.getConstructor().getDeclaringClass().getName());
+ return invocation.invokeNext();
+ }
+
+ public Object aroundAdvice(MethodInvocation invocation) throws Throwable
+ {
+ System.out.println(">>> aroundAdvice on method execution: " +
+ invocation.getMethod().getName());
+ return invocation.invokeNext();
+ }
+
+ public Object aroundAdvice(FieldReadInvocation invocation) throws Throwable
+ {
+ System.out.println(">>> aroundAdvice on field read: " +
+ invocation.getField().getName());
+ return invocation.invokeNext();
+ }
+
+ public Object aroundAdvice(FieldWriteInvocation invocation) throws Throwable
+ {
+ System.out.println(">>> aroundAdvice on field write: " +
+ invocation.getField().getName());
+ return invocation.invokeNext();
+ }
+
+ public void otherTypeOfAdvice(@JoinPoint IConstructorInfo joinPoint)
+ {
+ System.out.println(">>> otherTypeOfAdvice on constructor of class: " +
+ joinPoint.getConstructor().getDeclaringClass().getName());
+ }
+
+ public void otherTypeOfAdvice(@JoinPoint IMethodInfo joinPoint)
+ {
+ System.out.println(">>> otherTypeOfAdvice on method execution: " +
+ joinPoint.getAdvisedMethod().getName());
+ }
+
+ public void otherTypeOfAdvice(@JoinPoint IFieldInfo joinPoint)
+ {
+ System.out.println(">>> otherTypeOfAdvice on field" +
+ (joinPoint.isRead()? "read: ": "write: ") +
+ joinPoint.getAdvisedField().getName());
+ }
+}
\ No newline at end of file
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/MixedParametersAspect.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/MixedParametersAspect.java (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/MixedParametersAspect.java 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,59 @@
+/*
+* 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 org.jboss.aop.advice.annotation.Arg;
+import org.jboss.aop.advice.annotation.Caller;
+import org.jboss.aop.advice.annotation.JoinPoint;
+import org.jboss.aop.advice.annotation.Target;
+
+import org.jboss.aop.joinpoint.IConstructorInfo;
+import org.jboss.aop.joinpoint.IJoinPointInfo;
+import org.jboss.aop.joinpoint.ICallerMethodInfo;
+
+public class MixedParametersAspect
+{
+ public int overloadedAdvice(@Target POJO target)
+ {
+ System.out.println(">>> overloadedAdvice: int(Target POJO)");
+ return 0;
+ }
+
+ public void overloadedAdvice(@JoinPoint IConstructorInfo joinPoint)
+ {
+ System.out.println(">>> overloadedAdvice: (JoinPoint IConstructorInfo)");
+ }
+
+ public void overloadedAdvice(@Target Object target)
+ {
+ System.out.println(">>> overloadedAdvice: (Target Object)");
+ }
+
+ public void overloadedAdvice(@JoinPoint ICallerMethodInfo joinPoint, @Caller Driver driver)
+ {
+ System.out.println(">>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)");
+ }
+
+ public void overloadedAdvice(@JoinPoint IJoinPointInfo joinPoint, @Arg String arg)
+ {
+ System.out.println(">>> overloadedAdvice: JoinPoint IJoinPoint, Arg String");
+ }
+}
\ No newline at end of file
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/POJO.java
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/POJO.java (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/POJO.java 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,37 @@
+/*
+ * 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.
+ */
+
+public class POJO
+{
+ public int intField;
+ public String stringField;
+
+ public void voidMethod()
+ {
+ System.out.println("RUNNING POJO->voidMethod()");
+ }
+
+ public void methodWithStringArg(String arg)
+ {
+ System.out.println("RUNNING POJO->methodWithStringArg(\"" + arg + "\")");
+ }
+}
\ No newline at end of file
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/build.xml
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/build.xml (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/build.xml 2007-04-09 05:32:59 UTC (rev 62182)
@@ -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/overloaded-advices/jboss-aop.xml
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/jboss-aop.xml (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/jboss-aop.xml 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<aop>
+
+ <aspect class="JoinPointAspect" scope="PER_VM"/>
+
+ <bind pointcut="all(POJO)">
+ <before name="otherTypeOfAdvice" aspect="JoinPointAspect"/>
+ <advice name="aroundAdvice" aspect="JoinPointAspect"/>
+ </bind>
+
+ <aspect class="MixedParametersAspect" scope="PER_VM"/>
+
+ <bind pointcut="all(POJO) or call(* POJO->*(..))">
+ <after name="overloadedAdvice" aspect="MixedParametersAspect"/>
+ </bind>
+
+</aop>
\ No newline at end of file
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.html 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,237 @@
+<html>
+<body>
+<p>
+<h2>Overloaded Advices</h2>
+
+</p><p>
+<h4>Overview</h4>
+
+In previous examples, we have seen that JBoss AOP supports different types of advices
+and that those can have several signatures. In this example, we will show
+how to expand that flexibility by binding pointcuts to overloaded advices.
+</p><p>
+<h4>Overloaded Advices vs. Nested If-Else Statements</h4>
+
+</p><p>
+Overloaded advices can be useful to avoid nested if-else statements.
+Look at this version of <tt>JoinPointAspect.aroundAdvice</tt>:
+</p><p>
+<pre>
+public void aroundAdvice(Invocation invocation) throws Throwable
+{
+ if (invocation instanceof ConstructorInvocation)
+ {
+ System.out.println(">>> aroundAdvice on constructor of class: " +
+ invocation.getConstructor().getDeclaringClass().getName());
+ }
+ else if (invocation instanceof MethodInvocation)
+ {
+ System.out.println(">>> aroundAdvice on method execution: " +
+ invocation.getMehod().getName());
+ }
+ else if (invocation instanceof FieldReadInvocation)
+ {
+ System.out.println(">>> aroundAdvice on field read: " +
+ invocation.getField().getName());
+ }
+ else if (invocation instanceof FieldWriteInvocation)
+ {
+ System.out.println(">>> aroundAdvice on field write: " +
+ invocation.getField().getName());
+
+ }
+ return invocation.invokeNext();
+}
+
+___________________________
+
+<bind pointcut="all(POJO)">
+ <advice name="aroundAdvice" aspect="JoinPointAspect"/>
+</bind>
+</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
+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:
+</p><p>
+<pre>
+public Object aroundAdvice(ConstructorInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on constructor of class: " +
+ invocation.getConstructor().getDeclaringClass().getName());
+ return invocation.invokeNext();
+}
+
+public Object aroundAdvice(MethodInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on method execution: " +
+ invocation.getMethod().getName());
+ return invocation.invokeNext();
+}
+
+public Object aroundAdvice(FieldReadInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on field read: " +
+ invocation.getField().getName());
+ return invocation.invokeNext();
+}
+
+public Object aroundAdvice(FieldWriteInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on field write: " +
+ invocation.getField().getName());
+ return invocation.invokeNext();
+}
+</pre>
+</p><p>
+The code above is much more cleaner, and now we can see more clearly that <tt>aroundAdvice</tt>
+just logs messages regarding the joinpoint being intercepted. Besides, using
+overloaded advices is more efficient than using nested if-else statements. JBoss AOP
+will call the correct advice version for each joinpoint type, avoiding the cost
+of checking the invocation type everytime this advice is invoked.
+</p><p>
+This example could also be applied to another type of advice with minor changes:
+<pre>
+public void otherTypeOfAdvice(@JoinPoint IConstructorInfo joinPoint)
+{
+ System.out.println(">>> otherTypeOfAdvice on constructor of class: " +
+ joinPoint.getConstructor().getDeclaringClass().getName());
+}
+
+public void otherTypeOfAdvice(@JoinPoint IMethodInfo joinPoint)
+{
+ System.out.println(">>> otherTypeOfAdvice on method execution: " +
+ joinPoint.getAdvisedMethod().getName());
+}
+
+public void otherTypeOfAdvice(@JoinPoint IFieldInfo joinPoint)
+{
+ System.out.println(">>> otherTypeOfAdvice on field" +
+ (joinPoint.isRead()? "read: ": "write: ") +
+ joinPoint.getAdvisedField().getName());
+}
+
+___________________________
+
+<bind pointcut="all(POJO)">
+ <before name="otherTypeOfAdvice" aspect="JoinPointAspect"/>
+</bind>
+</pre>
+</p><p>
+Notice that <tt>IFieldInfo</tt> is used fro 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>
+parameter to all overloaded versions of this advice.
+</p><p>
+You can find the overloaded implementations of <tt>aroundAdvice</tt> and
+<tt>otherTypeOfAdvice</tt> in the <tt>JoinPointAspect.java</tt> file.
+</p><p>
+<h4> Mixing Different Parameters</h4>
+
+</p><p>
+Besides the previous examples, you can write overloaded advices using different
+return types and annotated parameters. Look at the following overloaded advice:
+</p><p>
+<pre>
+public int overloadedAdvice(@Target POJO target)
+{
+ System.out.println(">>> overloadedAdvice: int(Target POJO)");
+ return 0;
+}
+
+public void overloadedAdvice(@JoinPoint IConstructorInfo joinPoint)
+{
+ System.out.println(">>> overloadedAdvice: (JoinPoint IConstructorInfo)");
+}
+
+public void overloadedAdvice(@Target Object target)
+{
+ System.out.println(">>> overloadedAdvice: (Target Object)");
+}
+
+public void overloadedAdvice(@JoinPoint ICallerMethodInfo joinPoint, @Caller Driver driver)
+{
+ System.out.println(">>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)");
+}
+
+public void overloadedAdvice(@JoinPoint IJoinPointInfo joinPoint, @Arg String arg)
+{
+ System.out.println(">>> overloadedAdvice: JoinPoint IJoinPoint, Arg String");
+}
+</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
+appropriate version for each case.
+</p><p>
+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.
+</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 constructor
+ [java] ========================
+ [java] >>> otherTypeOfAdvice on constructor of class: POJO
+ [java] >>> aroundAdvice on constructor of class: POJO
+ [java] >>> overloadedAdvice: (JoinPoint IConstructorInfo)
+
+ [java] Setting POJO->intField with 1751 value
+ [java] ======================================
+ [java] >>> otherTypeOfAdvice on fieldwrite: intField
+ [java] >>> aroundAdvice on field write: intField
+ [java] >>> overloadedAdvice: int(Target POJO)
+
+ [java] Reading POJO->intField value
+ [java] ============================
+ [java] >>> otherTypeOfAdvice on fieldread: intField
+ [java] >>> aroundAdvice on field read: intField
+ [java] >>> overloadedAdvice: int(Target POJO)
+
+ [java] Setting POJO->stringField with "text" value
+ [java] ===========================================
+ [java] >>> otherTypeOfAdvice on fieldwrite: stringField
+ [java] >>> aroundAdvice on field write: stringField
+ [java] >>> overloadedAdvice: JoinPoint IJoinPoint, Arg String
+
+ [java] Reading POJO->stringField value
+ [java] ===============================
+ [java] >>> otherTypeOfAdvice on fieldread: stringField
+ [java] >>> aroundAdvice on field read: stringField
+ [java] >>> overloadedAdvice: (Target Object)
+
+ [java] Calling POJO->voidMethod()
+ [java] ==========================
+ [java] >>> otherTypeOfAdvice on method execution: voidMethod
+ [java] >>> aroundAdvice on method execution: voidMethod
+ [java] RUNNING POJO->voidMethod()
+ [java] >>> overloadedAdvice: int(Target POJO)
+ [java] >>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)
+
+ [java] Calling POJO->methodWithStringArg()
+ [java] ===================================
+ [java] >>> otherTypeOfAdvice on method execution: methodWithStringArg
+ [java] >>> aroundAdvice on method execution: methodWithStringArg
+ [java] RUNNING POJO->methodWithStringArg("stringArg")
+ [java] >>> overloadedAdvice: JoinPoint IJoinPoint, Arg String
+ [java] >>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)
+</pre>
+</p><p>
+</p>
+</body>
+</html>
Added: projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki
===================================================================
--- projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki (rev 0)
+++ projects/aop/trunk/aop/docs/examples/overloaded-advices/overloaded-advices.wiki 2007-04-09 05:32:59 UTC (rev 62182)
@@ -0,0 +1,226 @@
+!!!Overloaded Advices
+
+!Overview
+In previous examples, we have seen that JBoss AOP supports different types of advices
+and that those can have several signatures. In this example, we will show
+how to expand that flexibility by binding pointcuts to overloaded advices.
+
+!Overloaded Advices vs. Nested If-Else Statements
+
+Overloaded advices can be useful to avoid nested if-else statements.
+Look at this version of {{JoinPointAspect.aroundAdvice}}:
+
+{{{
+public void aroundAdvice(Invocation invocation) throws Throwable
+{
+ if (invocation instanceof ConstructorInvocation)
+ {
+ System.out.println(">>> aroundAdvice on constructor of class: " +
+ invocation.getConstructor().getDeclaringClass().getName());
+ }
+ else if (invocation instanceof MethodInvocation)
+ {
+ System.out.println(">>> aroundAdvice on method execution: " +
+ invocation.getMehod().getName());
+ }
+ else if (invocation instanceof FieldReadInvocation)
+ {
+ System.out.println(">>> aroundAdvice on field read: " +
+ invocation.getField().getName());
+ }
+ else if (invocation instanceof FieldWriteInvocation)
+ {
+ System.out.println(">>> aroundAdvice on field write: " +
+ invocation.getField().getName());
+
+ }
+ return invocation.invokeNext();
+}
+
+___________________________
+
+<bind pointcut="all(POJO)">
+ <advice name="aroundAdvice" aspect="JoinPointAspect"/>
+</bind>
+}}}
+
+As you can see, {{aroundAdvice}} is a simple advice that logs constructor and method
+executions, field reads and field writes. Despite that, its implementation doesn't
+look so simple as a logging advice should be. This advice does a check on the
+{{invocation}} 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 {{aroundAdvice}}, so that we have a version for each {{Invocation}} type:
+
+{{{
+public Object aroundAdvice(ConstructorInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on constructor of class: " +
+ invocation.getConstructor().getDeclaringClass().getName());
+ return invocation.invokeNext();
+}
+
+public Object aroundAdvice(MethodInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on method execution: " +
+ invocation.getMethod().getName());
+ return invocation.invokeNext();
+}
+
+public Object aroundAdvice(FieldReadInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on field read: " +
+ invocation.getField().getName());
+ return invocation.invokeNext();
+}
+
+public Object aroundAdvice(FieldWriteInvocation invocation) throws Throwable
+{
+ System.out.println(">>> aroundAdvice on field write: " +
+ invocation.getField().getName());
+ return invocation.invokeNext();
+}
+}}}
+
+The code above is much more cleaner, and now we can see more clearly that {{aroundAdvice}}
+just logs messages regarding the joinpoint being intercepted. Besides, using
+overloaded advices is more efficient than using nested if-else statements. JBoss AOP
+will call the correct advice version for each joinpoint type, avoiding the cost
+of checking the invocation type everytime this advice is invoked.
+
+This example could also be applied to another type of advice with minor changes:
+{{{
+public void otherTypeOfAdvice(@JoinPoint IConstructorInfo joinPoint)
+{
+ System.out.println(">>> otherTypeOfAdvice on constructor of class: " +
+ joinPoint.getConstructor().getDeclaringClass().getName());
+}
+
+public void otherTypeOfAdvice(@JoinPoint IMethodInfo joinPoint)
+{
+ System.out.println(">>> otherTypeOfAdvice on method execution: " +
+ joinPoint.getAdvisedMethod().getName());
+}
+
+public void otherTypeOfAdvice(@JoinPoint IFieldInfo joinPoint)
+{
+ System.out.println(">>> otherTypeOfAdvice on field" +
+ (joinPoint.isRead()? "read: ": "write: ") +
+ joinPoint.getAdvisedField().getName());
+}
+
+___________________________
+
+<bind pointcut="all(POJO)">
+ <before name="otherTypeOfAdvice" aspect="JoinPointAspect"/>
+</bind>
+}}}
+
+Notice that {{IFieldInfo}} is used fro both field read and write joinpoints. The
+{{otherTypeOfAdvice}} 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 {{@Thrown}}
+parameter to all overloaded versions of this advice.
+
+You can find the overloaded implementations of {{aroundAdvice}} and
+{{otherTypeOfAdvice}} in the {{JoinPointAspect.java}} file.
+
+! Mixing Different Parameters
+
+Besides the previous examples, you can write overloaded advices using different
+return types and annotated parameters. Look at the following overloaded advice:
+
+{{{
+public int overloadedAdvice(@Target POJO target)
+{
+ System.out.println(">>> overloadedAdvice: int(Target POJO)");
+ return 0;
+}
+
+public void overloadedAdvice(@JoinPoint IConstructorInfo joinPoint)
+{
+ System.out.println(">>> overloadedAdvice: (JoinPoint IConstructorInfo)");
+}
+
+public void overloadedAdvice(@Target Object target)
+{
+ System.out.println(">>> overloadedAdvice: (Target Object)");
+}
+
+public void overloadedAdvice(@JoinPoint ICallerMethodInfo joinPoint, @Caller Driver driver)
+{
+ System.out.println(">>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)");
+}
+
+public void overloadedAdvice(@JoinPoint IJoinPointInfo joinPoint, @Arg String arg)
+{
+ System.out.println(">>> overloadedAdvice: JoinPoint IJoinPoint, Arg String");
+}
+}}}
+
+{{MixedParametersAspect.overloadedAdvice()}} has five different versions, and each one
+receives different parameter types. In that case, JBoss AOP will try to find the most
+appropriate version for each case.
+
+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.
+
+!Run the example
+
+__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] >>> otherTypeOfAdvice on constructor of class: POJO
+ [java] >>> aroundAdvice on constructor of class: POJO
+ [java] >>> overloadedAdvice: (JoinPoint IConstructorInfo)
+
+ [java] Setting POJO->intField with 1751 value
+ [java] ======================================
+ [java] >>> otherTypeOfAdvice on fieldwrite: intField
+ [java] >>> aroundAdvice on field write: intField
+ [java] >>> overloadedAdvice: int(Target POJO)
+
+ [java] Reading POJO->intField value
+ [java] ============================
+ [java] >>> otherTypeOfAdvice on fieldread: intField
+ [java] >>> aroundAdvice on field read: intField
+ [java] >>> overloadedAdvice: int(Target POJO)
+
+ [java] Setting POJO->stringField with "text" value
+ [java] ===========================================
+ [java] >>> otherTypeOfAdvice on fieldwrite: stringField
+ [java] >>> aroundAdvice on field write: stringField
+ [java] >>> overloadedAdvice: JoinPoint IJoinPoint, Arg String
+
+ [java] Reading POJO->stringField value
+ [java] ===============================
+ [java] >>> otherTypeOfAdvice on fieldread: stringField
+ [java] >>> aroundAdvice on field read: stringField
+ [java] >>> overloadedAdvice: (Target Object)
+
+ [java] Calling POJO->voidMethod()
+ [java] ==========================
+ [java] >>> otherTypeOfAdvice on method execution: voidMethod
+ [java] >>> aroundAdvice on method execution: voidMethod
+ [java] RUNNING POJO->voidMethod()
+ [java] >>> overloadedAdvice: int(Target POJO)
+ [java] >>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)
+
+ [java] Calling POJO->methodWithStringArg()
+ [java] ===================================
+ [java] >>> otherTypeOfAdvice on method execution: methodWithStringArg
+ [java] >>> aroundAdvice on method execution: methodWithStringArg
+ [java] RUNNING POJO->methodWithStringArg("stringArg")
+ [java] >>> overloadedAdvice: JoinPoint IJoinPoint, Arg String
+ [java] >>> overloadedAdvice: (JoinPoint ICallerMethodInfo, Caller Driver)
+}}}
+
More information about the jboss-cvs-commits
mailing list