Chapter 34. AOP Guide

Chapter 34. AOP Guide

'before advice' is just that... it is advice that runs before the target method invocation is invoked. One does not get access to the target method invocation itself, and one cannot return a value... this is a good thing, because it means that you cannot inadvertently forget to call the Proceed() method on the target, and it also means that you cannot inadvertently forget to return the return value of the target method invocation. If you don't need to inspect or change the return value, or even do anything after the successful execution of the target method invocation, then 'before advice' is just what you need.

'before advice' in Spring.NET is defined by the IMethodBeforeAdvice interface in the Spring.Aop namespace. Lets just dive in with an example... we'll use the same scenario as before to keep things simple. Let's define the 'before advice' implementation first.

    public class ConsoleLoggingBeforeAdvice : IMethodBeforeAdvice
    {
        public void Before(MethodInfo method, object[] args, object target)
        {
            Console.Out.WriteLine("Intercepted call to this method : " + method.Name);
            Console.Out.WriteLine("    The target is               : " + target);
            Console.Out.WriteLine("    The arguments are           : ");
            if(args != null)
            {
                foreach (object arg in args)
                {
                    Console.Out.WriteLine("\t: " + arg);
                }
            }
        }
    }

Let's apply a single instance of the ConsoleLoggingBeforeAdvice advice to the invocation of the Execute() method of the ServiceCommand. What follows is programmatic configuration; as you can see, its pretty much identical to the previous version... the only difference is that we're using our new 'before advice' (encapsulated as an instance of the ConsoleLoggingBeforeAdvice class).

    ProxyFactory factory = new ProxyFactory(new ServiceCommand());
    factory.AddAdvice(new ConsoleLoggingBeforeAdvice());
    ICommand command = (ICommand) factory.GetProxy();
    command.Execute();

The result of executing the above snippet of code will look something like this...

    Intercepted call to this method : Execute
    The target is                   : Spring.Examples.AopQuickStart.ServiceCommand
    The arguments are               :

The output clearly indicates that the advice was applied before the invocation of the advised method. Notice that in contrast to 'around advice', with 'before advice' there is no chance of forgetting to call the Proceed() method on the target, because one does not have access to the IMethodInvocation (as is the case with 'around advice')... similarly, you cannot forget to return the return value either.

If you can use 'before advice', then do so. The simpler programming model offered by 'before advice' means that there is less to remember, and thus potentially less things to get wrong.

Here is the Spring.NET XML configuration for applying our 'before advice' declaratively...

    <object id="beforeAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingBeforeAdvice"/>

    <object id="myServiceObject"
        type="Spring.Aop.Framework.ProxyFactoryObject">
        <property name="target">
            <object id="myServiceObjectTarget"
                type="Spring.Examples.AopQuickStart.ServiceCommand"/>
        </property>
        <property name="interceptorNames">
            <list>
                <value>beforeAdvice</value>
            </list>
        </property>
    </object>

Just as 'before advice' defines advice that executes before an advised target, 'after advice' is advice that executes after a target has been executed.

'after advice' in Spring.NET is defined by the IAfterReturningAdvice interface in the Spring.Aop namespace. Again, lets just fire on ahead with an example... again, we'll use the same scenario as before to keep things simple.

    public class ConsoleLoggingAfterAdvice : IAfterReturningAdvice
    {
        public void AfterReturning(
            object returnValue, MethodInfo method, object[] args, object target)
        {
            Console.Out.WriteLine("This method call returned successfully : " + method.Name);
            Console.Out.WriteLine("    The target was                     : " + target);
            Console.Out.WriteLine("    The arguments were                 : ");
            if(args != null)
            {
                foreach (object arg in args)
                {
                    Console.Out.WriteLine("\t: " + arg);
                }
            }
            Console.Out.WriteLine("    The return value is                : " + returnValue);
        }
    }

Let's apply a single instance of the ConsoleLoggingAfterAdvice advice to the invocation of the Execute() method of the ServiceCommand. What follows is programmatic configuration; as you can, its pretty much identical to the 'before advice' version (which in turn was pretty much identical to the original 'around advice' version)... the only real difference is that we're using our new 'after advice' (encapsulated as an instance of the ConsoleLoggingAfterAdvice class).

    ProxyFactory factory = new ProxyFactory(new ServiceCommand());
    factory.AddAdvice(new ConsoleLoggingAfterAdvice());
    ICommand command = (ICommand) factory.GetProxy();
    command.Execute();

The result of executing the above snippet of code will look something like this...

    This method call returned successfully : Execute
    The target was                         : Spring.Examples.AopQuickStart.ServiceCommand
    The arguments were                     :
    The return value is                    : null

The output clearly indicates that the advice was applied after the invocation of the advised method. Again, it bears repeating that your real world development will actually have an advice implementation that does something useful after the invocation of an advised method. Notice that in contrast to 'around advice', with 'after advice' there is no chance of forgetting to call the Proceed() method on the target, because just like 'before advice' you don't have access to the IMethodInvocation... similarly, although you get access to the return value of the target, you cannot forget to return the return value either. You can however change the state of the return value, typically by setting some of its properties, or by calling methods on it.

The best-practice rule for 'after advice' is much the same as it is for 'before advice'; namely that if you can use 'after advice', then do so (in preference to using 'around advice'). The simpler programming model offered by 'after advice' means that there is less to remember, and thus less things to get potentially wrong.

A possible use case for 'after advice' would include performing access control checks on the return value of an advised method invocation; consider the case of a service that returns a list of document URI's... depending on the identity of the (Windows) user that is running the program that is calling this service, one could strip out those URI's that contain sensitive data for which the user does not have sufficient privileges to access. That is just one (real world) scenario... I'm sure you can think of plenty more that are a whole lot more relevant to your own development needs.

Here is the Spring.NET XML configuration for applying the 'after advice' declaratively...

    <object id="afterAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingAfterAdvice"/>

    <object id="myServiceObject"
        type="Spring.Aop.Framework.ProxyFactoryObject">
        <property name="target">
            <object id="myServiceObjectTarget"
                type="Spring.Examples.AopQuickStart.ServiceCommand"/>
        </property>
        <property name="interceptorNames">
            <list>
                <value>afterAdvice</value>
            </list>
        </property>
    </object>

So far we've covered 'around advice', 'before advice', and 'after advice'... these advice types will see you through most if not all of your AOP needs. However, one of the remaining advice types that Spring.NET has in its locker is 'throws advice'.

'throws advice' is advice that executes when an advised method invocation throws an exception.. hence the name. One basically applies the 'throws advice' to a target object in much the same way as any of the previously mentioned advice types. If during the execution of ones application none of any of the advised methods throws an exception, then the 'throws advice' will never execute. However, if during the execution of your application an advised method does throw an exception, then the 'throws advice' will kick in and be executed. You can use 'throws advice' to apply a common exception handling policy across the various objects in your application, or to perform logging of every exception thown by an advised method, or to alert (perhaps via email) the support team in the case of particularly of critical exceptions... the list of possible uses cases is of course endless.

The 'throws advice' type in Spring.NET is defined by the IThrowsAdvice interface in the Spring.Aop namespace... basically, one defines on one's 'throws advice' implementation class what types of exception are going to be handled. Lets take a quick look at the IThrowsAdvice interface...

    public interface IThrowsAdvice : IAdvice
    {
    }

Yes, that is really it... it is a marker interface that has no methods on it. You may be wondering how Spring.NET determines which methods to call to effect the running of one's 'throws advice'. An example would perhaps be illustrative at this point, so here is some simple Spring.NET style 'throws advice'...

    public class ConsoleLoggingThrowsAdvice : IThrowsAdvice
    {
        public void AfterThrowing(Exception ex)
        {
            Console.Out.WriteLine("Advised method threw this exception : " + ex);
        }
    }

Lets also change the implementation of the Execute() method of the ServiceCommand class such that it throws an exception. This will allow the advice encapsulated by the above ConsoleLoggingThrowsAdvice to kick in.

    public class ServiceCommand : ICommand
    {
        public void Execute()
        {
            throw new UnauthorizedAccessException();
        }
    }

Let's programmatically apply the 'throws advice' (an instance of our ConsoleLoggingThrowsAdvice) to the invocation of the Execute() method of the above ServiceCommand class; to wit...

    ProxyFactory factory = new ProxyFactory(new ServiceCommand());
    factory.AddAdvice(new ConsoleLoggingThrowsAdvice());
    ICommand command = (ICommand) factory.GetProxy();
    command.Execute();

The result of executing the above snippet of code will look something like this...

    Advised method threw this exception : System.UnauthorizedAccessException:
    Attempted to perform an unauthorized operation.

As can be seen from the output, the ConsoleLoggingThrowsAdvice kicked in when the advised method invocation threw an exception. There are a number of things to note about the ConsoleLoggingThrowsAdvice advice class, so lets take them each in turn.

In Spring.NET, 'throws advice' means that you have to define a class that implements the IThrowsAdvice interface. Then, for each type of exception that your 'throws advice' is going to handle, you have to define a method with this signature...

    void AfterThrowing(Exception ex)

Basically, your exception handling method has to be named AfterThrowing. This name is important... your exception handling method(s) absolutely must be called AfterThrowing. If your handler method is not called AfterThrowing, then your 'throws advice' will never be called, it's as simple as that. Currently, this naming restriction is not configurable (although it may well be opened up for configuration in the future).

Your exception handling method must (at the very least) declare a parameter that is an Exception type... this parameter can be the root Exception class (as in the case of the above example), or it can be an Exception subclass if you only want to handle certain types of exception. It is good practice to always make your exception handling methods have an Exception parameter that is the most specialized Exception type possible... i.e. if you are applying 'throws advice' to a method that could only ever throw ArgumentExceptions, then declare the parameter of your exception handling method as...

    void AfterThrowing(ArgumentException ex)

Note that your exception handling method can have any return type, but returning any value from a Spring.NET 'throws advice' method would be a waste of time... the Spring.NET AOP infrastructure will simply ignore the return value, so always define the return type of your exception handling methods to be void.

Finally, here is the Spring.NET XML configuration for applying the 'throws advice' declaratively...

    <object id="throwsAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingThrowsAdvice"/>

    <object id="myServiceObject"
        type="Spring.Aop.Framework.ProxyFactoryObject">
        <property name="target">
            <object id="myServiceObjectTarget"
                type="Spring.Examples.AopQuickStart.ServiceCommand"/>
        </property>
        <property name="interceptorNames">
            <list>
                <value>throwsAdvice</value>
            </list>
        </property>
    </object>

One thing that cannot be done using 'throws advice' is exception swallowing. It is not possible to define an exception handling method in a 'throws advice' implementation that will swallow any exception and prevent said exception from bubbling up the call stack. The nearest thing that one can do is define an exception handling method in a 'throws advice' implementation that will wrap the handled exception in another exception; one would then throw the wrapped exception in the body of one's exception handling method. One can use this to implement some sort of exception translation or exception scrubbing policy, in which implementation specific exceptions (such as SqlException or OracleException exceptions being thrown by an advised data access object) get replaced with a business exception that has meaning to the service objects in one's business layer. A toy example of this type of 'throws advice' can be seen below.

    public class DataAccessExceptionScrubbingThrowsAdvice : IThrowsAdvice
    {
        public void AfterThrowing (SqlException ex)
        {
            // business objects in higher level service layer need only deal with PersistenceException...
            throw new PersistenceException ("Cannot access persistent storage.", ex.StackTrace);
        }
    }

Spring.NET's data access library already has this kind of functionality (and is a whole lot more sophisticated)... the above example is merely being used for illustrative purposes.

This treatment of 'throws advice', and of Spring.NET's implementation of it is rather simplistic. 'throws advice' features that have been omitted include the fact that one can define exception handling methods that permit access to the original object, method, and method arguments of the advised method invocation that threw the original exception. This is a quickstart guide though, and is not meant to be exhaustive... do consult the 'throws advice' section of the reference documentation, which describes how to declare an exception handling method that gives one access to the above extra objects, and how to declare multiple exception handling methods on the same IThrowsAdvice implementation class (see Section 13.3.2.3, “Throws advice”).

In a nutshell, introductions are all about adding new state and behaviour to arbitrary objects... transparently and at runtime. Introductions (also called mixins) allow one to emulate multiple inheritance, typically with an eye towards applying crosscutting state and operations to a wide swathe of objects in your application that don't share the same inheritance hierarchy.

The examples shown so far have all demonstrated the application of a single advice instance to an advised object. Spring.NET's flavor of AOP would be pretty poor if one could only apply a single advice instance per advised object... it is perfectly valid to apply multiple advice to an advised object. For example, one might apply transactional advice to a service object, and also apply a security access checking advice to that same advised service object.

In the interests of keeping this section lean and tight, let's simply apply all of the advice types that have been previously described to a single advised object... in this first instance we'll just use the default pointcut which means that every possible joinpoint will be advised, and you'll be able to see that the various advice instances are applied in order.

Please do consult the class definitions for the following previously defined advice types to see exactly what each advice type implementation does... we're going to be using single instances of the ConsoleLoggingAroundAdvice, ConsoleLoggingBeforeAdvice, ConsoleLoggingAfterAdvice, and ConsoleLoggingThrowsAdvice advice to advise a single instance of the ServiceCommand class.

You can find the following listing and executable application in the AopQuickStart solution in the project Spring.AopQuickStart.Step1.

    ProxyFactory factory = new ProxyFactory(new ServiceCommand());
    factory.AddAdvice(new ConsoleLoggingBeforeAdvice());
    factory.AddAdvice(new ConsoleLoggingAfterAdvice());
    factory.AddAdvice(new ConsoleLoggingThrowsAdvice());
    factory.AddAdvice(new ConsoleLoggingAroundAdvice());
    ICommand command = (ICommand) factory.GetProxy();
    command.Execute();

Here is the Spring.NET XML configuration for declaratively applying multiple advice.

You can find the following listing and executable application in the AopQuickStart solution in the project Spring.AopQuickStart.Step2.

    <object id="throwsAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingThrowsAdvice"/>
    <object id="afterAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingAfterAdvice"/>
    <object id="beforeAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingBeforeAdvice"/>
    <object id="aroundAdvice"
	    type="Spring.Examples.AopQuickStart.ConsoleLoggingAroundAdvice"/>

    <object id="myServiceObject"
        type="Spring.Aop.Framework.ProxyFactoryObject">
        <property name="target">
            <object id="myServiceObjectTarget"
                type="Spring.Examples.AopQuickStart.ServiceCommand"/>
        </property>
        <property name="interceptorNames">
            <list>
                <value>throwsAdvice</value>
                <value>afterAdvice</value>
                <value>beforeAdvice</value>
                <value>aroundAdvice</value>
            </list>
        </property>
    </object>

In case it is not immediately apparent, remember that advice is just a plain old .NET object (a PONO); advice can have constructors that can take any number of parameters, and like any other .NET class, advice can have properties. What this means is that one can leverage the power of the Spring.NET IoC container to apply the IoC principle to one's advice, and in so doing reap all the benefits of Dependency Injection.

Consider the case of throws advice that needs to report (fatal) exceptions to a first line support centre. The throws advice could declare a dependency on a reporting service via a .NET property, and the Spring.NET container could dependency inject the reporting service dependency into the throws advice when it is being created; the reporting dependency might be a simple Log4NET wrapper, or a Windows EventLog wrapper, or a custom reporting exception reporting service that sends detailed emails concerning the fatal exception.

Also bear in mind the fact that Spring.NET's AOP implementation is quite independent of Spring.NET's IoC container. As you have seen, the various examples used in this have illustrated both programmatic and declarative AOP configuration (the latter being illustrated via Spring.NET's IoC XML configuration mechanism).