Transactions enable J2EE applications to maintain consistent, durable, and reliable persistent storage of data in a database. In Chapter 13, “Accessing Data Repositories Using JDBC,” an overview for writing applications that use and perform Java Database Connectivity is presented. This chapter builds on the infrastructure of JDBC to create J2EE applications that ensure durable and consistent storage of the application data. The Java technology that provides this capability is the Java Transaction API (JTA). A J2EE application is not useful if the data that it generates cannot be trusted to be consistent and accurate. After all, it is called a relational database because of the relationships between the data. Using database transactions correctly is extremely important so that all data affected by the transaction is modified as a group, or none of the data is modified. Otherwise, the database can become corrupted or contain inconsistent data.

This chapter introduces database transactions using JTA. Specifically, this chapter examines the way transactions are used in a J2EE application that is deployed in WebLogic Server. Managing database transactions using the performance tips provided here will help you to build robust, reliable, high-performance J2EE applications. A Servlet example is also presented to show how these technologies work together in a J2EE application.

Chapter 13 included an example that created a database to maintain inventory for a bookstore. Here, you will extend the bookstore example to add the capability to sell books. This example will provide an introduction to transactions against a single database. A few modifications to the database schema are required to add the price and inventory count to each book. The Books table needs two additional columns, the price as a REAL SQL data type and the number of copies in stock as an INTEGER. The customers will be identified with a name and ID. Each customer will have a balance to be used as the funds for purchasing books. The Customers table will therefore include the customer_name as a VARCHAR, customer_id as an INTEGER, and balance as a FLOAT. Selling books from the inventory requires a new many-to-many relationship between customers and books. Each customer can purchase many books, and each book can be purchased by many customers. The database now requires the Books table and two new tables, the Customers table and an association table called the ShoppingCart table, as shown in Figure 16.1.

Figure 16.1. The ShoppingCart table allows a many-to-many relationship between Customer and Books.

The scenario for a customer to purchase a book is as follows:

Steps 5, 6, and 7 must be performed as a transaction. In other words, a transaction must be established to complete or fail steps 5 through 7 as a group. It is clear that if the transaction only partially completes, the database would be in an invalid state. More than likely, the customer would not be pleased either. This example requires three database updates to be completed together. When all the statements complete successfully, they will be committed to the database. If any operation fails, a rollback will be performed. JDBC throws an SQLException to indicate errors. The rollback is therefore performed in the catch block for SQLException. If no exceptions are thrown, the commit will be executed. By default, JDBC is in auto-commit mode, meaning each statement is automatically committed to the database. You need to disable auto-commit to be able to control transaction management. Assuming a Connection object named con has already been obtained from either the DriverManager or a DataSource, Listing 16.1 shows the try block that performs the sample transaction.

try {
    con.setAutoCommit( false );    // disable auto-commit
    Statement s = con.createStatement();
    s.executeUpdate( "UPDATE books SET copies = " + ( copies – 1 ) +
        "WHERE title = " + title );
    s.close();
    s = con.createStatement();
    s.executeUpdate( "UPDATE customers SET balance = " + ( balance – price ) +
        "WHERE customer_name = " + name );
    s.close();
    s = con.createStatement();
    s.executeUpdate( "INSERT INTO ShoppingCart VALUES ( " +
        customerID + ", " + bookID + " )" );
    s.close();
    con.commit();
} catch( SQLException x ) {
    System.err.println( "Update Failed, rolling back" );
    try { con.rollback() }
    catch( SQLException x ) { }
}

Transactions against a single database are handled quite cleanly by the commit() and rollback() methods of the JDBC Connection object. An example of this was shown in Listing 16.1. J2EE applications often have much more complex transactions resulting from their distributed nature. For example, the same transaction may span multiple tiers, possibly shared by the servlet and EJB. Also, multiple databases may be involved in the same transaction. Such transactions are referred to as distributed transactions. The Java Transaction API (JTA) provides the ability to handle distributed transactions. The WebLogic services specifically designed for distributed transactions work with JTA, XA-compliant resources, and Two-Phase Commit (2PC) operations. These topics are addressed in the section “Performing Distributed Transactions with a Transaction Manager,” later in this chapter.

Cooperation occurs between the application server and the database server to ensure that transactions have basic properties that are referred to by the mnemonic ACID (see Table 16.1).

The database that you use with WebLogic Server must be ACID-compliant. The JDBC drivers offered by BEA WebLogic all connect to ACID-compliant databases.

Whether the transaction is simple or distributed, the requirement is the same—to complete a set of database actions as a group, which is referred to as atomicity (refer to Table 16.1). To support transaction management, the database being used must be ACID-compliant. An ACID-compliant database can process the standard SQL commands that are used with transaction management; these commands are shown in Table 16.2.

The JDBC Core API provides access to the database from Java applications, as shown in Chapter 13. The JDBC Optional Package and JTA supplement the JDBC Core API to address the requirements of distributed applications. The new functionality that is provided by the JDBC Optional Package includes

Two very significant features provided by the database driver vendor and the application server are distributed transactions and connection pooling. These features enable the portability, robustness, and data durability required by enterprise applications. As a J2EE developer, it is essential to have a basic understanding of distributed transactions and connection pooling. You can then incorporate these features into your J2EE applications using the JDBC Optional Package and JTA.

The DataSource interface is implemented by a driver vendor. The particular implementation of the DataSource allows the middle-tier infrastructure to provide connection pooling and distributed transactions. The DataSource therefore is implemented in one of three manners:

The Java Transaction API provides functionality to allow an application to explicitly manage transaction boundaries. The interface that defines the methods for transaction management is the UserTransaction interface. Both the DataSource and UserTransaction objects are used directly by a server-side component of a J2EE application. This component is either a servlet or an Enterprise JavaBean. The objects that implement the DataSource or UserTransaction interface are registered with a naming service. The Java application obtains an instance of these objects using the JNDI API.

The API for the JDBC Optional Package is in the javax.sql package. The API for JTA is in the javax.transaction and javax.transaction.xa packages. The package names follow the Java naming convention, indicating that they are standard extensions to the Java programming language. They are included as part of the standard Java SDK 1.4 release. The server-side data source access provided by the JDBC Optional Package and the transaction management provided by JTA make these APIs essential features of the J2EE architecture.

Context ctx = new InitialContext();
DataSource ds = (DataSource)ctx.lookup( "MY_DATASOURCE_NAME" );
Connection con = ds.getConnection( DATABASE_USER", "DATABASE_PASSWORD );

RowSet rs = new ImaginaryRowSet();         // create the RowSet object
rs.setDataSourceName( "MY_DATASOURCE" );   // configure the DataSource
rs.setUsername( "DATABASE_USER" );         // configure database user and password
rs.setPassword( "DATABASE_PASSWORD" );
rs.setCommand( "SELECT * FROM books " +    // configure the PreparedStatement
"WHERE title = ?" );

rs.setString( "MY_FAVORITE_BOOK" );
rs.execute();
while( rs.next() )
    System.out.println( "Book id is " + rs.getInt( "book_id" ) ) ;

try {
Context ctx = new InitialContext();
UserTransaction tx = (UserTransaction)ctx.lookup( "javax.transaction.UserTransaction" );
tx.begin();    // start transaction
// locate DataSource, establish connection, execute operations, close connections
tx.commit();    // commit transactions
} catch( Exception x ) {
    System.err.println( "error has occurred" );
try {
    tx.rollback();
} catch( javax.transaction.SystemException se ) { }
    }

The connection pool is configured through the WebLogic Server Console. Figure 16.2 shows the WebLogic JDBC Connection Pools page for creating a new JDBC Connection Pool. Follow these steps to configure a new connection pool:

Figure 16.2. Connection Pools are configured through the WebLogic Server Console.

The data source is configured through the WebLogic Server Console. The Tx DataSources support distributed transaction where standard DataSources do not. Figure 16.3 shows the WebLogic JDBC Tx DataSources page to create a new JDBC Tx DataSource. Follow these steps to configure a new Tx DataSource:

Tip

As shown in Figure 16.3, each field in the form is preceded with a “?” character. Click on the “?” to view context-sensitive help for the particular field.

Figure 16.3. Tx DataSources are configured through the WebLogic Server Console to support distributed transactions.

The middle tier of the JTA architecture is the Transaction Manager. The responsibility of the Transaction Manager is to manage the communication between the application and XA-Compliant resources. The transaction manager provides the ability to perform distributed transactions by coordinating and controlling the resources that are participating in the transaction. The application starts a transaction with the transaction manager, and then opens and communicates with the Tx DataSource objects that are participating in the distributed transaction. The application finally requests the transaction manager to commit all data storage modifications. The transaction manager performs a Two-Phase Commit operation, as explained in the “Two-Phase Commit (2PC)” section later in this chapter. If the transaction manager is unable to commit the transaction to all the participating resources, it will roll back the entire distributed transaction.

The WebLogic JTA driver provides a full distributed transaction implementation of the DataSource interface. The JTA driver also supports connection pooling. To enhance performance, the WebLogic JTA driver uses standard SQL commands to the database when the scope of the transaction is limited to a single DataSource.

To provide all the ACID properties between WebLogic Server and the database server, the transaction services provided by the JTA driver require that all resources involved in the transaction are XA-compliant. When multiple DataSources are involved in the transaction, the JTA driver uses a Two-Phase Commit (2PC) engine. Finally, distributed transactions introduce race conditions and concurrency issues that must be dealt with. This refers to the Isolation property of ACID. For example, two separate transactions might try to update the same data at the same time. JDBC specifies Transaction Isolation Levels that allow you to control how the database behaves in these situations. Each of these topics were introduced in the preceding sections.

Listing 16.2 shows a complete example using JDBC and JTA from a servlet deployed on the WebLogic Platform. The BookStoreServlet provides the user interface for a Web-based application to search for and order books. This example focuses on using JDBC with JTA. Refer to Chapter 19 “Servlets and JavaServer Pages—Best Practices” for more information on servlets. The init() method in the BookStoreServlet connects to the WebLogic JNDI naming service. The JNDI connection is used to lookup the DataSource for the relational database. The service() method is invoked when the HTML form that is handled by this servlet is submitted. The first step in the service() method is to lookup the JTA UserTransaction in the WebLogic naming service. All further processing is performed within a transaction which is either committed, if all completes successfully, or rolled back, if an error occurs. The following actions are performed within the transaction:

The BookStoreServlet checks the inventory for the number of available copies of the book and the customer’s balance to verify that the balance is greater than the price of the book. If the book is out of stock or the customer’s balance is less than the price of the book, throw an exception which will roll back the transaction. These checks are performed in queryBook() and queryCustomer() respectively.

This example was created using Together ControlCenter version 6.0. The class diagram was created using the Class By Pattern tool and choosing the Servlet pattern. For the pattern properties, we chose Implement Method init() and Implement Method service(). Together they generate the class diagram and template source code. The remainder of the application was manually edited within the Java source code.

Figure 16.4. The class diagram of the BookStore servlet shows the attributes and methods for the class.

/* Generated by Together */
import java.io.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.Statement;
import javax.transaction.UserTransaction;

public class BookStoreServlet extends HttpServlet  {
    // constants
    private static final String DATASOURCE_NAME = "datasource-demopool";
    private void parseForm( HttpServletRequest req ) {
        Enumeration fields = req.getParameterNames();
        while( fields.hasMoreElements() ) {
            String field = (String)fields.nextElement();
            if( field.equals( "name" ) )
                name = req.getParameter( field );
            else if( field.equals( "title" ) )
                title = req.getParameter( field );
        }
    }
    public void init(ServletConfig config)throws ServletException{
        super.init(config);
        //
        //Write your code here
        //
        name = null;
        title = null;
        try {
            // create a connection to the WebLogic JNDI Naming Service
            ctx = new InitialContext();
            // locate a DataSource in the Naming Service
            ds = (DataSource)m_ctx.lookup( DATASOURCE_NAME );
        }
        catch( Exception x ) {
            System.err.println( "Error in init(): " + x );
        }
    }

    public String getServletInfo(){
        return "Servlet description";
    }

    public void service(HttpServletRequest request, HttpServletResponse response)
        throws ServletException, IOException {
        //
        //Write your code here
        //
        Connection con = null;
        UserTransaction tx = null;

        try {
            PrintWriter out = res.getWriter();
            // print the HTML header
            out.println( "<html>" );
            out.println( "<head><title>Book Store Servlet</title></head>" );
            out.println( "<body>" );
            out.println( "<h1>Book Store Servlet</h1>" );
            // locate a UserTransaction in the Naming service
            tx = (UserTransaction)ctx.lookup(
                "javax.transaction.UserTransaction" );
            // start a transaction
            tx.start();
            // get a JDBC Connection from the DataSource
           con = ds.getConnection();
            // create a Statement
            Statement st = con.createStatement();
            // get customer name and book name from the HTML form
            parseForm( req );
            // search database for requested data
            queryBook( con );
            queryCustomer( con );
            // update the database
            con.setAutoCommit( false );    // disable auto-commit
            st.executeUpdate( "UPDATE books SET copies = " + ( copies - 1 ) +
                " WHERE title = " + title );
            st.close();
            st = con.createStatement();
            st.executeUpdate( "UPDATE customers SET balance = " +
                ( balance - price ) +
                " WHERE customer_name = " + name );
            st.close();
            st = con.createStatement();
            st.executeUpdate( "INSERT INTO ShoppingCart VALUES ( " +
                customerID + ", " + bookID + " )" );
            st.close();
            // commit the transaction
            tx.commit();
            out.println( "<h2>Success</h2>" );
            out.println( "</body>" );
            out.println( "</html>" );
        }
        catch(Exception x ) {
            System.err.println( "Rolled back transaction: " + x.toString() );
            tx.rollback();
        }
    }
    private void queryCustomer( Connection con, float price )
        throws SQLException, Exception {
        Statement st = con.createStatement();
        ResultSet rs = st.executeQuery(
            "Select * from customers WHERE customer_name = " + name  );
        rs.next();
        customerID = rs.getInt( "customer_id" );
        balance = rs.getFloat( "balance" );
    // verify balance is greater than price of book
    if( balance < price )
    {
       throw new Exception( name + " has insufficient funcds" );
    }
    }
    private void queryBook( Connection con )
        throws SQLException, Exception {
        Statement st = con.createStatement();
        ResultSet rs = st.executeQuery(
            "Select * from books WHERE title = " + title );
        rs.next();
        bookID = rs.getInt( "book_id" );
        price = rs.getFloat( "price" );
        copies = rs.getInt( "copies" );
    // verify there is at least 1 copy of the book
    if( copies == 0 )
    {
        throw new Exception( title + " is out of stock" );
    }
    }
    private Context ctx;
    private DataSource ds;

    private String name;
    private int customerID;
    private float balance;

    private String title;
    private int bookID;
    private int copies;
    private float price;
}

The WebLogic Application Server with the JTA driver provides full support for J2EE applications that require distributed transactions. Best of all, it is implemented transparently to the application. The JTA driver provides the transaction manager, and the XA-compliant resources provide the resource managers. The J2EE application need only locate the UserTransaction and DataSource objects in the naming and directory service using JNDI and start the transaction. After the Connection object is obtained from the DataSource, access to the data using JDBC is exactly the same. After you successfully perform all the updates, invoke the commit() method on the UserTransaction object. If any exceptions are thrown, indicating an error condition, you can perform a rollback.