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 ResponsibilitiesThis 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 ReferencesThe bean provider must use resource manager connection factory references to obtain connections to resources as follows .
The bean provider has two choices with respect to dealing with associating a principal with the resource manager access:
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 DescriptorAlthough 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 TypesThe 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 ResponsibilityThe 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:
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 ResponsibilityThe EJB container provider is responsible for the following:
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:
EJB.14.4.4 System Administrator's ResponsibilityThe system administrator is typically responsible for the following:
In some scenarios, these tasks can be performed by the deployer. |