CommonAnnotationBeanPostProcessor (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.context.annotation

## Class CommonAnnotationBeanPostProcessor

- java.lang.Object
- - org.springframework.beans.factory.annotation.InitDestroyAnnotationBeanPostProcessor
  - - org.springframework.context.annotation.CommonAnnotationBeanPostProcessor

- All Implemented Interfaces:
    Serializable, Aware, BeanFactoryAware, BeanPostProcessor, DestructionAwareBeanPostProcessor, InstantiationAwareBeanPostProcessor, MergedBeanDefinitionPostProcessor, Ordered, PriorityOrdered

      public class CommonAnnotationBeanPostProcessor
      extends InitDestroyAnnotationBeanPostProcessor
      implements InstantiationAwareBeanPostProcessor, BeanFactoryAware, Serializable

  `BeanPostProcessor` implementation that supports common Java annotations out of the box, in particular the JSR-250 annotations in the `javax.annotation` package. These common Java annotations are supported in many Java EE 5 technologies (e.g. JSF 1.2), as well as in Java 6's JAX-WS.

  This post-processor includes support for the `PostConstruct` and `PreDestroy` annotations - as init annotation and destroy annotation, respectively - through inheriting from `InitDestroyAnnotationBeanPostProcessor` with pre-configured annotation types.

  The central element is the `Resource` annotation for annotation-driven injection of named beans, by default from the containing Spring BeanFactory, with only `mappedName` references resolved in JNDI. The `"alwaysUseJndiLookup" flag` enforces JNDI lookups equivalent to standard Java EE 5 resource injection for `name` references and default names as well. The target beans can be simple POJOs, with no special requirements other than the type having to match.

  The JAX-WS `WebServiceRef` annotation is supported too, analogous to `Resource` but with the capability of creating specific JAX-WS service endpoints. This may either point to an explicitly defined resource by name or operate on a locally specified JAX-WS service class. Finally, this post-processor also supports the EJB 3 `EJB` annotation, analogous to `Resource` as well, with the capability to specify both a local bean name and a global JNDI name for fallback retrieval. The target beans can be plain POJOs as well as EJB 3 Session Beans in this case.

  The common annotations supported by this post-processor are available in Java 6 (JDK 1.6) as well as in Java EE 5/6 (which provides a standalone jar for its common annotations as well, allowing for use in any Java 5 based application). Hence, this post-processor works out of the box on JDK 1.6, and requires the JSR-250 API jar (and optionally the JAX-WS API jar and/or the EJB 3 API jar) to be added to the classpath on JDK 1.5 (when running outside of Java EE 5/6).

  For default usage, resolving resource names as Spring bean names, simply define the following in your application context:

       <bean class="org.springframework.context.annotation.CommonAnnotationBeanPostProcessor"/>

  For direct JNDI access, resolving resource names as JNDI resource references within the Java EE application's "java:comp/env/" namespace, use the following:

       <bean class="org.springframework.context.annotation.CommonAnnotationBeanPostProcessor">
         <property name="alwaysUseJndiLookup" value="true"/>
       </bean>

  `mappedName` references will always be resolved in JNDI, allowing for global JNDI names (including "java:" prefix) as well. The "alwaysUseJndiLookup" flag just affects `name` references and default names (inferred from the field name / property name).

  NOTE: A default CommonAnnotationBeanPostProcessor will be registered by the "context:annotation-config" and "context:component-scan" XML tags. Remove or turn off the default annotation configuration there if you intend to specify a custom CommonAnnotationBeanPostProcessor bean definition!

  NOTE: Annotation injection will be performed before XML injection; thus the latter configuration will override the former for properties wired through both approaches.

  Since:
    2.5
  Author:
    Juergen Hoeller
  See Also:
    `setAlwaysUseJndiLookup(boolean)`, `setResourceFactory(org.springframework.beans.factory.BeanFactory)`, `InitDestroyAnnotationBeanPostProcessor`, `AutowiredAnnotationBeanPostProcessor`, Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `CommonAnnotationBeanPostProcessor.LookupElement` Class representing generic injection information about an annotated field or setter method, supporting @Resource and related annotations.

  - ### Field Summary

    - ### Fields inherited from class org.springframework.beans.factory.annotation.InitDestroyAnnotationBeanPostProcessor

      `logger`

    - ### Fields inherited from interface org.springframework.core.Ordered

      `HIGHEST_PRECEDENCE, LOWEST_PRECEDENCE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CommonAnnotationBeanPostProcessor()` Create a new CommonAnnotationBeanPostProcessor, with the init and destroy annotation types set to `PostConstruct` and `PreDestroy`, respectively.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `autowireResource(BeanFactory factory, CommonAnnotationBeanPostProcessor.LookupElement element, String requestingBeanName)` Obtain a resource object for the given name and type through autowiring based on the given factory.
    `protected Object` | `getResource(CommonAnnotationBeanPostProcessor.LookupElement element, String requestingBeanName)` Obtain the resource object for the given name and type.
    `void` | `ignoreResourceType(String resourceType)` Ignore the given resource type when resolving `@Resource` annotations.
    `boolean` | `postProcessAfterInstantiation(Object bean, String beanName)` Perform operations after the bean has been instantiated, via a constructor or factory method, but before Spring property population (from explicit properties or autowiring) occurs.
    `Object` | `postProcessBeforeInstantiation(Class<?> beanClass, String beanName)` Apply this BeanPostProcessor before the target bean gets instantiated.
    `void` | `postProcessMergedBeanDefinition(RootBeanDefinition beanDefinition, Class<?> beanType, String beanName)` Post-process the given merged bean definition for the specified bean.
    `PropertyValues` | `postProcessPropertyValues(PropertyValues pvs, PropertyDescriptor[] pds, Object bean, String beanName)` Post-process the given property values before the factory applies them to the given bean.
    `void` | `setAlwaysUseJndiLookup(boolean alwaysUseJndiLookup)` Set whether to always use JNDI lookups equivalent to standard Java EE 5 resource injection, even for `name` attributes and default names.
    `void` | `setBeanFactory(BeanFactory beanFactory)` Callback that supplies the owning factory to a bean instance.
    `void` | `setFallbackToDefaultTypeMatch(boolean fallbackToDefaultTypeMatch)` Set whether to allow a fallback to a type match if no explicit name has been specified.
    `void` | `setJndiFactory(BeanFactory jndiFactory)` Specify the factory for objects to be injected into `@Resource` / `@WebServiceRef` / `@EJB` annotated fields and setter methods, for `mappedName` attributes that point directly into JNDI.
    `void` | `setResourceFactory(BeanFactory resourceFactory)` Specify the factory for objects to be injected into `@Resource` / `@WebServiceRef` / `@EJB` annotated fields and setter methods, for `name` attributes and default names.

    - ### Methods inherited from class org.springframework.beans.factory.annotation.InitDestroyAnnotationBeanPostProcessor

      `getOrder, postProcessAfterInitialization, postProcessBeforeDestruction, postProcessBeforeInitialization, setDestroyAnnotationType, setInitAnnotationType, setOrder`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.springframework.beans.factory.config.BeanPostProcessor

      `postProcessAfterInitialization, postProcessBeforeInitialization`

- - ### Constructor Detail

    - #### CommonAnnotationBeanPostProcessor

          public CommonAnnotationBeanPostProcessor()

      Create a new CommonAnnotationBeanPostProcessor, with the init and destroy annotation types set to `PostConstruct` and `PreDestroy`, respectively.

  - ### Method Detail

    - #### ignoreResourceType

          public void ignoreResourceType(String resourceType)

      Ignore the given resource type when resolving `@Resource` annotations.

      By default, the `javax.xml.ws.WebServiceContext` interface will be ignored, since it will be resolved by the JAX-WS runtime.

      Parameters:
        `resourceType` - the resource type to ignore

    - #### setFallbackToDefaultTypeMatch

          public void setFallbackToDefaultTypeMatch(boolean fallbackToDefaultTypeMatch)

      Set whether to allow a fallback to a type match if no explicit name has been specified. The default name (i.e. the field name or bean property name) will still be checked first; if a bean of that name exists, it will be taken. However, if no bean of that name exists, a by-type resolution of the dependency will be attempted if this flag is "true".

      Default is "true". Switch this flag to "false" in order to enforce a by-name lookup in all cases, throwing an exception in case of no name match.

      See Also:
        `AutowireCapableBeanFactory.resolveDependency(org.springframework.beans.factory.config.DependencyDescriptor, java.lang.String)`

    - #### setAlwaysUseJndiLookup

          public void setAlwaysUseJndiLookup(boolean alwaysUseJndiLookup)

      Set whether to always use JNDI lookups equivalent to standard Java EE 5 resource injection, even for `name` attributes and default names.

      Default is "false": Resource names are used for Spring bean lookups in the containing BeanFactory; only `mappedName` attributes point directly into JNDI. Switch this flag to "true" for enforcing Java EE style JNDI lookups in any case, even for `name` attributes and default names.

      See Also:
        `setJndiFactory(org.springframework.beans.factory.BeanFactory)`, `setResourceFactory(org.springframework.beans.factory.BeanFactory)`

    - #### setJndiFactory

          public void setJndiFactory(BeanFactory jndiFactory)

      Specify the factory for objects to be injected into `@Resource` / `@WebServiceRef` / `@EJB` annotated fields and setter methods, for `mappedName` attributes that point directly into JNDI. This factory will also be used if "alwaysUseJndiLookup" is set to "true" in order to enforce JNDI lookups even for `name` attributes and default names.

      The default is a `SimpleJndiBeanFactory` for JNDI lookup behavior equivalent to standard Java EE 5 resource injection.

      See Also:
        `setResourceFactory(org.springframework.beans.factory.BeanFactory)`, `setAlwaysUseJndiLookup(boolean)`

    - #### setResourceFactory

          public void setResourceFactory(BeanFactory resourceFactory)

      Specify the factory for objects to be injected into `@Resource` / `@WebServiceRef` / `@EJB` annotated fields and setter methods, for `name` attributes and default names.

      The default is the BeanFactory that this post-processor is defined in, if any, looking up resource names as Spring bean names. Specify the resource factory explicitly for programmatic usage of this post-processor.

      Specifying Spring's `SimpleJndiBeanFactory` leads to JNDI lookup behavior equivalent to standard Java EE 5 resource injection, even for `name` attributes and default names. This is the same behavior that the "alwaysUseJndiLookup" flag enables.

      See Also:
        `setAlwaysUseJndiLookup(boolean)`

    - #### setBeanFactory

          public void setBeanFactory(BeanFactory beanFactory)
                              throws BeansException

      Description copied from interface: `BeanFactoryAware`
      Callback that supplies the owning factory to a bean instance.

      Invoked after the population of normal bean properties but before an initialization callback such as `InitializingBean.afterPropertiesSet()` or a custom init-method.

      Specified by:
        `setBeanFactory` in interface `BeanFactoryAware`
      Parameters:
        `beanFactory` - owning BeanFactory (never `null`). The bean can immediately call methods on the factory.
      Throws:
        `BeansException` - in case of initialization errors
      See Also:
        `BeanInitializationException`

    - #### postProcessMergedBeanDefinition

          public void postProcessMergedBeanDefinition(RootBeanDefinition beanDefinition,
                                             Class<?> beanType,
                                             String beanName)

      Description copied from interface: `MergedBeanDefinitionPostProcessor`
      Post-process the given merged bean definition for the specified bean.
      Specified by:
        `postProcessMergedBeanDefinition` in interface `MergedBeanDefinitionPostProcessor`
      Overrides:
        `postProcessMergedBeanDefinition` in class `InitDestroyAnnotationBeanPostProcessor`
      Parameters:
        `beanDefinition` - the merged bean definition for the bean
        `beanType` - the actual type of the managed bean instance
        `beanName` - the name of the bean

    - #### postProcessBeforeInstantiation

          public Object postProcessBeforeInstantiation(Class<?> beanClass,
                                              String beanName)
                                                throws BeansException

      Description copied from interface: `InstantiationAwareBeanPostProcessor`
      Apply this BeanPostProcessor before the target bean gets instantiated. The returned bean object may be a proxy to use instead of the target bean, effectively suppressing default instantiation of the target bean.

      If a non-null object is returned by this method, the bean creation process will be short-circuited. The only further processing applied is the `BeanPostProcessor.postProcessAfterInitialization(java.lang.Object, java.lang.String)` callback from the configured `BeanPostProcessors`.

      This callback will only be applied to bean definitions with a bean class. In particular, it will not be applied to beans with a "factory-method".

      Post-processors may implement the extended `SmartInstantiationAwareBeanPostProcessor` interface in order to predict the type of the bean object that they are going to return here.

      Specified by:
        `postProcessBeforeInstantiation` in interface `InstantiationAwareBeanPostProcessor`
      Parameters:
        `beanClass` - the class of the bean to be instantiated
        `beanName` - the name of the bean
      Returns:
        the bean object to expose instead of a default instance of the target bean, or `null` to proceed with default instantiation
      Throws:
        `BeansException` - in case of errors
      See Also:
        `AbstractBeanDefinition.hasBeanClass()`, `AbstractBeanDefinition.getFactoryMethodName()`

    - #### postProcessAfterInstantiation

          public boolean postProcessAfterInstantiation(Object bean,
                                              String beanName)
                                                throws BeansException

      Description copied from interface: `InstantiationAwareBeanPostProcessor`
      Perform operations after the bean has been instantiated, via a constructor or factory method, but before Spring property population (from explicit properties or autowiring) occurs.

      This is the ideal callback for performing field injection on the given bean instance. See Spring's own `AutowiredAnnotationBeanPostProcessor` for a typical example.

      Specified by:
        `postProcessAfterInstantiation` in interface `InstantiationAwareBeanPostProcessor`
      Parameters:
        `bean` - the bean instance created, with properties not having been set yet
        `beanName` - the name of the bean
      Returns:
        `true` if properties should be set on the bean; `false` if property population should be skipped. Normal implementations should return `true`. Returning `false` will also prevent any subsequent InstantiationAwareBeanPostProcessor instances being invoked on this bean instance.
      Throws:
        `BeansException` - in case of errors

    - #### postProcessPropertyValues

          public PropertyValues postProcessPropertyValues(PropertyValues pvs,
                                                 PropertyDescriptor[] pds,
                                                 Object bean,
                                                 String beanName)
                                                   throws BeansException

      Description copied from interface: `InstantiationAwareBeanPostProcessor`
      Post-process the given property values before the factory applies them to the given bean. Allows for checking whether all dependencies have been satisfied, for example based on a "Required" annotation on bean property setters.

      Also allows for replacing the property values to apply, typically through creating a new MutablePropertyValues instance based on the original PropertyValues, adding or removing specific values.

      Specified by:
        `postProcessPropertyValues` in interface `InstantiationAwareBeanPostProcessor`
      Parameters:
        `pvs` - the property values that the factory is about to apply (never `null`)
        `pds` - the relevant property descriptors for the target bean (with ignored dependency types - which the factory handles specifically - already filtered out)
        `bean` - the bean instance created, but whose properties have not yet been set
        `beanName` - the name of the bean
      Returns:
        the actual property values to apply to to the given bean (can be the passed-in PropertyValues instance), or `null` to skip property population
      Throws:
        `BeansException` - in case of errors
      See Also:
        `MutablePropertyValues`

    - #### getResource

          protected Object getResource(CommonAnnotationBeanPostProcessor.LookupElement element,
                           String requestingBeanName)
                                throws BeansException

      Obtain the resource object for the given name and type.
      Parameters:
        `element` - the descriptor for the annotated field/method
        `requestingBeanName` - the name of the requesting bean
      Returns:
        the resource object (never `null`)
      Throws:
        `BeansException` - if we failed to obtain the target resource

    - #### autowireResource

          protected Object autowireResource(BeanFactory factory,
                                CommonAnnotationBeanPostProcessor.LookupElement element,
                                String requestingBeanName)
                                     throws BeansException

      Obtain a resource object for the given name and type through autowiring based on the given factory.
      Parameters:
        `factory` - the factory to autowire against
        `element` - the descriptor for the annotated field/method
        `requestingBeanName` - the name of the requesting bean
      Returns:
        the resource object (never `null`)
      Throws:
        `BeansException` - if we failed to obtain the target resource