# Annotation-based container configuration

## Are annotations better than XML for configuring Spring?

The introduction of annotation-based configurations raised the question of whether this approach is 'better' than XML. The short answer is it depends. The long answer is that each approach has its pros and cons, and usually it is up to the developer to decide which strategy suits her better. Due to the way they are defined, annotations provide a lot of context in their declaration, leading to shorter and more concise configuration. However, XML excels at wiring up components without touching their source code or recompiling them. Some developers prefer having the wiring close to the source while others argue that annotated classes are no longer POJOs and, furthermore, that the configuration becomes decentralized and harder to control.

No matter the choice, Spring can accommodate both styles and even mix them together. It's worth pointing out that through its JavaConfig option, Spring allows annotations to be used in a non-invasive way, without touching the target components source code and that in terms of tooling, all configuration styles are supported by the SpringSource Tool Suite.

An alternative to XML setups is provided by annotation-based configuration which rely on the bytecode metadata for wiring up components instead of angle-bracket declarations. Instead of using XML to describe a bean wiring, the developer moves the configuration into the component class itself by using annotations on the relevant class, method, or field declaration. As mentioned in beans-factory-extension-bpp-examples-rabpp, using a BeanPostProcessor in conjunction with annotations is a common means of extending the Spring IoC container. For example, Spring 2.0 introduced the possibility of enforcing required properties with the @Required annotation. Spring 2.5 made it possible to follow that same general approach to drive Spring's dependency injection. Essentially, the @Autowired annotation provides the same capabilities as described in beans-factory-autowire but with more fine-grained control and wider applicability. Spring 2.5 also added support for JSR-250 annotations such as @PostConstruct, and @PreDestroy. Spring 3.0 added support for JSR-330 (Dependency Injection for Java) annotations contained in the javax.inject package such as `@Inject` and `@Named`. Details about those annotations can be found in the relevant section.

Annotation injection is performed before XML injection, thus the latter configuration will override the former for properties wired through both approaches.

As always, you can register them as individual bean definitions, but they can also be implicitly registered by including the following tag in an XML-based Spring configuration (notice the inclusion of the `context` namespace):

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns:context="http://www.springframework.org/schema/context"
         xsi:schemaLocation="http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans.xsd
             http://www.springframework.org/schema/context
             http://www.springframework.org/schema/context/spring-context.xsd">

       <context:annotation-config/>

    </beans>

(The implicitly registered post-processors include `AutowiredAnnotationBeanPostProcessor`, `CommonAnnotationBeanPostProcessor`, `PersistenceAnnotationBeanPostProcessor`, as well as the aforementioned `RequiredAnnotationBeanPostProcessor`.)

`<context:annotation-config/>` only looks for annotations on beans in the same application context in which it is defined. This means that, if you put `<context:annotation-config/>` in a WebApplicationContext for a `DispatcherServlet`, it only checks for @Autowired beans in your controllers, and not your services. See mvc-servlet for more information.

## @Required

The @Required annotation applies to bean property setter methods, as in the following example:

    public class SimpleMovieLister {

      private MovieFinder movieFinder;

      @Required
      public void setMovieFinder(MovieFinder movieFinder) {
          this.movieFinder = movieFinder;
      }

      // ...
    }

This annotation simply indicates that the affected bean property must be populated at configuration time, through an explicit property value in a bean definition or through autowiring. The container throws an exception if the affected bean property has not been populated; this allows for eager and explicit failure, avoiding `NullPointerException`s or the like later on. It is still recommended that you put assertions into the bean class itself, for example, into an init method. Doing so enforces those required references and values even when you use the class outside of a container.

## @Autowired

As expected, you can apply the @Autowired annotation to "traditional" setter methods:

    public class SimpleMovieLister {

      private MovieFinder movieFinder;

      @Autowired
      public void setMovieFinder(MovieFinder movieFinder) {
          this.movieFinder = movieFinder;
      }

      // ...
    }

JSR 330's @Inject annotation can be used in place of Spring's @Autowired annotation in the examples below. See here for more details

You can also apply the annotation to methods with arbitrary names and/or multiple arguments:

    public class MovieRecommender {

      private MovieCatalog movieCatalog;

      private CustomerPreferenceDao customerPreferenceDao;

      @Autowired
      public void prepare(MovieCatalog movieCatalog,
                          CustomerPreferenceDao customerPreferenceDao) {
          this.movieCatalog = movieCatalog;
          this.customerPreferenceDao = customerPreferenceDao;
      }

      // ...
    }

You can apply @Autowired to constructors and fields:

    public class MovieRecommender {

      @Autowired
      private MovieCatalog movieCatalog;

      private CustomerPreferenceDao customerPreferenceDao;

      @Autowired
      public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) {
          this.customerPreferenceDao = customerPreferenceDao;
      }

      // ...
    }

It is also possible to provide all beans of a particular type from the ApplicationContext by adding the annotation to a field or method that expects an array of that type:

    public class MovieRecommender {

      @Autowired
      private MovieCatalog[] movieCatalogs;

      // ...
    }

The same applies for typed collections:

    public class MovieRecommender {

      private Set<MovieCatalog> movieCatalogs;

      @Autowired
      public void setMovieCatalogs(Set<MovieCatalog> movieCatalogs) {
          this.movieCatalogs = movieCatalogs;
      }

      // ...
    }

Even typed Maps can be autowired as long as the expected key type is `String`. The Map values will contain all beans of the expected type, and the keys will contain the corresponding bean names:

    public class MovieRecommender {

      private Map<String, MovieCatalog> movieCatalogs;

      @Autowired
      public void setMovieCatalogs(Map<String, MovieCatalog> movieCatalogs) {
          this.movieCatalogs = movieCatalogs;
      }

      // ...
    }

By default, the autowiring fails whenever zero candidate beans are available; the default behavior is to treat annotated methods, constructors, and fields as indicating required dependencies. This behavior can be changed as demonstrated below.

    public class SimpleMovieLister {

      private MovieFinder movieFinder;

      @Autowired(required=false)
      public void setMovieFinder(MovieFinder movieFinder) {
          this.movieFinder = movieFinder;
      }

      // ...
    }

Only one annotated constructor per-class can be marked as required, but multiple non-required constructors can be annotated. In that case, each is considered among the candidates and Spring uses the greediest constructor whose dependencies can be satisfied, that is the constructor that has the largest number of arguments.

@Autowired's required attribute is recommended over the @Required annotation. The required attribute indicates that the property is not required for autowiring purposes, the property is ignored if it cannot be autowired. @Required, on the other hand, is stronger in that it enforces the property that was set by any means supported by the container. If no value is injected, a corresponding exception is raised.

You can also use @Autowired for interfaces that are well-known resolvable dependencies: BeanFactory, ApplicationContext, Environment, ResourceLoader, ApplicationEventPublisher, and MessageSource. These interfaces and their extended interfaces, such as ConfigurableApplicationContext or ResourcePatternResolver, are automatically resolved, with no special setup necessary.

    public class MovieRecommender {

      @Autowired
      private ApplicationContext context;

      public MovieRecommender() {
      }

      // ...
    }

@Autowired, @Inject, @Resource, and @Value annotations are handled by a Spring BeanPostProcessor implementations which in turn means that you cannot apply these annotations within your own `BeanPostProcessor` or `BeanFactoryPostProcessor` types (if any). These types must be 'wired up' explicitly via XML or using a Spring @Bean method.

## Fine-tuning annotation-based autowiring with qualifiers

Because autowiring by type may lead to multiple candidates, it is often necessary to have more control over the selection process. One way to accomplish this is with Spring's @Qualifier annotation. You can associate qualifier values with specific arguments, narrowing the set of type matches so that a specific bean is chosen for each argument. In the simplest case, this can be a plain descriptive value:

    public class MovieRecommender {

      @Autowired
      @Qualifier("main")
      private MovieCatalog movieCatalog;

      // ...
    }

The @Qualifier annotation can also be specified on individual constructor arguments or method parameters:

    public class MovieRecommender {

      private MovieCatalog movieCatalog;

      private CustomerPreferenceDao customerPreferenceDao;

      @Autowired
      public void prepare(@Qualifier("main") MovieCatalog movieCatalog,
                          CustomerPreferenceDao customerPreferenceDao) {
          this.movieCatalog = movieCatalog;
          this.customerPreferenceDao = customerPreferenceDao;
      }

      // ...
    }

The corresponding bean definitions appear as follows. The bean with qualifier value "main" is wired with the constructor argument that is qualified with the same value.

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:context="http://www.springframework.org/schema/context"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://www.springframework.org/schema/context
          http://www.springframework.org/schema/context/spring-context.xsd">

      <context:annotation-config/>

      <bean class="example.SimpleMovieCatalog">
          <qualifier value="main"/>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean class="example.SimpleMovieCatalog">
          <qualifier value="action"/>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean id="movieRecommender" class="example.MovieRecommender"/>

    </beans>

For a fallback match, the bean name is considered a default qualifier value. Thus you can define the bean with an id "main" instead of the nested qualifier element, leading to the same matching result. However, although you can use this convention to refer to specific beans by name, @Autowired is fundamentally about type-driven injection with optional semantic qualifiers. This means that qualifier values, even with the bean name fallback, always have narrowing semantics within the set of type matches; they do not semantically express a reference to a unique bean id. Good qualifier values are "main" or "EMEA" or "persistent", expressing characteristics of a specific component that are independent from the bean id, which may be auto-generated in case of an anonymous bean definition like the one in the preceding example.

Qualifiers also apply to typed collections, as discussed above, for example, to `Set<MovieCatalog>`. In this case, all matching beans according to the declared qualifiers are injected as a collection. This implies that qualifiers do not have to be unique; they rather simply constitute filtering criteria. For example, you can define multiple `MovieCatalog` beans with the same qualifier value "action"; all of which would be injected into a `Set<MovieCatalog>` annotated with `@Qualifier("action")`.

If you intend to express annotation-driven injection by name, do not primarily use @Autowired, even if is technically capable of referring to a bean name through @Qualifier values. Instead, use the JSR-250 @Resource annotation, which is semantically defined to identify a specific target component by its unique name, with the declared type being irrelevant for the matching process.

As a specific consequence of this semantic difference, beans that are themselves defined as a collection or map type cannot be injected through @Autowired, because type matching is not properly applicable to them. Use @Resource for such beans, referring to the specific collection or map bean by unique name.

@Autowired applies to fields, constructors, and multi-argument methods, allowing for narrowing through qualifier annotations at the parameter level. By contrast, @Resource is supported only for fields and bean property setter methods with a single argument. As a consequence, stick with qualifiers if your injection target is a constructor or a multi-argument method.

You can create your own custom qualifier annotations. Simply define an annotation and provide the @Qualifier annotation within your definition:

    @Target({ElementType.FIELD, ElementType.PARAMETER})
    @Retention(RetentionPolicy.RUNTIME)
    @Qualifier
    public @interface Genre {

      String value();
    }

Then you can provide the custom qualifier on autowired fields and parameters:

    public class MovieRecommender {

      @Autowired
      @Genre("Action")
      private MovieCatalog actionCatalog;

      private MovieCatalog comedyCatalog;

      @Autowired
      public void setComedyCatalog(@Genre("Comedy") MovieCatalog comedyCatalog) {
          this.comedyCatalog = comedyCatalog;
      }

      // ...
    }

Next, provide the information for the candidate bean definitions. You can add `<qualifier/>` tags as sub-elements of the `<bean/>` tag and then specify the `type` and `value` to match your custom qualifier annotations. The type is matched against the fully-qualified class name of the annotation. Or, as a convenience if no risk of conflicting names exists, you can use the short class name. Both approaches are demonstrated in the following example.

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:context="http://www.springframework.org/schema/context"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://www.springframework.org/schema/context
          http://www.springframework.org/schema/context/spring-context.xsd">

      <context:annotation-config/>

      <bean class="example.SimpleMovieCatalog">
          <qualifier type="Genre" value="Action"/>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean class="example.SimpleMovieCatalog">
          <qualifier type="example.Genre" value="Comedy"/>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean id="movieRecommender" class="example.MovieRecommender"/>

    </beans>

In beans-classpath-scanning, you will see an annotation-based alternative to providing the qualifier metadata in XML. Specifically, see beans-scanning-qualifiers.

In some cases, it may be sufficient to use an annotation without a value. This may be useful when the annotation serves a more generic purpose and can be applied across several different types of dependencies. For example, you may provide an offline catalog that would be searched when no Internet connection is available. First define the simple annotation:

    @Target({ElementType.FIELD, ElementType.PARAMETER})
    @Retention(RetentionPolicy.RUNTIME)
    @Qualifier
    public @interface Offline {

    }

Then add the annotation to the field or property to be autowired:

    public class MovieRecommender {

      @Autowired
      @Offline
      private MovieCatalog offlineCatalog;

      // ...
    }

Now the bean definition only needs a qualifier `type`:

    <bean class="example.SimpleMovieCatalog">
      <qualifier type="Offline"/>
      <!-- inject any dependencies required by this bean -->
    </bean>

You can also define custom qualifier annotations that accept named attributes in addition to or instead of the simple `value` attribute. If multiple attribute values are then specified on a field or parameter to be autowired, a bean definition must match all such attribute values to be considered an autowire candidate. As an example, consider the following annotation definition:

    @Target({ElementType.FIELD, ElementType.PARAMETER})
    @Retention(RetentionPolicy.RUNTIME)
    @Qualifier
    public @interface MovieQualifier {

      String genre();

      Format format();
    }

In this case `Format` is an enum:

    public enum Format {

      VHS, DVD, BLURAY
    }

The fields to be autowired are annotated with the custom qualifier and include values for both attributes: `genre` and `format`.

    public class MovieRecommender {

      @Autowired
      @MovieQualifier(format=Format.VHS, genre="Action")
      private MovieCatalog actionVhsCatalog;

      @Autowired
      @MovieQualifier(format=Format.VHS, genre="Comedy")
      private MovieCatalog comedyVhsCatalog;

      @Autowired
      @MovieQualifier(format=Format.DVD, genre="Action")
      private MovieCatalog actionDvdCatalog;

      @Autowired
      @MovieQualifier(format=Format.BLURAY, genre="Comedy")
      private MovieCatalog comedyBluRayCatalog;

      // ...
    }

Finally, the bean definitions should contain matching qualifier values. This example also demonstrates that bean meta attributes may be used instead of the `<qualifier/>` sub-elements. If available, the `<qualifier/>` and its attributes take precedence, but the autowiring mechanism falls back on the values provided within the `<meta/>` tags if no such qualifier is present, as in the last two bean definitions in the following example.

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:context="http://www.springframework.org/schema/context"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
          http://www.springframework.org/schema/beans/spring-beans.xsd
          http://www.springframework.org/schema/context
          http://www.springframework.org/schema/context/spring-context.xsd">

      <context:annotation-config/>

      <bean class="example.SimpleMovieCatalog">
          <qualifier type="MovieQualifier">
              <attribute key="format" value="VHS"/>
              <attribute key="genre" value="Action"/>
          </qualifier>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean class="example.SimpleMovieCatalog">
          <qualifier type="MovieQualifier">
              <attribute key="format" value="VHS"/>
              <attribute key="genre" value="Comedy"/>
          </qualifier>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean class="example.SimpleMovieCatalog">
          <meta key="format" value="DVD"/>
          <meta key="genre" value="Action"/>
          <!-- inject any dependencies required by this bean -->
      </bean>

      <bean class="example.SimpleMovieCatalog">
          <meta key="format" value="BLURAY"/>
          <meta key="genre" value="Comedy"/>
          <!-- inject any dependencies required by this bean -->
      </bean>

    </beans>

## `CustomAutowireConfigurer`

The `CustomAutowireConfigurer` is a BeanFactoryPostProcessor that enables you to register your own custom qualifier annotation types even if they are not annotated with Spring's @Qualifier annotation.

    <bean id="customAutowireConfigurer"
         class="org.springframework.beans.factory.annotation.CustomAutowireConfigurer">
      <property name="customQualifierTypes">
          <set>
              <value>example.CustomQualifier</value>
          </set>
      </property>
    </bean>

The particular implementation of AutowireCandidateResolver that is activated for the application context depends on the Java version. In versions earlier than Java 5, the qualifier annotations are not supported, and therefore autowire candidates are solely determined by the `autowire-candidate` value of each bean definition as well as by any `default-autowire-candidates` pattern(s) available on the `<beans/>` element. In Java 5 or later, the presence of @Qualifier annotations and any custom annotations registered with the `CustomAutowireConfigurer` will also play a role.

Regardless of the Java version, when multiple beans qualify as autowire candidates, the determination of a "primary" candidate is the same: if exactly one bean definition among the candidates has a `primary` attribute set to `true`, it will be selected.

## @Resource

Spring also supports injection using the JSR-250 @Resource annotation on fields or bean property setter methods. This is a common pattern in Java EE 5 and 6, for example in JSF 1.2 managed beans or JAX-WS 2.0 endpoints. Spring supports this pattern for Spring-managed objects as well.

@Resource takes a name attribute, and by default Spring interprets that value as the bean name to be injected. In other words, it follows by-name semantics, as demonstrated in this example:

    public class SimpleMovieLister {

      private MovieFinder movieFinder;

      @Resource(name="myMovieFinder")
      public void setMovieFinder(MovieFinder movieFinder) {
          this.movieFinder = movieFinder;
      }
    }

If no name is specified explicitly, the default name is derived from the field name or setter method. In case of a field, it takes the field name; in case of a setter method, it takes the bean property name. So the following example is going to have the bean with name "movieFinder" injected into its setter method:

    public class SimpleMovieLister {

      private MovieFinder movieFinder;

      @Resource
      public void setMovieFinder(MovieFinder movieFinder) {
          this.movieFinder = movieFinder;
      }
    }

The name provided with the annotation is resolved as a bean name by the ApplicationContext of which the `CommonAnnotationBeanPostProcessor` is aware. The names can be resolved through JNDI if you configure Spring's `SimpleJndiBeanFactory` explicitly. However, it is recommended that you rely on the default behavior and simply use Spring's JNDI lookup capabilities to preserve the level of indirection.

In the exclusive case of @Resource usage with no explicit name specified, and similar to @Autowired, @Resource finds a primary type match instead of a specific named bean and resolves well-known resolvable dependencies: the BeanFactory, ApplicationContext, ResourceLoader, ApplicationEventPublisher, and MessageSource interfaces.

Thus in the following example, the `customerPreferenceDao` field first looks for a bean named customerPreferenceDao, then falls back to a primary type match for the type `CustomerPreferenceDao`. The "context" field is injected based on the known resolvable dependency type ApplicationContext.

    public class MovieRecommender {

      @Resource
      private CustomerPreferenceDao customerPreferenceDao;

      @Resource
      private ApplicationContext context;

      public MovieRecommender() {
      }

      // ...
    }

## @PostConstruct and @PreDestroy

The `CommonAnnotationBeanPostProcessor` not only recognizes the @Resource annotation but also the JSR-250 lifecycle annotations. Introduced in Spring 2.5, the support for these annotations offers yet another alternative to those described in initialization callbacks and destruction callbacks. Provided that the `CommonAnnotationBeanPostProcessor` is registered within the Spring ApplicationContext, a method carrying one of these annotations is invoked at the same point in the lifecycle as the corresponding Spring lifecycle interface method or explicitly declared callback method. In the example below, the cache will be pre-populated upon initialization and cleared upon destruction.

    public class CachingMovieLister {

      @PostConstruct
      public void populateMovieCache() {
          // populates the movie cache upon initialization...
      }

      @PreDestroy
      public void clearMovieCache() {
          // clears the movie cache upon destruction...
      }
    }

For details about the effects of combining various lifecycle mechanisms, see beans-factory-lifecycle-combined-effects.