The J2EETM Tutorial

JNDI Names and Resource References

First, let's define some terms.

JNDI is the acronym for the Java Naming and Directory Interface API. J2EE components locate objects by invoking the JNDI lookup method.

A JNDI name is a people-friendly name for an object. These names are bound to their objects by the naming and directory service that is provided by the J2EE server. Because J2EE components access this service through the JNDI API, we usually refer to an object's people-friendly name as its JNDI name. The JNDI name of the Cloudscape database is jdbc/Cloudscape. When it starts up, the J2EE server reads information from a configuration file and automatically adds JNDI database names such as jdbc/Cloudscape to the name space.

A connection factory is an object that produces connection objects that enable a J2EE component to access a resource. The connection factory for a database is a javax.sql.DataSource object, which creates a java.sql.Connection object.

A resource reference is an element in a deployment descriptor that identifies the component's coded name for the resource. More specifically, the coded name references a connection factory for the resource. In the example in the following section, the resource reference name is jdbc/SavingsAccountDB.

The JNDI name of a resource and the name of the resource reference are not the same. This approach to naming requires that you map the two names before deployment, but it also decouples components from resources. Because of this decoupling, if at a later time the component needs to access a different resource, you don't have to change the name in the code. This flexibility also makes it easier for you to assemble J2EE applications from preexisting components.

deploytool Tips for Resource References

The instructions that follow refer to the entity bean described in the section The SavingsAccountEJB Example. The SavingsAccountEJB code is in the j2eetutorial/examples/src/ejb/savingsaccount directory. A sample SavingsAccountApp.ear file is in the j2eetutorial/examples/ears directory.

Specifying a Resource Reference

  1. In deploytool, select SavingsAccountEJB from the tree.
  2. Select the Resource Refs tab.
  3. Click Add.
  4. In the Coded Name field, enter jdbc/SavingsAccountDB.
    The SavingsAccountBean code refers to the database as follows:
    private String dbName = "java:comp/env/jdbc/SavingsAccountDB";
    The java:comp/env prefix is the name of the JNDI context for the component. The jdbc/SavingsAccountDB string is the JNDI name for the resource reference. The JNDI names for JDBC DataSource objects are stored in the java:comp/env/jdbc subcontext.
  5. In the Type combo box, select javax.sql.DataSource. A DataSource object is a factory for database connections.
  6. In the Authentication combo box, select Container.
  7. If you want other enterprise beans to share the connections acquired from the DataSource, select the Sharable checkbox.

If the preceding steps are followed, the Resource Refs tab will appear as shown in Figure 16-1.

Figure 16-1 Resource Refs Tabbed Pane of SavingsAccountEJB

Mapping a Resource Reference to a JNDI Name

  1. Select the J2EE application from the tree.
  2. Select the JNDI Names tab.
  3. In the References table, select the row containing the resource reference. For the SavingsAccountEJB example, the resource reference is jdbc/SavingsAccountDB, the name you entered in the Coded Name field of the Resource Refs tab.
  4. In the row you just selected, enter the JNDI name. For the SavingsAccountEJB example, you would enter jdbc/Cloudscape in the JNDI Name field.
    The JNDI Names tab for SavingsAccountApp is shown in Figure 16-2.

Figure 16-2 JNDI Names Tab of SavingsAccountApp