# Using AspectJ with Spring applications - Java-Springs

Spring ships with a small AspectJ aspect library, which is available standalone in your distribution as spring-aspects.jar; you'll need to add this to your classpath in order to use the aspects in it.

Using AspectJ to dependency inject domain objects with Spring

The Spring container instantiates and configures beans defined in your application context.It is also possible to ask a bean factory to configure a pre-existing object given the name of a bean definition containing the configuration to be applied.The spring-aspects.jar contains an annotation-driven aspect that exploits this capability to allow dependency injection of any object.The support is intended to be used for objects created outside of the control of any container. Domain objects often fall into this category because they are often created programmatically using the new operator, or by an ORM tool as a result of a database query.

The @Configurable annotation marks a class as eligible for Spring-driven configuration. In the simplest case it can be used just as a marker annotation:

package com.xyz.myapp.domain;
import org.springframework.beans.factory.annotation.Configurable;
@Configurable
public class Account {
// ...
}

When used as a marker interface in this way, Spring will configure new instances of the annotated type (Account in this case) using a prototype-scoped bean definition with the same name as the fully-qualified type name (com.xyz.myapp.domain.Account).Since the default name for a bean is the fully-qualified name of its type, a convenient way to declare the prototype definition is simply to omit the id attribute:

<bean class="com.xyz.myapp.domain.Account"scope="prototype">
<property name="fundsTransferService" ref="fundsTransferService"/>
</bean>

If you want to explicitly specify the name of the prototype bean definition to use, you can do so directly in the annotation:

package com.xyz.myapp.domain;
import org.springframework.beans.factory.annotation.Configurable;
@Configurable("account")
public class Account {
// ...
}

Spring will now look for a bean definition named "account" and use that as the definition to configure new Account instances.

You can also use autowiring to avoid having to specify a prototype-scoped bean definition at all.To have Spring apply autowiring use the 'autowire' property of the @Configurable annotation: specify either @Configurable(autowire=Autowire.BY_TYPE) or @Configurable(autowire=Autowire.BY_NAME for autowiring by type or by name respectively. As an alternative, as of Spring 2.5 it is preferable to specify explicit, annotation-driven dependency injection for your @Configurable beans by using @Autowired and @Resource at the field or method level.

Finally you can enable Spring dependency checking for the object references in the newly created and configured object by using the dependency Check attribute (for example:@Configurable ( auto wire = Auto wire. BY_NAME, dependency Check = true)).If this attribute is set to true, then Spring will validate after configuration that all properties (which are not primitives or collections) have been set.

Using the annotation on its own does nothing of course. It is the Annotation Bean Configurer Aspect in spring-aspects.jar that acts on the presence of the annotation. In essence the aspect says "after returning from the initialization of a new object of a type annotated with @Configurable, configure the newly created object using Spring in accordance with the properties of the annotation". In this context, initialization refers to newly instantiated objects (e.g., objects instantiated with the 'new' operator) as well as to Serializable objects that are undergoing deserialization (e.g., via readResolve()).

For this to work the annotated types must be woven with the AspectJ weaver - you can either use a build-time Ant or Maven task to do this or load-time weaving. The AnnotationBeanConfigurerAspect itself needs configuring by Spring (in order to obtain a reference to the bean factory that is to be used to configure new objects). The Spring context namespace defines a convenient tag for doing this: just include the following in your application context configuration:

<context:spring-configured/>

If you are using the DTD instead of schema, the equivalent definition is:

<bean
class="org.springframework.beans.factory.aspectj.AnnotationBeanConfigurerAspect"
factory-method="aspectOf"/>

Instances of @Configurable objects created before the aspect has been configured will result in a warning being issued to the log and no configuration of the object taking place.An example might be a bean in the Spring configuration that creates domain objects when it is initialized by Spring.In this case you can use the "depends-on" bean attribute to manually specify that the bean depends on the configuration aspect.

<bean id="myService"
class="com.xzy.myapp.service.MyService"
depends-on="org.springframework.beans.factory.aspectj.AnnotationBeanConfigurerAspect">
<!-- ... -->
</bean>

Unit testing @Configurable objects

One of the goals of the @Configurable support is to enable independent unit testing of domain objects without the difficulties associated with hard-coded lookups. If @Configurable types have not been woven by AspectJ then the annotation has no affect during unit testing, and you can simply set mock or stub property references in the object under test and proceed as normal.If @Configurable types have been woven by AspectJ then you can still unit test outside of the container as normal, but you will see a warning message each time that you construct an @Configurable object indicating that it has not been configured by Spring.

Working with multiple application contexts

The AnnotationBeanConfigurerAspect used to implement the @Configurable support is an AspectJ singleton aspect. The scope of a singleton aspect is the same as the scope of static members, that is to say there is one aspect instance per classloader that defines the type. This means that if you define multiple application contexts within the same classloader hierarchy you need to consider where to define the <context:spring-configured/> bean and where to place spring-aspects.jar on the classpath.

Consider a typical Spring web-app configuration with a shared parent application context defining common business services and everything needed to support them, and one child application context per servlet containing definitions particular to that servlet. All of these contexts will co-exist within the same classloader hierarchy, and so the Annotation Bean Configurer Aspect can only hold a reference to one of them. In this case we recommend defining the <context: spring- configured/> bean in the shared (parent) application context: this defines the services that you are likely to want to inject into domain objects. A consequence is that you cannot configure domain objects with references to beans defined in the child (servlet-specific) contexts using the @Configurable mechanism (probably not something you want to do anyway!).

When deploying multiple web-apps within the same container, ensure that each web-application loads the 00 types in spring-aspects.jar using its own classloader (for example, by placing spring-aspects.jar in 'WEB-INF/lib'). If spring-aspects.jar is only added to the container wide classpath (and hence loaded by the shared parent classloader), all web applications will share the same aspect instance which is probably not what you want.

Other Spring aspects for AspectJ

In addition to the @Configurable aspect, spring-aspects.jar contains an AspectJ aspect that can be used to drive Spring's transaction management for types and methods annotated with the @Transactional annotation. This is primarily intended for users who want to use the Spring Frame work's transaction support outside of the Spring container.

The aspect that interprets @Transactional annotations is the Annotation Transaction Aspect.When using this aspect, you must annotate the implementation class (and/or methods within that class), not the interface (if any) that the class implements. AspectJ follows Java's rule that annotations on interfaces are not inherited.

A @Transactional annotation on a class specifies the default transaction semantics for the execution of any public operation in the class.

A @Transactional annotation on a method within the class overrides the default transaction semantics given by the class annotation (if present). Methods with public, protected, and default visibility may all be annotated.Annotating protected and default visibility methods directly is the only way to get transaction demarcation for the execution of such methods.

For AspectJ programmers that want to use the Spring configuration and transaction management support but don't want to (or cannot) use annotations, spring-aspects. jar also contains abstract aspects you can extend to provide your own pointcut definitions. See the sources for the AbstractBeanConfigurerAspect and Abstract Transaction Aspect aspects for more information.As an example, the following excerpt shows how you could write an aspect to configure all instances of objects defined in the domain model using prototype bean definitions that match the fully-qualified class names:

public aspect DomainObjectConfiguration extends AbstractBeanConfigurerAspect {
public DomainObjectConfiguration() {
setBeanWiringInfoResolver(new ClassNameBeanWiringInfoResolver());
}
// the creation of a new bean (any object in the domain model)
protected pointcut beanCreation(Object beanInstance) :
initialization(new(..)) &&
SystemArchitecture.inDomainModel() &&
this(beanInstance);
}

Configuring AspectJ aspects using Spring IoC

When using AspectJ aspects with Spring applications, it is natural to both want and expect to be able to configure such aspects using Spring.The AspectJ runtime itself is responsible for aspect creation, and the means of configuring the AspectJ created aspects via Spring depends on the AspectJ instantiation model (the 'per-xxx' clause) used by the aspect.

The majority of AspectJ aspects are singleton aspects.Configuration of these aspects is very easy: simply create a bean definition referencing the aspect type as normal, and include the bean attribute 'factory-method="aspectOf"'.This ensures that Spring obtains the aspect instance by asking AspectJ for it rather than trying to create an instance itself. For example:

<bean id="profiler" class="com.xyz.profiler.Profiler"
factory-method="aspectOf">
<property name="profilingStrategy"ref="jamonProfilingStrategy"/>
</bean>

Non-singleton aspects are harder to configure: however it is possible to do so by creating prototype bean definitions and using the @Configurable support from spring-aspects.jar to configure the aspect instances once they have bean created by the AspectJ runtime.

If you have some @AspectJ aspects that you want to weave with AspectJ (for example, using load-time weaving for domain model types) and other @AspectJ aspects that you want to use with Spring AOP, and these aspects are all configured using Spring, then you will need to tell the Spring AOP @AspectJ autoproxying support which exact subset of the @AspectJ aspects defined in the configuration should be used for autoproxying.You can do this by using one or more <include/> elements inside the <aop:aspectj-autoproxy/> declaration. Each <include/> element specifies a name pattern, and only beans with names matched by at least one of the patterns will be used for Spring AOP autoproxy configuration:

<aop:aspectj-autoproxy>
<aop:include name="thisBean"/>
<aop:include name="thatBean"/>
</aop:aspectj-autoproxy>

Load-time weaving with AspectJ in the Spring Framework

Load-time weaving (LTW) refers to the process of weaving AspectJ aspects into an application's class files as they are being loaded into the Java virtual machine (JVM).

The value-add that the Spring Framework brings to AspectJ LTW is in enabling much finer-grained control over the weaving process.'Vanilla' AspectJ LTW is effected using a Java (5+) agent, which is switched on by specifying a VM argument when starting up a JVM. It is thus a JVM-wide setting, which may be fine in some situations, but often is a little too coarse.Spring-enabled LTW enables you to switch on LTW on a per-ClassLoader basis, which obviously is more fine-grained and which can make more sense in a 'single-JVM-multiple-application' environment (such as is found in a typical application server environment).

Further, in certain environments, this support enables load-time weaving without making any modifications to the application server's launch script that will be needed to add -javaagent :path/to/aspectj weaver.jar or -javaagent :path/to/org.spring frame work. instrument-{version}.jar(previously named spring-agent.jar). Developers simply modify one or more files that form the application context to enable load-time weaving instead of relying on administrators who typically are in charge of the deployment configuration such as the launch script.

Now that the sales pitch is over, let us first walk through a quick example of AspectJ LTW using Spring, followed by detailed specifics about elements introduced in the following example. For a complete example, please see the Petclinic sample application.

A first example

Let us assume that you are an application developer who has been tasked with diagnosing the cause of some performance problems in a system.Rather than break out a profiling tool, what we are going to do is switch on a simple profiling aspect that will enable us to very quickly get some performance metrics, so that we can then apply a finer-grained profiling tool to that specific area immediately afterwards.

Here is the profiling aspect. Nothing too fancy, just a quick-and-dirty time-based profiler, using the @AspectJ-style of aspect declaration.

package foo;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Pointcut;
import org.springframework.util.StopWatch;
import org.springframework.core.annotation.Order;
@Aspect
public class ProfilingAspect {
@Around("methodsToBeProfiled()")
public Object profile(ProceedingJoinPoint pjp) throws Throwable {
StopWatch sw = new StopWatch(getClass().getSimpleName());
try {
sw.start(pjp.getSignature().getName());
return pjp.proceed();
} finally {
sw.stop();
System.out.println(sw.prettyPrint());
}
}
@Pointcut("execution(public * foo..*.*(..))")
public void methodsToBeProfiled(){}
}

We will also need to create an 'META-INF/aop.xml' file, to inform the AspectJ weaver that we want to weave our ProfilingAspect into our classes. This file convention, namely the presence of a file (or files) on the Java classpath called ' META-INF/aop.xml' is standard AspectJ.

<!DOCTYPE aspectj PUBLIC
"-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/aspectj.dtd">
<aspectj>
<weaver>
<!-- only weave classes in our application-specific packages -->
<include within="foo.*"/>
</weaver>
<aspects>
<!-- weave in just this aspect -->
<aspect name="foo.ProfilingAspect"/>
</aspects>
</aspectj>

Now to the Spring-specific portion of the configuration. We need to configure a LoadTimeWeaver. This load-time weaver is the essential component responsible for weaving the aspect configuration in one or more 'META-INF/aop.xml' files into the classes in your application. The good thing is that it does not require a lot of configuration,

Now that all the required artifacts are in place - the aspect, the 'META-INF/aop.xml' file, and the Spring configuration -, let us create a simple driver class with a main(..) method to demonstrate the LTW in action.

package foo;
import org.spring frame work.context.support.Class Path Xml Application Context;
public final class Main {
public static void main(String[] args) {
ApplicationContext ctx = new ClassPathXmlApplicationContext("beans.xml", Main.class);
EntitlementCalculationService entitlementCalculationService
= (EntitlementCalculationService) ctx.getBean("entitlementCalculationService");
// the profiling aspect is 'woven' around this method execution
entitlementCalculationService.calculateEntitlement();
}
}

There is one last thing to do. However, just for this example, we are going to use a Java agent (supplied with Spring) to switch on the LTW. This is the command line we will use to run the above Main class:java -javaagent:C:/projects/foo/lib/global/spring-instrument.jar foo.Main

The '-javaagent' is a Java 5+ flag for specifying and enabling agents to instrument programs running on the JVM. The Spring Frame work ships with such an agent, the InstrumentationSavingAgent, which is packaged in the spring-instrument.jar that was supplied as the value of the -javaagent argument in the above example.

The output from the execution of the Main program will look something like that below. (I have introduced a Thread.sleep(..) statement into the calculate Entitlement() implementation so that the profiler actually captures something other than 0 milliseconds - the 01234 milliseconds is not an overhead introduced by the AOP :) )

Calculating entitlement
StopWatch 'ProfilingAspect': running time (millis) = 1234
------ ----- ----------------------------
------ ----- ----------------------------
01234 100% calculateEntitlement

Since this LTW is effected using full-blown AspectJ, we are not just limited to advising Spring beans; the following slight variation on the Main program will yield the same result.

package foo;
import org.springframework.context.support.ClassPathXmlApplicationContext;
public final class Main {
public static void main(String[] args) {
new ClassPathXmlApplicationContext("beans.xml", Main.class);
EntitlementCalculationService entitlementCalculationService =
new StubEntitlementCalculationService();
// the profiling aspect will be 'woven' around this method execution
entitlementCalculationService.calculateEntitlement();
}
}

Notice how in the above program we are simply boot strapping the Spring container, and then creating a new instance of the Stub Enti tlement Calculation Service totally outside the context of Spring... the profiling advice still gets woven in.

The example admittedly is simplistic... however the basics of the LTW support in Spring have all been introduced in the above example.

Aspects

The aspects that you use in LTW have to be AspectJ aspects.They can be written in either the AspectJ language itself or you can write your aspects in the @AspectJ-style.The latter option is of course only an option if you are using Java 5+, but it does mean that your aspects are then both valid AspectJ and Spring AOP aspects.Furthermore, the compiled aspect classes need to be available on the classpath.

META-INF/aop.xml

The AspectJ LTW infrastructure is configured using one or more 'META-INF/aop.xml' files, that are on the Java classpath (either directly, or more typically in jar files).

The structure and contents of this file is detailed in the main AspectJ reference documentation, and the interested reader is referred to that resource. (I appreciate that this is brief, but the 'aop.xml' file is 100% AspectJ - there is no Spring-specific information or semantics that apply to it, and so there is no extra value that I can contribute either as a result), so rather than rehash the quite satisfactory that the AspectJ developers wrote, I am just directing you there.)

Required libraries (JARS)

At a minimum you will need the following libraries to use the Spring Frame work's support for AspectJ LTW:

1. spring-aop.jar (version 2.5 or later, plus all mandatory dependencies)
2. aspectjrt.jar (version 1.5 or later)
3. aspectjweaver.jar (version 1.5 or later)

If you are using the Spring-provided agent to enable instrumentation, you will also need:

1. spring-instrument.jar

Spring configuration

The key component in Spring's LTW support is the LoadTimeWeaver interface (in the org.spring frame work. instrument. class loading package), and the nume rous implementations of it that ship with the Spring distribution. A Load Time Weaver is responsible for adding one or more java.lang.instrument.Class File Transformers to a ClassLoader at runtime, which opens the door to all manner of interesting applications, one of which happens to be the LTW of aspects.

Configuring a LoadTimeWeaver using XML for a particular ApplicationContext can be as easy as adding one line. (Please note that you almost certainly will need to be using an Application Context as your Spring container - typically a Bean Factory will not be enough because the LTW support makes use of BeanFactoryPostProcessors.)

To enable the Spring Frame work's LTW support, you need to configure a Load Time Weaver, which typically is done using the <context:load-time-weaver/> element.Find below a valid.

The above <context:load-time-weaver/> bean definition will define and register a number of LTW-specific infrastructure beans for you automatically, such as a Load Time Weaver and an AspectJ Weaving Enabler.Notice how the <context:load-time-weaver/> is defined in the 'context' namespace; note also that the referenced XML Schema file is only available in versions of Spring 2.5 and later.

What the above configuration does is define and register a default Load Time Weaver bean for you. The default Load Time Weaver is the Default Context Load Time Weaver class, which attempts to decorate an automatically detected LoadTimeWeaver: the exact type of Load Time Weaver that will be 'automatically detected' is dependent upon your runtime environment (summarised in the following table).

Note that these are just the Load Time Weavers that are autodetected when using the Default Context LoadT ime Weaver: it is of course possible to specify exactly which Load Time Weaver implementation that you wish to use by specifying the fully-qualified class name as the value of the 'weaver-class' attribute of the <context:load-time-weaver/> element.

The LoadTimeWeaver that is defined and registered by the <context:load-time-weaver/> element can be later retrieved from the Spring container using the well-known name 'load Time Weaver'. Remember that the Load Time Weaver exists just as a mechanism for Spring's LTW infra structure to add one or more Class File Transformers.The actual Class File Transformer that does the LTW is the Class Pre Processor Agent Adapter (from the org.aspectj.weaver.loadtime package) class.

There is one final attribute of the <context:load-time-weaver/> left to discuss: the 'aspectj-weaving' attribute. This is a simple attribute that controls whether LTW is enabled or not, it is as simple as that. It accepts one of three possible values, summarised below, with the default value if the attribute is not present being ' autodetect'

Table 'aspectj-weaving' attribute values:-

Environment-specific configuration

Tomcat

Apache Tomcat's default class loader does not support class transformation which is why Spring provides an enhanced implementation that addresses this need. Named TomcatInstrumentableClassLoader, the loader works on Tomcat 5.0 and above and can be registered individually for each web application as follows:Tomcat 6.0.x or higher

1. Copy org.springframework.instrument.tomcat.jar into $CATALINA_HOME/lib, where$CATALINA_HOME represents the root of the Tomcat installation)
2. Instruct Tomcat to use the custom class loader (instead of the default) by editing the web application context file:
<Context path="/myWebApp" docBase="/my/webApp/location">
</Context>

Apache Tomcat 6.0.x (similar to 5.0.x/5.5.x) series supports several context locations:

• server configuration file - $CATALINA_HOME/conf/server.xml • default context configuration -$CATALINA_HOME/conf/context.xml - that affects all deployed web applications
• per-web application configuration which can be deployed either on the server-side at
$CATALINA_HOME/conf/ [enginename]/[hostname] /[webapp]-context.xmlor embedded inside the web-app archive at META-INF/context.xml For efficiency, the embedded per-web-app configuration style is recommended because it will impact only applications that use the custom class loader and does not require any changes to the server configuration. See the Tomcat 6.0.x documentation for more details about available context locations. Tomcat 5.0.x/5.5.x 1. Copy org.springframework.instrument.tomcat.jar into 2.$CATALINA_HOME/server/lib, where $CATALINA_HOME represents the root of the Tomcat installation. 3. Instruct Tomcat to use the custom class loader instead of the default one by editing the web application context file: <Context path="/myWebApp" docBase="/my/webApp/location"> <Loader loaderClass="org.springframework.instrument.classloading.tomcat .TomcatInstrumentableClassLoader"/> </Context> Tomcat 5.0.x and 5.5.x series supports several context locations: • server configuration file -$CATALINA_HOME/conf/server.xml
• default context configuration - $CATALINA_HOME/conf/context.xml - that affects all deployed web applications • per-web application configuration which can be deployed either on the server-side at$CATALINA_HOME/conf/[enginename] /[hostname]/[webapp] -context.xml or embedded inside the web-app archive at META-INF/context.xml

For efficiency, the embedded web-app configuration style is recommended recommended because it will impact only applications that use the class loader.

Tomcat versions prior to 5.5.20 contained a bug in the XML configuration parsing that prevented usage of the Loader tag inside server.xml configuration, regardless of whether a class loader is specified or whether it is the official or a custom one.

In Tomcat 5.5.x, versions 5.5.20 or later, you should set useSystemClassLoaderAsParent to false to fix this problem:

<Context path="/myWebApp"docBase="/my/webApp/location">
</Context>

This setting is not needed on Tomcat 6 or higher.

Alternatively, consider the use of the Spring-provided generic VM agent, to be specified in Tomcat's launch script (see above). This will make instrumentation available to all deployed web applications, no matter what ClassLoader they happen to run on.

Web Logic, OC4J, Resin, GlassFish, JBoss

Recent versions of BEA WebLogic (version 10 and above), Oracle Containers for Java EE (OC4J 10.1.3.1 and above), Resin (3.1 and above) and JBoss (5.x or above) provide a Class Loader that is capable of local instrumentation.Spring's native LTW leverages such ClassLoaders to enable AspectJ weaving. You can enable LTW by simply activating context:load-time-weaver. Specifically, you do not need to modify the launch script to add -javaagent:path/to/spring-instrument.jar.

Note that GlassFish instrumentation-capable Class Loader is available only in its EAR environment. For GlassFish web applications, follow the Tomcat setup instructions as outlined above.

Generic Java applications

When class instrumentation is required in environments that do not support or are not supported by the existing Load Time Weaver implementations, a JDK agent can be the only solution. For such cases, Spring provides InstrumentationLoadTimeWeaver, which requires a Spring-specific (but very general) VM agent, org. spring frame work. instrument-{version}.jar (previously named spring-agent.jar).

To use it, you must start the virtual machine with the Spring agent, by supplying the following JVM options:-javaagent:/path/to/org.spring frame work. instrument -{version}.jar

Note that this requires modification of the VM launch script which may prevent you from using this in application server environments(depending on your operation policies). Additionally, the JDK agent will instrument the entire VM which can prove expensive.

For performance reasons, it is recommended to use this configuration only if your target environment (such as Jetty) does not have (or does not support) a dedicated LTW.