4 Using Contexts and Dependency Injection in Resource Adapters
WebLogic Server provides full support for JSR 299: Contexts and Dependency Injection for the Java EE Platform (CDI) in its implementation of Connector Architecture 1.7.
Overview
CDI support in the WebLogic Server implementation of Connector Architecture 1.7 is based on the following related specifications:
-
JSR 299: Contexts and Dependency Injection for the Java EE Platform (
http://www.jcp.org/en/jsr/summary?id=299
) -
JSR 330: Dependency Injection for Java (
http://jcp.org/en/jsr/summary?id=330
)
For additional general information about CDI, see:
-
Using Contexts and Dependency Injection for the Java EE Platform in Developing Applications for Oracle WebLogic Server
-
Introduction to Contexts and Dependency Injection for Java EE in Java Platform, Enterprise Edition: The Java EE Tutorial.
Resource Adapter Bean Discovery
beans.xml
, in its META-INF
directory. If a resource adapter RAR is a bean archive, then all JARs must conform to the CDI 1.1 standard. See Using CDI With JCA Technology in Developing Applications for Oracle WebLogic Server.
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
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
Using Resource Adapters Deployed as CDI Bean Archives
-
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 Portable Extensions of Chapter 11 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 thegetBeanManager
method on theExtendedBootstrapContext
object. -
WebLogic Server supports the use of an adapter's
BeanManager
only in the adapter's own thread. An adapter'sBeanManager
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 theResourceAdapter
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'sWorkManager
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
— TheValidationFactory
instance of the resource adapter module itself and that is also accessible from theExtendedBootstrapContext.getValidatorFactory
method. -
Validator
— TheValidator
instance of the resource adapter module itself and that is also accessible from theExtendedBootstrapContext.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 theExtendedBootstrapContext.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.7 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: theResourceAdapter
bean instance of the current adapter module; ornull
if noResourceAdapter
bean is defined for the current resource adapter module. -
javax.resource.spi.BootstrapContext
orweblogic.connector.extensions.ExtendedBootstrapContext
allowing injection of a reference to either: the current resource adapter'sBootstrapContext
bean instance; ornull
if noResourceAdapter
bean is defined for the current resource adapter module. This bean type is also available from a parameter in an invocation of theResourceAdapter.start(BootstrapContext ctx)
method. -
javax.resource.spi.work.WorkManager
allowing injection of a reference to either: the current resource adapter'sWorkManager
instance, which is available also from theBootstrapContext.getWorkManager()
method; ornull
if noResourceAdapter
bean is defined for the current resource adapter module. -
javax.resource.spi.XATerminator
allowing injection of a reference to either: the current resource adapter'sXATerminator
instance, which is also available from theBootstrapContext.getXATerminator
method; ornull
if noResourceAdapter
bean is defined for the current resource adapter module. -
javax.transaction.TransactionSynchronizationRegistry
allowing injection of a reference to the JTATransactionSynchronizationRegistry
instance, which is also available also from theBootstrapContext.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 implementsjavax.resource.spi.ResourceAdapter
interface, which contains operations for life cycle management and message endpoint setup. -
ManagedConnectionFactory
bean — JavaBean class that implements thejavax.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 thejavax.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.7 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.
Note:
Note the following:
-
The WebLogic Server Connector container does not support managed beans that conform to the Java EE 6 Managed Beans Specification, which is a part of JSR 316: Java Platform, Enterprise Edition 6 (Java EE 6) Specification.
-
For information about designing a managed bean that meets the conditions required by JSR 299, see About Managed Beans in The Java EE 6 Tutorial.
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:
-
The
javax.annotation.ManagedBean
annotation -
Any scope annotation
-
Any qualifier annotation
-
Any stereotype annotation
-
javax.inject.Named
annotation -
javax.enterprise.inject.Alternative
annotation -
javax.enterprise.inject.Specializes
annotation -
javax.enterprise.inject.Typed
annotation -
javax.decorator.Decorator
annotation -
javax.decorator.Delegate
annotation
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:
- Initializes the resource adapter component bean configuration properties using values in deployment descriptors.
- Uses the
PostConstruct
annotation after dependency injection is done to perform any initialization. - Performs bean validation, consistent with JSR 303: Bean Validation, and for an
ActivationSpec
bean, invokes thevalidate()
method. - For a
ResourceAdapter
bean, invokes thestart()
method. - 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:
-
Field and method injection, but not constructor injection, is supported using the
javax.inject.Inject
annotation. -
Injected Fields, as defined in Section 3.8 of JSR 299: Contexts and Dependency Injection for the Java EE Platform, is supported.
-
All injection points listed in Injection Points, are supported, such as
weblogic.transaction.UserTransaction
orjavax.resource.spi.BootstrapContext
. -
The
PostConstruct
andPreDestroy
injection annotations are supported as follows:-
For
ResourceAdapter
bean types, the @PostConstruct method is called after the configuration properties are initialized but before thestart()
method is called. In addition, the @PreDestroy method is after thestop()
method. -
For other bean types, the @PostConstruct method is called after the configuration properties are initialized but before the bean is bound to JNDI. In addition, the @PreDestroy method is called when the resource adapter is undeployed or when the server is shut down.
-
For all beans, WebLogic Server performs bean validation consistent with its support for JSR 303: Bean Validation and also call the
validate()
method, if applicable, after calling the @PostConstruct method.
-
-
Events, as defined in Chapter 10, Events, in JSR 299: Contexts and Dependency Injection for the Java EE Platform, are supported.
-
In releases prior to WebLogic Server 12.2.1, the annotation "@Inject Validator v" injects only the default validator, even if you specify a customized validator as per the specification in CDI 1.0. However, since 12.2.1 release of WebLogic Server, the annotation "@Inject Validator v" injects even the customized validator as per the specification in CDI 1.1.
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 theMyResourceAdapter
instance using thejavax.inject.Inject
annotation. -
Injects the
Validator
instance of this adapter module into theMyResourceAdapter
instance. -
Injects the
WorkManager
andUserTransaction
instances of this adapter module intoMyBean
.
@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); } }