The J2EETM Tutorial

Database Connections for Enterprise Beans

The persistence type of an enterprise bean determines whether or not you code the connection routine. You must code the connection for enterprise beans that access a database and do not have container-managed persistence. Such beans include entity beans with bean-managed persistence and session beans. For entity beans with container-managed persistence, deploytool generates the connection routines for you.

Coded Connections

How to Connect

The code examples in this section are from the SavingsAccountBean class, which connects to the database via the following steps.

  1. Specify the database name.
    private String dbName = "java:comp/env/jdbc/SavingsAccountDB";
  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 it will retain the connection. Generally you have two choices: either hold the connection for the lifetime of the bean, or hold it only during each database call. Your choice determines the method (or methods) in which your bean connects to a database.

Long-Term 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 trade-off--other components cannot 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 cannot 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 Life Cycle of a Stateful Session Bean. For an example of a stateful session bean with a long-term connection, see the code in the j2eetutorial/examples/ejb/teller directory.

Entity Beans with Container-Managed Persistence

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 life span, an entity bean connects in the setEntityContext method and disconnects in the unsetEntityContext method. To see a diagram of the life cycle, see Figure 3-5. For an example of an entity bean with a long-term connection, see the code in the j2eetutorial/examples/ejb/savingsaccount directory.

Short-term Connections

Briefly held connections allow many components 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.

deploytool Tips for Specifying Database Users and Passwords

The instructions in this section do not apply to entity beans with container-managed persistence. For those entity beans, see the instructions in Specifying the Database JNDI Name, User Name, and Password.

To connect to the Cloudscape database bundled with this release, you do not specify a database user name and password; authentication is performed by a separate service. For more information about authentication, see Chapter 15.

However, some types of databases do require a user name and password during connection. For these databases, if the getConnection call has no parameters, you must specify the database user name and password with deploytool. To specify these values, perform these steps:

  1. Select the enterprise bean in the tree view.
  2. Select the Resource Refs tab.
  3. Select the appropriate row in the table labeled, 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 name and password programmatically, you do not need to specify them with deploytool. In this case, you include the database user name and password in the arguments of the getConnection method:

con = dataSource.getConnection(dbUser, dbPassword);

Connection Pooling

The EJB container maintains the pool of database connections. This pool is transparent to the enterprise beans. When an enterprise bean requests a connection, the container fetches one from the pool and assigns it to the bean. Because the time-consuming connection has already been made, the bean quickly gets a connection. The bean may release the connection after each database call, since it can rapidly get another connection. Because such a bean holds the connection for a short time, the same connection can be shared sequentially by many beans.