5 Using Contexts and Dependency Injection in Resource Adapters

This chapter describes WebLogic Server support for JSR 299: Contexts and Dependency Injection for the Java EE Platform (CDI) in its implementation of Connector Architecture 1.6.

This chapter includes the following sections:

Overview

The CDI specification defines a set of services for using injection to specify dependencies in an application. CDI provides contextual life cycle management of beans, type-safe injection points, a loosely coupled event framework, loosely coupled interceptors and decorators, alternative implementations of beans, bean navigation through the Unified Expression Language (EL), and a service provider interface (SPI) that enables CDI extensions to support third-party frameworks or future Java EE components.

CDI support in the WebLogic Server implementation of Connector Architecture 1.6 is based on the following related specifications:

For additional general information about CDI, see:

Resource Adapter Bean Discovery

If a resource adapter RAR is a bean archive, WebLogic Server treats all JAR files inside the RAR as bean archives that can be discovered, regardless of whether those JARs contain META-INF/beans.xml files. A resource adapter RAR is a bean archive if it has a bean archive descriptor file, beans.xml, in its META-INF directory.

WebLogic Server ignores beans.xml files that exist within nested JARs inside the RAR.

When an application is deployed as a resource adapter RAR bean archive, the WebLogic Server Connector container searches the following for beans and bean references:

  • The resource adapter RAR

  • All classes packaged directly inside the resource adapter RAR

  • Every bean archive referenced by the adapter RAR

Obtaining Contextual References to Resource Adapter Beans

A resource adapter is different from a Web application or an EJB in that a resource adapter does not have its own JNDI namespace. That is, a resource adapter module does not have a java:comp, java:module, or java:app namespace. Therefore, it is not possible to bind a named managed bean to a resource adapter's JNDI namespace, and it is also not possible to perform a lookup (as specified in the Java EE 6 Managed Beans Specification) from a resource adapter's JNDI namespace or to use the Java EE 6 @Resource annotation to inject a predefined bean.

However, WebLogic Server provides the ExtendedBootstrapContext.getBeanManager() method. A resource adapter can invoke the getBeanManager method to expose the BeanManager instance of its adapter module.

Invoking Resource Adapter Beans From Other Application Types

The WebLogic Server Connector container does not support injecting CDI bean classes contained in a resource adapter RAR bean archive into other Web applications or EJBs. WebLogic Server support is limited to permitting CDI beans within an adapter RAR bean archive to be used or invoked by other caller Web applications or EJBs, provided that those CDI beans are not client proxies.

Using Resource Adapters Deployed as CDI Bean Archives

If the resource adapter is deployed as a CDI bean archive, the WebLogic Server Connector container provides the following support for CDI beans within the resource adapter itself:

  • The ability to discover managed beans, decorators, interceptors, events, and so on, that are inside the deployed resource adapter

  • Support for third-party portable extensions, as defined in Chapter 11, "Portable Extensions," in JSR 299: Contexts and Dependency Injection for the Java EE Platform

  • Support for the CDI features that are exposed by the BeanManager

  • Support for bean instantiation, injection, decorators, interceptors, events, and so on, for managed beans inside the resource adapter

Note the following:

  • A resource adapter's BeanManager instance is exposed by the getBeanManager method on the ExtendedBootstrapContext object.

  • WebLogic Server supports the use of an adapter's BeanManager only in the adapter's own thread. An adapter's BeanManager cannot be used in another application's thread.

  • The WebLogic Server Connector container supports the injection of built-in BeanManager bean types that are inside the resource adapter module; for example, injecting into the ResourceAdapter bean.

  • The use of the Resource injection annotation on a resource adapter's managed beans is not supported.

BeanManager Support

A resource adapter's BeanManager can be used in either of the following situations:

  • During the adapter deployment process, such as when the ResourceAdapter.start method is invoked

  • Inside the Work.run method, which is scheduled by the resource adapter's WorkManager instance

The WebLogic Server Connector container supports the injection of built-in BeanManager bean types in the resource adapter module. However, the use of a resource adapter's BeanManager instance by a caller thread is not supported.

Injection Points

The WebLogic Server Connector container supports injection points for the following beans within a resource adapter deployed as a CDI bean archive:

  • The following built-in beans, which JSR 299: Contexts and Dependency Injection for the Java EE Platform requires to be provided in a Java EE container:

    • UserTransaction — Provided by WebLogic JTA.

    • Principal — The caller principal set by the WebLogic Server Connector container. Its value is the current principal on the thread at the time this instance is used, not when it was injected.

    • ValidationFactory — The ValidationFactory instance of the resource adapter module itself and that is also accessible from the ExtendedBootstrapContext.getValidatorFactory method.

    • Validator — The Validator instance of the resource adapter module itself and that is also accessible from the ExtendedBootstrapContext.getValidator method.

  • The BeanManager instance, as defined in Section 11.3 of JSR 299: Contexts and Dependency Injection for the Java EE Platform, of the resource adapter module itself that is accessible from the ExtendedBootstrapContext.getBeanManager method.

  • Any managed bean that conforms to JSR 299: Contexts and Dependency Injection for the Java EE Platform and the Java EE 6 Managed Beans Specification, which is a part of JSR 316: Java Platform, Enterprise Edition 6 (Java EE 6) Specification.

  • Any special Connector Architecture 1.6 built-in beans of the following types that are part of the current resource adapter module:

    • javax.resource.spi.ResourceAdapter allowing injection of a reference to the current resource adapter bean, which always refers to either: the ResourceAdapter bean instance of the current adapter module; or null if no ResourceAdapter bean is defined for the current resource adapter module.

    • javax.resource.spi.BootstrapContext or weblogic.connector.extensions.ExtendedBootstrapContext allowing injection of a reference to either: the current resource adapter's BootstrapContext bean instance; or null if no ResourceAdapter bean is defined for the current resource adapter module. This bean type is also available from a parameter in an invocation of the ResourceAdapter.start(BootstrapContext ctx) method.

    • javax.resource.spi.work.WorkManager allowing injection of a reference to either: the current resource adapter's WorkManager instance, which is available also from the BootstrapContext.getWorkManager() method; or null if no ResourceAdapter bean is defined for the current resource adapter module.

    • javax.resource.spi.XATerminator allowing injection of a reference to either: the current resource adapter's XATerminator instance, which is also available from the BootstrapContext.getXATerminator method; or null if no ResourceAdapter bean is defined for the current resource adapter module.

    • javax.transaction.TransactionSynchronizationRegistry allowing injection of a reference to the JTA TransactionSynchronizationRegistry instance, which is also available also from the BootstrapContext.getTransactionSynchronizationRegistry method.

Using CDI with Resource Adapter Component Beans

WebLogic Server supports four types of beans called resource adapter component beans, which define special components managed by the WebLogic Server Connector container. Resource adapter component beans are "POJOs" (Plain Old Java Objects), but are created and managed by the resource adapter container and have a special life cycle.

The adapter component bean types are:

  • ResourceAdapter bean — Resource adapter class that implements javax.resource.spi.ResourceAdapter interface, which contains operations for life cycle management and message endpoint setup.

  • ManagedConnectionFactory bean — JavaBean class that implements the javax.resource.spi.ManagedConnectionFactory interface and is a factory of both ManagedConnection and EIS-specific connection factory instances. This interface supports connection pooling by providing methods for matching and creation of a ManagedConnection instance.

  • ActivationSpec bean — JavaBean class that implements the javax.resource.spi.ActivationSpec interface and that holds the activation configuration information for a message endpoint.

  • Administered objects, or admin objects — Optional set of JavaBean classes that represent objects specific to a messaging style or message provider.

The following metadata annotations may be used within resource adapter component beans:

  • @Connector

  • @Activation

  • @ConnectionDefinition

  • @ConnectionDefinitions

  • @AdministeredObject

Note:

The preceding annotations are new in Connector Architecture 1.6 and are recommended for use instead of the corresponding ra.xml elements.

The following sections include important information about the programming requirements for resource adapter component beans:

For information about setting dynamically configurable properties on resource adapter component beans, see Dynamic Reconfigurable Configuration Properties.

Resource Adapter Component Beans Must Not Be Managed Beans

Resource adapter component beans must not be managed beans. However, the WebLogic Server Connector container does support CDI injection of managed beans, as defined in JSR 299: Contexts and Dependency Injection for the Java EE Platform, into a resource adapter component bean. WebLogic Server also supports the PostConstruct and PreDestroy annotations in adapter component beans as well.

Notes:

Note the following:

To ensure that a resource adapter component bean is not treated as a managed bean, WebLogic Server will fail to deploy the adapter if any of the following class-level annotations are used within an adapter component bean:

Using Dependency Injection

In a resource adapter that is deployed as a CDI bean archive, the WebLogic Server Connector container supports CDI for adapter component beans once they are created and initialized.

To support Dependency Injection for resource adapter component beans, consistent with Section EE.5.20, "Support for Dependency Injection (JSR-330)" in the Java Platform, Enterprise Edition (Java EE) Specification, Version 6, the WebLogic Connector container does the following when initializing these beans:

  1. Initializes the resource adapter component bean configuration properties using values in deployment descriptors.

  2. Uses the PostConstruct annotation after dependency injection is done to perform any initialization.

  3. Performs bean validation, consistent with JSR 303: Bean Validation, and for an ActivationSpec bean, invokes the validate() method.

  4. For a ResourceAdapter bean, invokes the start() method.

  5. Makes all resource adapter component beans available either by binding them to JNDI or exposing them to endpoint applications.

Notes on Injection Usage

Resource adapter component beans cannot be injected into other beans outside of the resource adapter module because they are not standard managed beans. That is, they are not visible outside the resource adapter module in a way that is consistent with JSR 299: Contexts and Dependency Injection for the Java EE Platform. You can design adapter component beans to support injection, but it is important to ensure that they are not treated like managed beans because the notion of request scope or session scope is meaningless in resource adapter component beans.

Injection is supported as follows:

The Resource injection annotation is not supported in a resource adapter module.

Example

The following example shows that during resource adapter deployment, WebLogic Server first instantiates a MyResourceAdapter instance consistent with CDI. MyResourceAdapter is the ResourceAdapter component bean of the resource adapter module shown in this example because it is annotated with the Connector annotation. During deployment, WebLogic Server also:

  • Instantiates MyBean and injects it into the MyResourceAdapter instance using the javax.inject.Inject annotation.

  • Injects the Validator instance of this adapter module into the MyResourceAdapter instance.

  • Injects the WorkManager and UserTransaction instances of this adapter module into MyBean.

@Connector
public class MyResourceAdapter implements ResourceAdapter{
     private @Inject MyBean bean;
private @Validator v;
 
public void start(BootstrapContext ctx){
     v.validate(this, AnotherGroup.class);
     bean.do();
     .
     .
     .
}
     .
     .
     .
}
 
public class MyBean{
     private String name;
private @WorkManager wm;
private @UserTransaction ut;
 
public String  getName(){
          return name;
     }
 
     public void setName(String name) {
          this.name = name;
     }
 
     public void do(){
          Work w = …
          wm.scheduleWork(w);
     }
}