org.beanlet
Annotation Type AroundInvoke

@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface AroundInvoke

Designates a method to intercept invocations on a beanlet. A class that declares a method marked with the ArroundInvoke annotation is said to be an interceptor class. Interceptor classes are instantiated either by their (typically implicit) sole constructor, or by contructor injection. Example (A) shows how to implement an interceptor using this annotation.

Inner Interceptors

The ArroundInvoke annotation can be applied on methods of any class, including classes implementing a beanlet. Such interceptors are so-called inner interceptors. An inner interceptor is automatically installed for all business methods of a beanlet. It is placed at the tail of the interceptor chain. It cannot be excluded by the ExcludeClassInterceptors annotation. An example of an inner interceptor can be found at example (B).

Hierarchical Interceptors

Interceptor classes may declare only one interceptor method. However interceptor methods may be defined on any of its superclasses. The interceptor methods defined by these superclasses are invoked before the interceptor method defined by the interceptor class, most general superclass first. This is demonstrated by example (C).
If a interceptor method is overridden by another method (regardless whether that method is itself an interceptor method), it will not be invoked. An example of such an interceptor is listed at (D).

Method Constraints

The method on which the AroundInvoke annotation is applied MUST fulfill all of the following criteria:

• The method MUST have the InterceptorContext object as parameter.
• The return type of the method MUST NOT be void
• The method MAY throw a checked exception.
• The method on which AroundInvoke is applied MAY be public, protected, package private or private.
• The method MUST NOT be static.
• The method MAY be final.

Examples

(A) Example of an interceptor class using the ArroundInvoke annotation:

 public class BaseInterceptor {

     @AroundInvoke
     public Object wrap(InvocationContext ctx) throws Exception {
         try {
             // Run code before the invocation...
             return ctx.proceed();
         } finally {
             // Run code after the invocation...
         }
     }
 }
 

(B) Example of a beanlet with an inner interceptor:

 public class ExampleBeanlet {
     
     @Factory
     public Object getInstance() {
         return new Object();
     }

     @ArroundInvoke 
     public Object intercept(InvocationContext ctx) throws Exception {
         try {
             // Run code before the invocation...
             return ctx.proceed();
         } finally {
             // Run code after the invocation...
         }
     }
 }
 

(C) Example of an interceptor class that extends the interceptor class listed at example (A). The BaseInterceptor.wrap() method preceeds the ExtendedInterceptor.wrapToo() method in the interceptor chain:

 public class ExtendedInterceptor extends BaseInterceptor {

     @AroundInvoke 
     public Object wrapToo(InvocationContext ctx) throws Exception {
         try {
             // Run code before the invocation...
             return ctx.proceed();
         } finally {
             // Run code after the invocation...
         }
     }
 }
 

(D) Example of an extended interceptor class of which the interceptor method overrides the interceptor method of its superclass (listed at (A)). The BaseInterceptor.wrap() method is excluded from the interceptor chain, it is not invoked. The ExtendedInterceptor.wrap() method however, is included in the interceptor chain.

 public class ExtendedInterceptor extends BaseInterceptor {

     @AroundInvoke 
     public Object wrap(InvocationContext ctx) throws Exception {
         try {
             // Run code before the invocation...
             return ctx.proceed();
         } finally {
             // Run code after the invocation...
         }
     }
 }
 

More information on how to apply interceptors can be found at the javadoc of the Interceptor interface.

XML Representation

The following xml-fragment shows how to express this annotation in xml. The italic attribute of the 'around-invoke' tag is used to identify the element to which this annotation is applied.

<beanlets xmlns="http://beanlet.org/schema/beanlet"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://beanlet.org/schema/beanlet http://beanlet.org/schema/beanlet/beanlet_1_0.xsd">
  <beanlet name="foo" type="com.acme.Foo">
    <around-invoke method="bar"/>
  </beanlet>
</beanlets>

See Also:

Interceptor, Interceptors