J2EE^TM Developer's Guide
Database Connections

Coded Connections

The bean routine that connects to the database should not hardcode the actual name (URL) of the database. Instead, it should refer to the database with a logical name and use a JNDI lookup when obtaining the database connection. This level of indirection provides several benefits:

You can deploy the same enterprise bean in different environments that have databases with different names.
You can re-use the enterprise bean in multiple applications.
You can assemble the enterprise beans into applications that run in a distributed environment. (The enterprise beans and the databases they access may run on different machines.)

The instructions that follow show you how to link the logical database name in your code with the JNDI name of the resource manager connection factory-- a term that may be new to you. A resource manager is a storage mechanism such as a DBMS. A resource manager connection is an object, such as java.sql.Connection, that represents a session with the resource manager (DBMS). A resource manager connection factory is an object that creates resource manager connections. For example, a javax.sql.DataSource object is a connection factory because it creates a java.sql.Connection object.

How to Connect

The code examples in this section are from the the AccountEJB class, which was described in the the Entity Beans chapter. Because the AccountEJB class uses bean-managed persistence, it connects to the database with the following steps:

1. Specify the logical database name.

private String dbName = "java:comp/env/jdbc/AccountDB";

The java:comp/env/ prefix is the JNDI context for the component. The jdbc/AccountDB string is the logical database name.

2. Obtain the DataSource associated with the logical name.

InitialContext ic = new InitialContext();
DataSource ds = (DataSource) ic.lookup(dbName);

3. Get the Connection from the DataSource.

Connection con =  ds.getConnection();

When To Connect

When coding an enterprise bean, you must decide how long the bean will retain the connection. Generally you have two choices: either hold the connection for the lifetime of the bean, or only during each database call. Your choice determines the method (or methods) in which your bean connects to a database.

Longterm Connections

You can design an enterprise bean that holds a database connection for its entire lifetime. Because the bean connects and disconnects just once, its code is slightly easier to write. But there's a tradeoff-- other enterprise beans may not acquire the connection. Session and entity beans issue the lifelong connections in different methods.

Session Beans

The EJB container invokes the ejbCreate method at the beginning of a session bean's life cycle, and invokes the ejbRemove method at the end. To retain a connection for the lifetime of a session bean, you connect to the database in ejbCreate and disconnect in ejbRemove. If the session bean is stateful, you must also connect in ejbActivate and disconnect in ejbPassivate. A stateful session bean requires these additional calls because the EJB container may passivate the bean during its lifetime. During passivation, a stateful session bean is saved in secondary storage, but a database connection may not be saved in this manner. Because a stateless session bean cannot be passivated, it does not require the additional calls in ejbActivate and ejbPassivate. For more information on activation and passivation, see the section, "The Life Cycle of a Session Bean". For an example of a stateful session bean with a longterm connection, see the TellerEJB.java code.

Entity Beans

After instantiating an entity bean and moving it to the pooled stage, the EJB container invokes the setEntityContext method. Conversely, the EJB container invokes the unsetEntityContext method when the entity bean leaves the pooled stage and becomes eligible for garbage collection. To retain a database connection for its entire lifespan, an entity bean connects in the setEntityContext method and disconnects in the unsetEntityContext method. To see a diagram of the life cycle, refer to the section, "The Life Cycle of an Entity Bean". For an example of an entity bean with a longterm connection, see the AccountEJB.java code.

Shortterm Connections

Briefly held connections allow many enterprise beans to share the same connection. Because the EJB container manages a pool of database connections, enterprise beans can quickly obtain and release the connections. For example, a business method might connect to a database, insert a row, and then disconnect.

In a session bean, a business method that connects to a database should be transactional. The transaction will help maintain data integrity.

Specifying the JNDI Name for Deployment

Specifying the JNDI name of the database is a two-step process:

1. Enter the coded name.

To enter the coded name in the bean's deployment descriptor, you run the Application Deployment Tool and step through the New Enterprise Bean Wizard. In the Coded Name field of the wizard's Resource References dialog box, you enter the database name from the bean's code. For example, the logical database name coded in the AccountEJB class is the jdbc/AccountDB portion of the following string:

private String dbName = "java:comp/env/jdbc/AccountDB";

In the Coded Name field of the wizard, you enter jdbc/AccountDB. In the Type column, select javax.sql.DataSource.

2. Map the coded name to the JNDI name.

The Application Deployment Tool allows you to map this information in two ways: in a deployment dialog box and in the JNDI Names tabbed pane of the J2EE application. If the AccountEJB class connects to a Cloudscape database, for example, you enter jdbc/Cloudscape in the JNDI Name field of the JNDI Names tabbed pane.

The J2EE server automatically enters the database JNDI names such as jdbc/Cloudscape into the name space. The server obtains these JNDI names from the jdbc.datasources entry of the config/default.properties file. The jdbc.datasources entry maps the JNDI name to the URL of the database. (For more information on jdbc.datasources, see the Configuration Guide .)

Specifying Database Users and Passwords

To connect to the Cloudscape database bundled with this release, you do not specify a database user and password. Authentication is performed by a separate service. (For more information about authentication, see the Security chapter.)

However, some types of databases do require a user and password during connection. For these databases, if the getConnection call has no parameters, you must specify the database user and password with the Application Deployment Tool. To specify these values, click on the Resource Ref's tabbed pane of the enterprise bean, select the appropriate row in the table labelled, "Resource Factories Referenced in Code," and enter the database user name and password in the fields at the bottom.

If you wish to obtain the database user and password programmatically, you do not need to specify them with the Application Deployment Tool. In this case, you include the database user and password in the arguments of the getConnection method:

con = dataSource.getConnection(dbUser, dbPassword);

Prev | Next

TOC | Index