EJB.14.4 Resource Manager Connection Factory References

A resource manager connection factory is an object that is used to create connections to a resource manager. For example, an object that implements the javax.sql.DataSource interface is a resource manager connection factory for java.sql.Connection objects which implement connections to a database management system.

This section describes the enterprise bean programming and deployment descriptor interfaces that allow the enterprise bean code to refer to resource factories using logical names called resource manager connection factory references . The resource manager connection factory references are special entries in the enterprise bean's environment. The deployer binds the resource manager connection factory references to the actual resource factories that are configured in the container. Because these resource factories allow the container to affect resource management, the connections acquired through the resource manager connection factory references are called managed resources (e.g., these resource factories allow the container to implement connection pooling and automatic enlistment of the connection with a transaction).

EJB.14.4.1 Bean Provider's Responsibilities

This subsection describes the bean provider's view of locating resource factories and defines his responsibilities.

EJB.14.4.1.1 Programming Interfaces for Resource Manager Connection Factory References

The bean provider must use resource manager connection factory references to obtain connections to resources as follows .

• Assign an entry in the enterprise bean's environment to the resource manager connection factory reference. (See Section EJB.14.4.1.2 for information on how resource manager connection factory references are declared in the deployment descriptor.)

• The EJB specification recommends, but does not require, that all resource manager connection factory references be organized in the subcontexts of the bean's environment, using a different subcontext for each resource manager type. For example, all JDBC DataSource references might be declared in the java:comp/env/jdbc subcontext, and all JMS connection factories in the java:comp/env/jms subcontext. Also, all JavaMail connection factories might be declared in the java:comp/env/mail subcontext and all URL connection factories in the java:comp/env/url subcontext.

• Look up the resource manager connection factory object in the enterprise bean's environment using the JNDI interface.

• Invoke the appropriate method on the resource manager connection factory method to obtain a connection to the resource. The factory method is specific to the resource type. It is possible to obtain multiple connections by calling the factory object multiple times.

The bean provider has two choices with respect to dealing with associating a principal with the resource manager access:

• Allow the deployer to set up principal mapping or resource manager sign-on information. In this case, the enterprise bean code invokes a resource manager connection factory method that has no security- related parameters.

• Sign on to the resource manager from the bean code. In this case, the enterprise bean invokes the appropriate resource manager connection factory method that takes the sign-on information as method parameters.

The bean provider uses the res-auth deployment descriptor element to indicate which of the two resource manager authentication approaches is used.

We expect that the first form (i.e., letting the deployer set up the resource manager sign-on information) will be the approach used by most enterprise beans.

The following code sample illustrates obtaining a JDBC connection.

 public class EmployeeServiceBean implements SessionBean {    EJBContext ejbContext;     public void changePhoneNumber(...) {       ...        // obtain the initial JNDI context        Context initCtx = new InitialContext();        // perform JNDI lookup to obtain resource manager        // connection factory        javax.sql.DataSource ds = (javax.sql.DataSource)           initCtx.lookup("java:comp/env/jdbc/EmployeeAppDB");        // Invoke factory to obtain a connection. The security        // principal is not given, and therefore        // it will be configured by the Deployer.        java.sql.Connection con = ds.getConnection();        ...     }  } 

EJB.14.4.1.2 Declaration of Resource Manager Connection Factory References in Deployment Descriptor

Although a resource manager connection factory reference is an entry in the enterprise bean's environment, the bean provider must not use an env-entry element to declare it.

Instead, the bean provider must declare all the resource manager connection factory references in the deployment descriptor using the resource-ref elements. This allows the EJB JAR consumer (i.e., application assembler or deployer) to discover all the resource manager connection factory references used by an enterprise bean.

Each resource-ref element describes a single resource manager connection factory reference. The resource-ref element consists of the description element and the mandatory res-ref- name , res-type , and res-auth elements. The res-ref- name element contains the name of the environment entry used in the enterprise bean's code. The res-type element contains the Java type of the resource manager connection factory that the enterprise bean code expects. The res-auth element indicates whether the enterprise bean code performs resource manager sign-on programmatically, or whether the container signs on to the resource manager using the principal mapping information supplied by the deployer. The bean provider indicates the sign-on responsibility by setting the value of the res-auth element to Application or container.

A resource manager connection factory reference is scoped to the session or entity bean whose declaration contains the resource-ref element. This means that the resource manager connection factory reference is not accessible from other enterprise beans at runtime, and that other enterprise beans may define resource-ref elements with the same res-ref-name without causing a name conflict.

The type declaration allows the deployer to identify the type of the resource manager connection factory.

Note that the indicated type is the Java type of the resource manager connection factory, not the Java type of the resource.

The following example is the declaration of resource manager connection factory references used by the EmployeeService enterprise bean illustrated in the previous subsection.

 ...  <enterprise-beans>     <session>            ...        <ejb-name>EmployeeService</ejb-name>        <ejb-class>           com.wombat.empl.EmployeeServiceBean        </ejb-class>        ...        <resource-ref>           <description>              A data source for the database in which              the EmployeeService enterprise bean will              record a log of all transactions.           </description>           <res-ref-name>jdbc/EmployeeAppDB</res-ref-name>           <res-type>javax.sql.DataSource</res-type>           <res-auth>Container</res-auth>        </resource-ref>        ...     </session>  </enterprise-beans>  ... 

EJB.14.4.1.3 Standard Resource Manager Connection Factory Types

The bean provider must use the javax.sql.DataSource resource manager connection factory type for obtaining JDBC API connections, and the javax.jms.QueueConnectionFactory or the javax.jms.TopicConnectionFactory for obtaining JMS connections.

The bean provider must use the javax.mail.Session resource manager connection factory type for obtaining JavaMail API connections, and the java.net.URL resource manager connection factory type for obtaining URL connections.

It is recommended that the bean provider names JDBC API data sources in the java:comp/env/jdbc subcontext, and JMS connection factories in the java:comp/env/jms subcontext. It is also recommended that the bean provider names all JavaMail API connection factories in the java:comp/env/mail subcontext, and all URL connection factories in the java:comp/env/url subcontext.

Note

A future EJB specification will add the "connector" mechanism that will allow an enterprise bean to use the API described in this section to obtain resource objects that provide access to additional back-end systems.

EJB.14.4.2 Deployer's Responsibility

The deployer uses deployment tools to bind the resource manager connection factory references to the actual resource factories configured in the target operational environment.

The deployer must perform the following tasks for each resource manager connection factory reference declared in the deployment descriptor:

• Bind the resource manager connection factory reference to a resource manager connection factory that exists in the operational environment. The deployer may use, for example, the JNDI LinkRef mechanism to create a symbolic link to the actual JNDI API name of the resource manager connection factory. The resource manager connection factory type must be compatible with the type declared in the res-type element.

• Provide any additional configuration information that the resource manager needs for opening and managing the resource. The configuration mechanism is resource-manager specific, and is beyond the scope of this specification.

• If the value of the res-auth element is container , the deployer is responsible for configuring the sign-on information for the resource manager. This is performed in a manner specific to the EJB container and resource manager; it is beyond the scope of this specification.

For example, if principals must be mapped from the security domain and principal realm used at the enterprise beans application level to the security domain and principal realm of the resource manager, the deployer or system administrator must define the mapping. The mapping is performed in a manner specific to the EJB container and resource manager; it is beyond the scope of the current EJB specification.

EJB.14.4.3 Container Provider Responsibility

The EJB container provider is responsible for the following:

• Provide the deployment tools that allow the deployer to perform the tasks described in the previous subsection.

• Provide the implementation of the resource manager connection factory classes for the resource managers that are configured with the EJB container.

• If the bean provider set the res-auth of a resource manager connection factory reference to Application , the container must allow the bean to perform explicit programmatic signon using the resource manager's API.

• The container must provide tools that allow the deployer to set up resource manager sign-on information for the resource manager references whose res-auth element is set to container . The minimum requirement is that the deployer must be able to specify the user/password information for each resource manager connection factory reference declared by the enterprise bean, and the container must be able to use the user/password combination for user authentication when obtaining a connection to the resource by invoking the resource manager connection factory.

Although not required by the EJB specification, we expect that containers will support some form of a single sign-on mechanism that spans the application server and the resource managers. The container will allow the deployer to set up the resource managers such that the EJB caller principal can be propagated (directly or through principal mapping) to a resource manager, if required by the application.

While not required by the EJB specification, most EJB container providers also provide the following features:

• A tool to allow the system administrator to add, remove, and configure a resource manager for the EJB Server.

• A mechanism to pool connections to the resources for the enterprise beans and otherwise manage the use of resources by the container. The pooling must be transparent to the enterprise beans.

EJB.14.4.4 System Administrator's Responsibility

The system administrator is typically responsible for the following:

• Add, remove, and configure resource managers in the EJB server environment.

In some scenarios, these tasks can be performed by the deployer.