JBoss.org Community Documentation

4.3. Annotated Advice Parameters

This section lists the annotated parameters that can be used on JBoss AOP advices (available only in generated advisor execution mode). Table 4.1, “Annotated Parameters Table” lists all annotations and their semantics.

Except for the @JoinPoint annotation, used to refer to joinpoint beans, all other annotations are used on parameters that contain joinpoint context values.

Notice that the types of annotated parameters are dependent on the joinpoint being intercepted by the advice.

JBoss AOP will accept any type that is assignable from the type referred by that parameter, as shown in the Type Assignable From column of the table below. For example, for a joinpoint whose target is of type POJO, the annotated parameter that receives the target must be of POJO type, one of POJO's superclasses, or one of the interfaces implemented by POJO.

Regarding the type of joinpoint bean parameters, the rules are the same for the default signature of around advices (without annotations). For example, an around advice that intercepts a method execution, can receive either a MethodInvocation, or an Invocation (the complete list of joinpoint beans and their relationship with joinpoint types was shown in Table 3.1, “ Joinpoint Types Table ”). As already explained, around advices use Invocation instances, while the other advices use JoinPointBean objects.

Notice also that only one annotated parameter can be mandatory: @Thrown. This will be further explained in Section 4.3.1, “@Thrown annotated parameter”.

Except for @Arg, all annotations are single-enforced, i.e., there must be at most only one advice parameter with that annotation per advice.

Annotation Semantics Type assignable from Mandatory Advice type
Before Around After After-Throwing Finally
@JoinPoint JoinPoint bean Joinpoint invocation type No No Yes No No No
JoinpointBean interface type No Yes No Yes Yes Yes
@Target Joinpoint target Joinpoint target type No Yes Yes Yes Yes Yes
@Caller Joinpoint caller JoinPoint caller type (only for call joinpoints) No Yes Yes Yes Yes Yes
@Thrown Joinpoint thrown exception java.lang.Throwable

If used on an after-throwing advice, this parameter can also be:

- assignable from any exception declared to be thrown by the joinpoint

- java.lang.RuntimeException or any subtype of this class

Yes:

- for after-throwing advices

- for finally advices only if @Return is present

No: otherwise

No No No Yes Yes
@Return Joinpoint return value JoinPoint return type No No No Yes No Yes
@Arg One of the joinpoint arguments JoinPoint argument type No Yes Yes Yes Yes Yes
@Args All joinpoint arguments java.lang.Object[] No Yes Yes Yes Yes Yes
The first column shows the annotation to be used for each parameter type. All annotations are from the org.jboss.aop.advice.annotation package. The column Semantics shows what value each annotated parameter represents. The third column shows from which type the parameter type must be assignable (notice that Throwable and Object[] belong to java.lang package). The Mandatory column indicates whether that value must be present in order for the advice to be considered valid. Finally, the Advice Type column shows for which advice types that parameter is allowed.

Table 4.1. Annotated Parameters Table


Due to the fact that most of these parameters represent context values, their availability depends on the joinpoint type. If an advice receives as a parameter a context value that is not available during a joinpoint execution, the parameter value will be null. The exception to this rule is @Return. If an advice has this parameter, it will not intercept joinpoints that don’t have a return value.

The only exception to this rule is @Args on field read joinpoints. Such an advice will be called with an empty arguments array, in that case.