Interception Done Right

One of the new features in the AspectWerkz 2 architecture is that it comes with a full-blown interception framework that allows per instance programmatic deployment with most of the AOP semantics preserved. You can make use of this using both the regular load-time weaving or the AW Proxy (that I blogged about here)

In short you will get: Per instance programmatic deployment for before, around, after, after finally and after throwing advice types for call, execution, set and get pointcuts as well as the expressiveness of the AspectWerkz' pointcut pattern language all wrapped up in a very simple and intuitive API.

POJO pojo = new POJO();

// adds tracing to all methods in the 'pojo' instance

((Advisable) pojo).aw$addAdvice(
    "* *.*(..)",
    new BeforeAdvice() {
        public Object invoke(JoinPoint jp) {
            System.out.println("Entering: " + jp.getSignature().toString());
        }
    }
);

The Advisable interface

From a users perspective pretty much all you need to know about is in the Advisable interface. This interface is added to all the classes that you want to do per instance runtime deployment at. This interface is added to your classes by the framework, but more on that later.

The Advisable interface basically has two methods that are of interest to you:

void aw_addAdvice(String memberPattern, Advice advice) - this methods allows you to add an Advice instance to the members specified by the memberPattern argument.
void aw_removeAdvice(String memberPattern, Class adviceClass) - this methods allows you to remove the last advice (that was added last) of the type specified in the adviceClass argument from from the list of aspects applied to the members specified by the memberPattern argument

The funny prefix aw_ is just to minimize method clashes since these methods are added to your classes on-the-fly.

The different Advice interfaces

The intercept framework supports all main types of advice defined in AOP today:

AroundAdvice - works like a regular interceptor and is invoked "around" or "instead-of" the target method invocation or field access/modification. It has one method you need to implement which has the following signature: Object invoke(JoinPoint jp)
BeforeAdvice - is invoked before the actual member invocation. It has one method you need to implement which has the following signature: Object invoke(JoinPoint jp)
AfterAdvice - is invoked after the actual member invocation, is invoked both if the method returns normally or with an exception. E.g. can be seen as being invoked in the finally block. It has one method you need to implement which has the following signature: Object invoke(JoinPoint jp)
AfterReturning - is invoked after the actual method has returned normally. It has one method you need to implement which has the following signature: Object invoke(JoinPoint jp, Object returnValue)
AfterThrowingAdvice - is invoked after the actual method has returned with an exception. It has one method you need to implement which has the following signature: Object invoke(JoinPoint jp, Throwable exception)

As you can see, all of these methods takes a JoinPoint instance as a parameter. This class contains f.e. contextual information bout the join point (member) we are executing before/after/around. Such as caller and callee instances and types, argument values and types etc. You can also see that some of the advice takes an optional parameter which provides direct access to the return value or the exception instance.

Preparing your application

To make this work you finally need to tell AspectWerkz which classes you want to make "advisable" and to which extent. This is done in the META-INF/aop.xml deployment descriptor in which you have to make use of the element. This element has two attributes:

expresssion - here you specify the type pattern that picks out the classes that you want to make "advisable" and this is done by defining a within() pointcut expression.
pointcut-type - here you defined which pointcut semantics you want the added advice to follow. Valid types are:
- call - the advice added to a method will be invoked on the caller side of the method invocation (if you think client-server then it is executing on the client side)
- execution - the advice added to a method will be invoked on the execution side of the method invocation
- set - the advice added to a field will be invoked when a field is modified
- get - the advice added to a field will be invoked when a field is accessed
- all - a combination of all the above pointcut types

Example:

<aspectwerkz>
    <system id="intercept-sample">
        <advisable expression="within(my.application.domain.*)" pointcut-type="call|set|get"/>
    </system>
</aspectwerkz>

Bringing it all together

So now we have talked about the Advisable interface that we can use to add the advice we want to a specific instance. We have talked about the different Advice interfaces and their differences. Finally we talked about how we tell the AspectWerkz container which classes it should make "advisable" and how it should treat them. Let's now try to bring it all together in a small example.

In this example we are taking a regular POJO and we are adding an advice that will be applied to all methods that are annotated with the annotation @OneWay and turn the otherwise synchronous invocations into ansynchronous invocations.

...

POJO pojo = new POJO();

((Advisable) pojo).aw_addAdvice(
    "@OneWay * *.*(..)",
    new AroundAdvice() {
        private Executor m_threadPool = Executors.newCachedThreadPool();

        public Object invoke(JoinPoint jp) throws Throwable {
            m_threadPool.execute(
                new Runnable() {
                    public void run() {
                        try {
                            // proceed with the invocation in a new thread

                            jp.proceed();
                        } catch (Throwable e) {
                            throw new RuntimeException(e);
                        }
                    }
                }
            );
            return null;
        }
    }
);

...

The META-INF/aop.xml file looks like this:

<aspectwerkz>
    <system id="intercept-sample">
        <advisable expression="within(sample.intercept.POJO)" pointcut-type="call"/>
    </system>
</aspectwerkz>

Resources

I have not written any specific sample application for this article but if you want you can look at and run the tests in the AspectWerkz distribution. You can download the distribution here. The tests are in ./src/test/test/intercept/* directory and you can run them (along with all the other tests) by invoking ant test when standing in the AspectWerkz distribution's root dir.

Enjoy

Jonas Bonér