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

org.springframework.jca.context

## Class SpringContextResourceAdapter

- java.lang.Object
- - org.springframework.jca.context.SpringContextResourceAdapter

- All Implemented Interfaces:
    ResourceAdapter

      public class SpringContextResourceAdapter
      extends Object
      implements ResourceAdapter

  JCA 1.5 `ResourceAdapter` implementation that loads a Spring `ApplicationContext`, starting and stopping Spring-managed beans as part of the ResourceAdapter's lifecycle.

  Ideal for application contexts that do not need any HTTP entry points but rather just consist of message endpoints and scheduled jobs etc. Beans in such a context may use application server resources such as the JTA transaction manager and JNDI-bound JDBC DataSources and JMS ConnectionFactory instances, and may also register with the platform's JMX server - all through Spring's standard transaction management and JNDI and JMX support facilities.

  If the need for scheduling asynchronous work arises, consider using Spring's `WorkManagerTaskExecutor` as a standard bean definition, to be injected into application beans through dependency injection. This WorkManagerTaskExecutor will automatically use the JCA WorkManager from the BootstrapContext that has been provided to this ResourceAdapter.

  The JCA `BootstrapContext` may also be accessed directly, through application components that implement the `BootstrapContextAware` interface. When deployed using this ResourceAdapter, the BootstrapContext is guaranteed to be passed on to such components.

  This ResourceAdapter is to be defined in a "META-INF/ra.xml" file within a J2EE ".rar" deployment unit like as follows:

       <?xml version="1.0" encoding="UTF-8"?>
       <connector xmlns="http://java.sun.com/xml/ns/j2ee"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                       xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/connector_1_5.xsd"
                       version="1.5">
               <vendor-name>Spring Framework</vendor-name>
               <eis-type>Spring Connector</eis-type>
               <resourceadapter-version>1.0</resourceadapter-version>
               <resourceadapter>
                       <resourceadapter-class>org.springframework.jca.context.SpringContextResourceAdapter</resourceadapter-class>
                       <config-property>
                               <config-property-name>ContextConfigLocation</config-property-name>
                               <config-property-type>java.lang.String</config-property-type>
                               <config-property-value>META-INF/applicationContext.xml</config-property-value>
                       </config-property>
               </resourceadapter>
       </connector>

  Note that "META-INF/applicationContext.xml" is the default context config location, so it doesn't have to specified unless you intend to specify different/additional config files. So in the default case, you may remove the entire `config-property` section above.

  For simple deployment needs, all you need to do is the following: Package all application classes into a RAR file (which is just a standard JAR file with a different file extension), add all required library jars into the root of the RAR archive, add a "META-INF/ra.xml" deployment descriptor as shown above as well as the corresponding Spring XML bean definition file(s) (typically "META-INF/applicationContext.xml"), and drop the resulting RAR file into your application server's deployment directory!

  Since:
    2.5
  Author:
    Juergen Hoeller
  See Also:
    `setContextConfigLocation(java.lang.String)`, `loadBeanDefinitions(org.springframework.beans.factory.support.BeanDefinitionRegistry, java.lang.String[])`, `ResourceAdapterApplicationContext`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONFIG_LOCATION_DELIMITERS` Any number of these characters are considered delimiters between multiple context config paths in a single String value.
    `static String` | `DEFAULT_CONTEXT_CONFIG_LOCATION`
    `protected Log` | `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SpringContextResourceAdapter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected ConfigurableApplicationContext` | `createApplicationContext(BootstrapContext bootstrapContext)` Build a Spring ApplicationContext for the given JCA BootstrapContext.
    `protected ConfigurableEnvironment` | `createEnvironment()` Return a new `StandardEnvironment`.
    `void` | `endpointActivation(MessageEndpointFactory messageEndpointFactory, ActivationSpec activationSpec)` This implementation always throws a NotSupportedException.
    `void` | `endpointDeactivation(MessageEndpointFactory messageEndpointFactory, ActivationSpec activationSpec)` This implementation does nothing.
    `boolean` | `equals(Object obj)`
    `protected String` | `getContextConfigLocation()` Return the specified context configuration files.
    `XAResource[]` | `getXAResources(ActivationSpec[] activationSpecs)` This implementation always returns `null`.
    `int` | `hashCode()`
    `protected void` | `loadBeanDefinitions(BeanDefinitionRegistry registry, String[] configLocations)` Load the bean definitions into the given registry, based on the specified configuration files.
    `void` | `setContextConfigLocation(String contextConfigLocation)` Set the location of the context configuration files, within the resource adapter's deployment unit.
    `void` | `start(BootstrapContext bootstrapContext)` This implementation loads a Spring ApplicationContext through the `createApplicationContext(javax.resource.spi.BootstrapContext)` template method.
    `void` | `stop()` This implementation closes the Spring ApplicationContext.

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

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

- - ### Field Detail

    - #### CONFIG_LOCATION_DELIMITERS

          public static final String CONFIG_LOCATION_DELIMITERS

      Any number of these characters are considered delimiters between multiple context config paths in a single String value.
      See Also:
        `setContextConfigLocation(java.lang.String)`, Constant Field Values

    - #### DEFAULT_CONTEXT_CONFIG_LOCATION

          public static final String DEFAULT_CONTEXT_CONFIG_LOCATION

      See Also:
        Constant Field Values

    - #### logger

          protected final Log logger

  - ### Constructor Detail

    - #### SpringContextResourceAdapter

          public SpringContextResourceAdapter()

  - ### Method Detail

    - #### setContextConfigLocation

          public void setContextConfigLocation(String contextConfigLocation)

      Set the location of the context configuration files, within the resource adapter's deployment unit. This can be a delimited String that consists of multiple resource location, separated by commas, semicolons, whitespace, or line breaks.

      This can be specified as "ContextConfigLocation" config property in the `ra.xml` deployment descriptor.

      The default is "classpath:META-INF/applicationContext.xml".

    - #### getContextConfigLocation

          protected String getContextConfigLocation()

      Return the specified context configuration files.

    - #### createEnvironment

          protected ConfigurableEnvironment createEnvironment()

      Return a new `StandardEnvironment`.

      Subclasses may override this method in order to supply a custom `ConfigurableEnvironment` implementation.

    - #### start

          public void start(BootstrapContext bootstrapContext)
                     throws ResourceAdapterInternalException

      This implementation loads a Spring ApplicationContext through the `createApplicationContext(javax.resource.spi.BootstrapContext)` template method.
      Specified by:
        `start` in interface `ResourceAdapter`
      Throws:
        `ResourceAdapterInternalException`

    - #### createApplicationContext

          protected ConfigurableApplicationContext createApplicationContext(BootstrapContext bootstrapContext)

      Build a Spring ApplicationContext for the given JCA BootstrapContext.

      The default implementation builds a `ResourceAdapterApplicationContext` and delegates to `loadBeanDefinitions(org.springframework.beans.factory.support.BeanDefinitionRegistry, java.lang.String[])` for actually parsing the specified configuration files.

      Parameters:
        `bootstrapContext` - this ResourceAdapter's BootstrapContext
      Returns:
        the Spring ApplicationContext instance

    - #### loadBeanDefinitions

          protected void loadBeanDefinitions(BeanDefinitionRegistry registry,
                                 String[] configLocations)

      Load the bean definitions into the given registry, based on the specified configuration files.
      Parameters:
        `registry` - the registry to load into
        `configLocations` - the parsed config locations
      See Also:
        `setContextConfigLocation(java.lang.String)`

    - #### stop

          public void stop()

      This implementation closes the Spring ApplicationContext.
      Specified by:
        `stop` in interface `ResourceAdapter`

    - #### endpointActivation

          public void endpointActivation(MessageEndpointFactory messageEndpointFactory,
                                ActivationSpec activationSpec)
                                  throws ResourceException

      This implementation always throws a NotSupportedException.
      Specified by:
        `endpointActivation` in interface `ResourceAdapter`
      Throws:
        `ResourceException`

    - #### endpointDeactivation

          public void endpointDeactivation(MessageEndpointFactory messageEndpointFactory,
                                  ActivationSpec activationSpec)

      This implementation does nothing.
      Specified by:
        `endpointDeactivation` in interface `ResourceAdapter`

    - #### getXAResources

          public XAResource[] getXAResources(ActivationSpec[] activationSpecs)
                                      throws ResourceException

      This implementation always returns `null`.
      Specified by:
        `getXAResources` in interface `ResourceAdapter`
      Throws:
        `ResourceException`

    - #### equals

          public boolean equals(Object obj)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`