Sun Microsystems Inc.

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).

14.4.1 Bean Provider’s responsibilities

This subsection describes the Bean Provider’s view of locating resource factories and defines his responsibilities.

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 subsection 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.

Sun Microsystem Inc

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();

...

}

}

14.4.1.2Declaration 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.

Sun Microsystems Inc.

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>

...

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 JavaMailTM 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.