Chapter 25. Annotations and Source Level Metadata Support

25.1. Introduction

Source-level metadata is the addition of attributes or annotations to program elements - usually, classes and/or methods.

For example, we might add metadata to a class as follows:

/**
 * Normal comments here
 * @@org.springframework.transaction.interceptor.DefaultTransactionAttribute()
 */
public class PetStoreImpl implements PetStoreFacade, OrderService {

We could add metadata to a method as follows:

/**
 * Normal comments here
 * @@org.springframework.transaction.interceptor.RuleBasedTransactionAttribute()
 * @@org.springframework.transaction.interceptor.RollbackRuleAttribute(Exception.class)
 * @@org.springframework.transaction.interceptor.NoRollbackRuleAttribute("ServletException")
 */
public void echoException(Exception ex) throws Exception {
    ....
}

Both of these examples use Jakarta Commons Attributes syntax.

Source-level metadata was introduced to the mainstream by XDoclet (in the Java world) and by the release of Microsoft's .NET platform, which uses source-level attributes to control transactions, pooling and other behavior.

The value in this approach has been recognized in the J2EE community. For example, it's much less verbose than the traditional XML deployment descriptors used exclusively by EJB. While it is desirable to externalize some things from program source code, some important enterprise settings - notably transaction characteristics - arguably belong in program source. Contrary to the assumptions of the EJB spec, it seldom makes sense to modify the transactional characteristics of a method (although parameters like transaction timeouts might change!).

Although metadata attributes are typically used mainly by framework infrastructure to describe the services application classes require, it should also be possible for metadata attributes to be queried at runtime. This is a key distinction from solutions such as XDoclet, which view metadata primarily as a way of generating code such as EJB artefacts.

There are a number of solutions in this space, including:

  • Standard Java Annotations: the standard Java metadata implementation (developed as JSR-175 and available in Java 5). Spring has specific Java 5 annotations for transactional demarcation, JMX, and aspects (to be precise they are AspectJ annotations). However, since Spring supports Java 1.4 as well, a solution for said JVM versions is needed too. Spring metadata support provides such a solution.

  • XDoclet: well-established solution, primarily intended for code generation.

  • Various open source attribute implementations, for Java 1.4, of which Commons Attributes is the most complete implementation. All these require a special pre- or post-compilation step.

25.2. Spring's metadata support

In keeping with its provision of abstractions over important concepts, Spring provides a facade to metadata implementations, in the form of the org.springframework.metadata.Attributes interface. Such a facade adds value for several reasons:

  • Even though Java 5 provides metadata support at language level, there will still be value in providing such an abstraction:

    • Java 5 metadata is static. It is associated with a class at compile time, and cannot be changed in a deployed environment (annotation state can actually be changed at runtime using reflection, but doing so would really be a bad practice). There is a need for hierarchical metadata, providing the ability to override certain attribute values in deployment - for example, in an XML file.

    • Java 5 metadata is returned through the Java reflection API. This makes it impossible to mock during test time. Spring provides a simple interface to allow this.

    • There will be a need for metadata support in 1.3 and 1.4 applications for at least two years. Spring aims to provide working solutions now; forcing the use of Java 5 is not an option in such an important area.

  • Current metadata APIs, such as Commons Attributes (used by Spring 1.0-1.2) are hard to test. Spring provides a simple metadata interface that is much easier to mock.

The Spring Attributes interface looks like this:

public interface Attributes {

    Collection getAttributes(Class targetClass);

    Collection getAttributes(Class targetClass, Class filter);

    Collection getAttributes(Method targetMethod);

    Collection getAttributes(Method targetMethod, Class filter);

    Collection getAttributes(Field targetField);

    Collection getAttributes(Field targetField, Class filter);
}

This is a lowest common denominator interface. JSR-175 offers more capabilities than this, such as attributes on method arguments.

Note that this interface offers Object attributes, like .NET. This distinguishes it from attribute systems such as that of Nanning Aspects, which offer only String attributes. There is a significant advantage in supporting Object attributes, namely that it enables attributes to participate in class hierarchies and allows such attributes to react intelligently to their configuration parameters.

With most attribute providers, attribute classes are configured via constructor arguments or JavaBean properties. Commons Attributes supports both.

As with all Spring abstraction APIs, Attributes is an interface. This makes it easy to mock attribute implementations for unit tests.

25.3. Annotations

The Spring Framework ships with a number of custom Java 5+ annotations.

25.3.1. @Required

The @Required annotation in the org.springframework.beans.factory.annotation package can be used to mark a property as being 'required-to-be-set' (i.e. an annotated (setter) method of a class must be configured to be dependency injected with a value), else an Exception will be thrown by the container at runtime.

The best way to illustrate the usage of this annotation is to show an example:

public class SimpleMovieLister {

    // the SimpleMovieLister has a dependency on the MovieFinder
    private MovieFinder movieFinder;

    // a setter method so that the Spring container can 'inject' a MovieFinder
    @Required
    public void setMovieFinder(MovieFinder movieFinder) {
        this.movieFinder = movieFinder;
    }
    
    // business logic that actually 'uses' the injected MovieFinder is omitted...
}

Hopefully the above class definition reads easy on the eye. Any and all BeanDefinitions for the SimpleMovieLister class must be provided with a value.

Let's look at an example of some XML configuration that will not pass validation.

<bean id="movieLister" class="x.y.SimpleMovieLister">
    <!-- whoops, no MovieFinder is set (and this property is @Required) -->
</bean>

At runtime the following message will be generated by the Spring container (the rest of the stack trace has been truncated).

Exception in thread "main" java.lang.IllegalArgumentException:
    Property 'movieFinder' is required for bean 'movieLister'.

There is one last little (small, tiny) piece of Spring configuration that is required to actually 'switch on' this behavior. Simply annotating the 'setter' properties of your classes is not enough to get this behavior. You need to enable a component that is aware of the @Required annotation and that can process it appropriately.

This component is the RequiredAnnotationBeanPostProcessor class. This is a special BeanPostProcessor implementation that is @Required-aware and actually provides the 'blow up if this required property has not been set' logic. It is very easy to configure; simply drop the following bean definition into your Spring XML configuration.

<bean class="org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor"/>

Finally, one can configure an instance of the RequiredAnnotationBeanPostProcessor class to look for another Annotation type. This is great if you already have your own @Required-style annotation. Simply plug it into the definition of a RequiredAnnotationBeanPostProcessor and you are good to go.

By way of an example, let's suppose you (or your organization / team) have defined an attribute called @ Mandatory. You can make a RequiredAnnotationBeanPostProcessor instance @Mandatory-aware like so:

<bean class="org.springframework.beans.factory.annotation.RequiredAnnotationBeanPostProcessor">
    <property name="requiredAnnotationType" value="your.company.package.Mandatory"/>
</bean>

Here is the source code for the @Mandatory annotation. You will need to ensure that your custom annotation type is itself annotated with appropriate annotations for it's target and runtime retention policy.

package your.company.package;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Mandatory {
}

25.3.2. Other @Annotations in Spring

Annotations are also used in a number of other places throughout Spring. Rather than being described here, these annotations are described in that section or chapter of the reference documentation to which they are most relevant.

25.4. Integration with Jakarta Commons Attributes

Presently Spring supports only Jakarta Commons Attributes out of the box, although it is easy to provide implementations of the org.springframework.metadata.Attributes interface for other metadata providers.

Commons Attributes 2.2 (http://jakarta.apache.org/commons/attributes/) is a capable attributes solution. It supports attribute configuration via constructor arguments and JavaBean properties, which offers better self-documentation in attribute definitions. (Support for JavaBean properties was added at the request of the Spring team.)

We've already seen two examples of Commons Attributes attributes definitions. In general, we will need to express:

  • The name of the attribute class. This can be a fully qualified name (FQN), as shown above. If the relevant attribute class has already been imported, the FQN isn't required. It's also possible to specify "attribute packages" in attribute compiler configuration.

  • Any necessary parameterization. This is done via constructor arguments or JavaBean properties.

Bean properties look as follows:

/**
 * @@MyAttribute(myBooleanJavaBeanProperty=true)
 */

It's possible to combine constructor arguments and JavaBean properties (as in Spring IoC).

Because, unlike Java 1.5 attributes, Commons Attributes is not integrated with the Java language, it is necessary to run a special attribute compilation step as part of the build process.

To run Commons Attributes as part of the build process, you will need to do the following:

1. Copy the necessary library jars to $ANT_HOME/lib. Four Jars are required, and all are distributed with Spring:

  • the Commons Attributes compiler jar and API jar

  • xJavadoc.jar from XDoclet

  • commons-collections.jar from Jakarta Commons

2. Import the Commons Attributes ant tasks into your project build script, as follows:

<taskdef resource="org/apache/commons/attributes/anttasks.properties"/>

3. Next, define an attribute compilation task, which will use the Commons Attributes attribute-compiler task to "compile" the attributes in the source. This process results in the generation of additional sources, to a location specified by the destdir attribute. Here we show the use of a temporary directory for storing the generated files:

<target name="compileAttributes">

  <attribute-compiler destdir="${commons.attributes.tempdir}">
    <fileset dir="${src.dir}" includes="**/*.java"/>
  </attribute-compiler>

</target>

The compile target that runs javac over the sources should depend on this attribute compilation task, and must also compile the generated sources, which we output to our destination temporary directory. If there are syntax errors in your attribute definitions, they will normally be caught by the attribute compiler. However, if the attribute definitions are syntactically plausible, but specify invalid types or class names, the compilation of the generated attribute classes may fail. In this case, you can look at the generated classes to establish the cause of the problem.

Commons Attributes also provides Maven support. Please refer to Commons Attributes documentation for further information.

While this attribute compilation process may look complex, in fact it's a one-off cost. Once set up, attribute compilation is incremental, so it doesn't usually noticeably slow the build process. And once the compilation process is set up, you may find that use of attributes as described in this chapter can save you a lot of time in other areas.

If you require attribute indexing support (only currently required by Spring for attribute-targeted web controllers, discussed below), you will need an additional step, which must be performed on a jar file of your compiled classes. In this additional step, Commons Attributes will create an index of all the attributes defined on your sources, for efficient lookup at runtime. The step looks like this:

<attribute-indexer jarFile="myCompiledSources.jar">
    
  <classpath refid="master-classpath"/>

</attribute-indexer>
See the /attributes directory of the Spring JPetStore sample application for an example of this build process. You can take the build script it contains and modify it for your own projects.

If your unit tests depend on attributes, try to express the dependency on the Spring Attributes abstraction, rather than Commons Attributes. Not only is this more portable - for example, your tests will still work if you switch to Java 1.5 attributes in future - it simplifies testing. Also, Commons Attributes is a static API, while Spring provides a metadata interface that you can easily mock.

25.5. Metadata and Spring AOP autoproxying

The most important uses of metadata attributes are in conjunction with Spring AOP. This provides a .NET-like programming model, where declarative services are automatically provided to application objects that declare metadata attributes. Such metadata attributes can be supported out of the box by the framework, as in the case of declarative transaction management, or can be custom.

25.5.1. Fundamentals

This builds on the Spring AOP autoproxy functionality. Configuration might look like this:

<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator"/>

<bean class="org.springframework.transaction.interceptor.TransactionAttributeSourceAdvisor">
  <property name="transactionInterceptor" ref="txInterceptor" />
</bean>

<bean id="txInterceptor" class="org.springframework.transaction.interceptor.TransactionInterceptor">
  <property name="transactionManager" ref="transactionManager" />
  <property name="transactionAttributeSource">
    <bean class="org.springframework.transaction.interceptor.AttributesTransactionAttributeSource">
      <property name="attributes" ref="attributes" />
    </bean>
  </property>
</bean>

<bean id="attributes" class="org.springframework.metadata.commons.CommonsAttributes" />

The basic concepts here should be familiar from the discussion of autoproxying in the AOP chapter.

The most important bean definitions are the auto-proxy creator and the advisor. Note that the actual bean names are not important; what matters is their class.

The bean definition of class org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator will automatically advise ("auto-proxy") all bean instances in the current factory based on matching advisor implementations. This class knows nothing about attributes, but relies on advisors' pointcuts matching. The pointcuts, however, do know about attributes.

Thus we simply need an AOP advisor that will provide declarative transaction management based on attributes.

It is possible to add arbitrary custom advisor implementations as well, and they will also be evaluated and applied automatically. (You can use advisors whose pointcuts match on criteria besides attributes in the same autoproxy configuration, if necessary.)

Finally, the attributes bean is the Commons Attributes Attributes implementation. Replace it with another implementation of the org.springframework.metadata.Attributes interface to source attributes from a different source.

25.5.2. Declarative transaction management

The most common use of source-level attributes is to provide declarative transaction management. Once the bean definitions shown above are in place, you can define any number of application objects requiring declarative transactions. Only those classes or methods with transaction attributes will be given transaction advice. You need to do nothing except define the required transaction attributes.

Please note that you can specify transaction attributes at either class or method level. Class-level attributes, if specified, will be "inherited" by all methods whereas method attributes will wholly override any class-level attributes.

25.5.3. Pooling

You can also enable pooling behavior via class-level attributes. Spring can apply this behavior to any POJO. You simply need to specify a pooling attribute, as follows, in the business object to be pooled:

 /** 
 * @@org.springframework.aop.framework.autoproxy.target.PoolingAttribute(10)
 */
public class MyClass {

You'll need the usual autoproxy infrastructure configuration. You then need to specify a pooling TargetSourceCreator, as follows. Because pooling affects the creation of the target, we can't use a regular advice. Note that pooling will apply even if there are no advisors applicable to the class, if that class has a pooling attribute.

<bean id="poolingTargetSourceCreator"
  class="org.springframework.aop.framework.autoproxy.metadata.AttributesPoolingTargetSourceCreator">
  <property name="attributes" ref="attributes" />
</bean>

The relevant autoproxy bean definition needs to specify a list of "custom target source creators", including the Pooling target source creator. We could modify the example shown above to include this property as follows:

<bean class="org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator">
  <property name="customTargetSourceCreators">
    <list>
      <ref bean="poolingTargetSourceCreator" />
    </list>
  </property>
</bean>

As with the use of metadata in Spring in general, this is a one-off cost: once setup is out of the way, it's very easy to use pooling for additional business objects.

It's arguable that the need for pooling is rare, so there's seldom a need to apply pooling to a large number of business objects. Hence this feature does not appear to be used often.

Please see the Javadoc for the org.springframework.aop.framework.autoproxy package for more details. It's possible to use a different pooling implementation than Commons Pool with minimal custom coding.

25.5.4. Custom metadata

We can even go beyond the capabilities of .NET metadata attributes, because of the flexibility of the underlying autoproxying infrastructure.

We can define custom attributes, to provide any kind of declarative behavior. To do this, you need to:

  • Define your custom attribute class.

  • Define a Spring AOP Advisor with a pointcut that fires on the presence of this custom attribute.

  • Add that Advisor as a bean definition to an application context with the generic autoproxy infrastructure in place.

  • Add attributes to your POJOs.

There are several potential areas you might want to do this, such as custom declarative security, or possibly caching.

This is a powerful mechanism which can significantly reduce configuration effort in some projects. However, remember that it does rely on AOP under the covers. The more advisors you have in play, the more complex your runtime configuration will be. (If you want to see what advice applies to any object, try casting a reference to org.springframework.aop.framework.Advised. This will enable you to examine the advisors.)

25.6. Using attributes to minimize MVC web tier configuration

The other main use of Spring metadata as of 1.0 is to provide an option to simplify Spring MVC web configuration.

Spring MVC offers flexible handler mappings: mappings of incoming request to controller (or other handler) instance. Normally handler mappings are configured in the xxxx-servlet.xml file for the relevant Spring DispatcherServlet.

Holding these mappings in the DispatcherServlet configuration file is normally A Good Thing. It provides maximum flexibility. In particular:

  • The controller instance is explicitly managed by Spring IoC, through an XML bean definition.

  • The mapping is external to the controller, so the same controller instance could be given multiple mappings in the same DispatcherServlet context or reused in a different configuration.

  • Spring MVC is able to support mappings based on any criteria, rather than merely the request URL-to-controller mappings available in most other frameworks.

However, this does mean that for each controller we typically need both a handler mapping (normally in a handler mapping XML bean definition) and an XML mapping for the controller itself.

Spring offers a simpler approach based on source-level attributes, which is an attractive option in simpler scenarios.

The approach described in this section is best suited to relatively simple MVC scenarios. It sacrifices some of the power of Spring MVC, such as the ability to use the same controller with different mappings, and the ability to base mappings on something other than request URL.

In this approach, controllers are marked with one or more class-level metadata attributes, each specifying one URL they should be mapped to.

The following examples show the approach. In each case, we have a controller that depends on a business object of type Cruncher. As usual, this dependency will be resolved by Dependency Injection. The Cruncher must be available through a bean definition in the relevant DispatcherServlet XML file, or a parent context.

We attach an attribute to the controller class specifying the URL that should map to it. We can express the dependency through a JavaBean property or a constructor argument. This dependency must be resolvable by autowiring: that is, there must be exactly one business object of type Cruncher available in the context.

/**
 * Normal comments here
 *
 * @@org.springframework.web.servlet.handler.metadata.PathMap("/bar.cgi")
 */
public class BarController extends AbstractController {

    private Cruncher cruncher;

    public void setCruncher(Cruncher cruncher) {
        this.cruncher = cruncher;
    }

    protected ModelAndView handleRequestInternal (
            HttpServletRequest request, HttpServletResponse response) throws Exception {
        System.out.println("Bar Crunching c and d =" + cruncher.concatenate("c", "d"));
        return new ModelAndView("test");
    }
}

For this auto-mapping to work, we need to add the following to the relevant xxxx-servlet.xml file, specifying the attributes handler mapping. This special handler mapping can handle any number of controllers with attributes as shown above. The bean id ("commonsAttributesHandlerMapping") is not important. The type is what matters:

<bean id="commonsAttributesHandlerMapping"      
    class="org.springframework.web.servlet.handler.metadata.CommonsPathMapHandlerMapping"/>

We do not currently need an Attributes bean definition, as in the above example, because this class works directly with the Commons Attributes API, not via the Spring metadata abstraction.

We now need no XML configuration for each controller. Controllers are automatically mapped to the specified URL(s). Controllers benefit from IoC, using Spring's autowiring capability. For example, the dependency expressed in the "cruncher" bean property of the simple controller shown above is automatically resolved in the current web application context. Both Setter and Constructor Dependency Injection are available, each with zero configuration.

An example of Constructor Injection, also showing multiple URL paths:

/**
 * Normal comments here
 *
 * @@org.springframework.web.servlet.handler.metadata.PathMap("/foo.cgi")
 * @@org.springframework.web.servlet.handler.metadata.PathMap("/baz.cgi")
 */
public class FooController extends AbstractController {

    private Cruncher cruncher;

    public FooController(Cruncher cruncher) {
        this.cruncher = cruncher;
    }

    protected ModelAndView handleRequestInternal (
            HttpServletRequest request, HttpServletResponse response) throws Exception {
        return new ModelAndView("test");
    }
}

This approach has the following benefits:

  • Significantly reduced volume of configuration. Each time we add a controller we need add no XML configuration. As with attribute-driven transaction management, once the basic infrastructure is in place, it is very easy to add more application classes.

  • We retain much of the power of Spring IoC to configure controllers.

This approach has the following limitations:

  • One-off cost in a more complex build process. We need an attribute compilation step and an attribute indexing step. However, once in place, this should not be an issue.

  • Currently Commons Attributes only, although support for other attribute providers may be added in future.

  • Only "autowiring by type" dependency injection is supported for such controllers. However, this still leaves them far in advance of Struts Actions (with no IoC support from the framework) and, arguably, WebWork Actions (with only rudimentary IoC support) where IoC is concerned.

  • Reliance on automagical IoC resolution may be confusing.

Because autowiring by type means there must be exactly one dependency of the specified type, we need to be careful if we use AOP. In the common case using TransactionProxyFactoryBean, for example, we end up with two implementations of a business interface such as Cruncher: the original POJO definition, and the transactional AOP proxy. This won't work, as the owning application context can't resolve the type dependency unambiguously. The solution is to use AOP autoproxying, setting up the autoproxy infrastructure so that there is only one implementation of Cruncher defined, and that implementation is automatically advised. Thus this approach works well with attribute-targeted declarative services as described above. As the attributes compilation process must be in place to handle the web controller targeting, this is easy to set up.

Unlike other metadata functionality, there is currently only a Commons Attributes implementation available: org.springframework.web.servlet.handler.metadata.CommonsPathMapHandlerMapping. This limitation is due to the fact that not only do we need attribute compilation, we need attribute indexing: the ability to ask the attributes API for all classes with the PathMap attribute. Indexing is not currently offered on the org.springframework.metadata.Attributes abstraction interface, although it may be in future. (If you want to add support for another attributes implementation - which must support indexing - you can easily extend the AbstractPathMapHandlerMapping superclass of CommonsPathMapHandlerMapping, implementing the two protected abstract methods to use your preferred attributes API.)

In summary, we need two additional steps in the build process: attribute compilation and attribute indexing. Use of the attribute indexer task was shown above. Note that Commons Attributes presently requires a jar file as input to indexing.