J2EE.5.4 Resource Factory References

A resource is an object that encapsulates access to a resource manager. A resource factory is an object that is used to create resources. For example, an object that implements the java.sql.Connection interface is a resource that provides access to a database management system, and an object that implements the javax.sql.Data- Source interface is a resource factory.

This section describes the application component programming and deployment descriptor interfaces that allow the application component code to refer to resource factories using logical names called resource factory references. The resource factory references are special entries in the application component's environment. The deployer binds the resource factory references to the actual resource factories that exist in the target operational environment.

Resource factory objects accessed through the naming environment are valid only within the component instance that performed the lookup. See the individual component specifications for additional restrictions that may apply.

J2EE.5.4.1 Application Component Provider's Responsibilities

This subsection describes the application component provider's view of locating resource factories and defines his or her responsibilities. It does so in two sections, the first describing the API for accessing resource factory references, and the second describing the syntax for declaring the factory references.

J2EE.5.4.1.1 Programming Interfaces for Resource Factory References

The application component provider must use resource factory references to obtain resources as follows .

• Assign an entry in the application component's naming environment to the resource factory reference. (See Section J2EE.5.4.1.2 for information on how resource factory references are declared in the deployment descriptor.)

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

• Look up the resource factory object in the application component's environment using the JNDI interface.

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

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

• Allow the deployer to set up principal mapping or resource signon information. In this case, the application component code invokes a resource factory method that has no security- related parameters.

• Sign on to the resource from the application component code. In this case, the application component invokes the appropriate resource factory method that takes the signon information as method parameters.

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

We expect that the first form (i.e., letting the deployer set up the resource signon information) will be the approach used by most application components .

The following code sample illustrates obtaining a resource.

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

J2EE.5.4.1.2 Declaration of Resource Factory References

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

Instead, the application component provider must declare all the resource factory references in the deployment descriptor using the resource-ref elements. This allows the consumer of the application component's jar file (i.e., the application assembler or deployer) to discover all the resource factory references used by an application component.

Each resource-ref element describes a single resource 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 application component's code. The res-type element contains the Java type of the resource factory that the application component code expects. The res-auth element indicates whether the application component code performs resource signon programmatically, or whether the container signs on to the resource based on the principal mapping information supplied by the deployer. The application component provider indicates the signon responsibility by setting the value of the res-auth element to Bean or Container .

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

Note that the indicated type is the Java programming language type of the resource factory, not the type of the resource.

The following example is the declaration of resource references used by the application component illustrated in the previous subsection.

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

J2EE.5.4.1.3 Standard Resource Factory Types

The application component provider must use the javax.sql.DataSource resource factory type for obtaining JDBC API connections.

The application component provider must use the javax.jms.QueueConnectionFactory or the javax.jms.TopicConnectionFactory for obtaining JMS connections.

The application component provider must use the javax.mail.Session resource factory type for obtaining JavaMail connections.

The application component provider must use the java.net.URL resource factory type for obtaining URL connections.

It is recommended that the application component provider name JDBC API data sources in the java:comp/env/jdbc subcontext, all JMS connection factories in the java:comp/env/jms subcontext, 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 version of this specification will add the "connector" mechanism that will allow an application component to use the API described in this section to obtain resource objects that provide access to additional back-end systems.

J2EE.5.4.2 Deployer's Responsibilities

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

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

• Bind the resource factory reference to a resource 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 name of the resource factory. The resource 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 resources. 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 signon information for the resource. This is performed in a manner specific to the 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 application component 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 manner specific to the container and resource manager; it is beyond the scope of this specification.

J2EE.5.4.3 J2EE Product Provider's Responsibilities

The J2EE product 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 factory classes.

• If the application component provider set the res-auth of a resource reference to Bean , the container must allow the application component to perform explicit programmatic signon using the resource manager's API.

• The container must provide tools that allow the deployer to set up resource signon 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 factory reference declared by the application component, and the container must be able to use the user/password combination for user authentication when obtaining a resource by invoking the resource factory.

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

While not required by this specification, most J2EE products will provide the following features:

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

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

J2EE.5.4.4 System Administrator's Responsibilities

The system administrator is typically responsible for the following:

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

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