Mapping References

The following XML elements map JNDI names configured in the Application Server to resource references in application client, EJB, and web application components:

• resource-env-ref - Maps the resource-env-ref element in the corresponding J2EE XML file to the absolute JNDI name configured in the Application Server.

• resource-ref - Maps the resource-ref element in the corresponding J2EE XML file to the absolute JNDI name configured in the Application Server.

• ejb-ref - Maps the ejb-ref element in the corresponding J2EE XML file to the absolute JNDI name configured in the Application Server.

JNDI names for EJB components must be unique. For example, appending the application name and the module name to the EJB name is one way to guarantee unique names. In this case, mycompany.pkging.pkgingEJB.MyEJB would be the JNDI name for an EJB in the module pkgingEJB.jar, which is packaged in the pkging.ear application.

These elements are part of the sun-web-app.xml, sun-ejb-ref.xml, and sun-application-client.xml deployment descriptor files. For more information about how these elements behave in each of the deployment descriptor files, see Appendix A, Deployment Descriptor Files.

The rest of this section uses an example of a JDBC resource lookup to describe how to reference resource factories. The same principle is applicable to all resources (such as JMS destinations, JavaMail sessions, and so on).

The resource-ref element in the sun-web-app.xml deployment descriptor file maps the JNDI name of a resource reference to the resource-ref element in the web-app.xml J2EE deployment descriptor file.

The resource lookup in the application code looks like this:

InitialContext ic = new InitialContext();
String dsName = "java:comp/env/jdbc/HelloDbDs";
DataSource ds = (javax.sql.DataSource)ic.lookup(dsName);
Connection connection = ds.getConnection();

The resource being queried is listed in the res-ref-name element of the web.xml file as follows:

<resource-ref>
   <description>DataSource Reference</description>
   <res-ref-name>jdbc/HelloDbDs</res-ref-name>
   <res-type>javax.sql.DataSource</res-type>
   <res-auth>Container</res-auth>
</resource-ref>

The resource-ref section in a Application Server specific deployment descriptor, for example sun-web.xml, maps the res-ref-name (the name being queried in the application code) to the JNDI name of the JDBC resource. The JNDI name is the same as the name of the JDBC resource as defined in the resource file when the resource is created.

<resource-ref>
   <res-ref-name>jdbc/HelloDbDs</res-ref-name>
   <jndi-name>jdbc/HelloDbDataSource</jndi-name>
</resource-ref>

The JNDI name in the Application Server specific deployment descriptor must match the JNDI name you assigned to the resource when you created and configured it.