Transactions overview

When writing almost any application for Geronimo, you encounter the need to create and handle transactions. In many circumstances, such as manipulating database records, operating on container-managed relations (CMRs), and sending Java Message Service (JMS) messages, Geronimo forces you to use transactions, or else it returns with an error condition.

To get more familiar with the important details of using transactions in Geronimo applications, you'll work with a small application called Transaction Demo, created for deployment in a Geronimo application server. The development was based on an early release of Geronimo M5 (the fifth milestone release). (See Resources for a link to the Apache Software Foundation site to download the latest release of the Geronimo application server.)

J2EE applications use transactions whenever databases are accessed during CMP. If an error occurs while creating, updating, or deleting an entity bean, the previous state of the database can be restored, and the user can be notified that there was a problem. The main concern here is data integrity. A transaction protects data integrity in your database by undoing any potentially incomplete operations.

In a J2EE application you can either create a transaction and manage its lifetime in your own code by obtaining and using instances of the UserTransaction class (see the Directly remove Sol section), or you can rely on the EJB container to create and manage transactions for you by employing CMTs. You get details about using both of these methods with the Geronimo application server.

As previously mentioned, transactions aren't just for databases. A key part of the J2EE specification describes the use of transactions within the Java Message Service (JMS). JMS is a critical component of message-driven beans (MDBs) and can be used within a transaction so that messages that could not be delivered due to some exception will roll back the transaction, causing the message to be redelivered. Geronimo embeds the ActiveMQ JMS service, so you're welcome to try creating an MDB. You can even use the Geronimo console to start the SystemJMS configuration and configure the JMS server. This is beyond the scope of this article, however. (See Resources for more information on these topics.)

This article covers the use of transactions from within a Web application as well as through a stateless session bean instance using CMTs. It also shows examples of recovering from a failed transaction gracefully.

Back to top

The sample program

Transaction Demo, the sample program used in this article to demonstrate transactions, is a Struts application that has all the deployment plans necessary to be deployed in the Geronimo application server. It provides a simple menu that allows you to interact with a basic database of stars (as in the sun and other celestial bodies, not Hollywood movie stars), and it demonstrates many key concepts of using transactions within your Geronimo programs.

To run the Transaction Demo program, you must first build the Geronimo application server from source code. The Maven build scripts for the sample program only complete if many of the Geronimo build products are available during build time. You also need to download XDoclet 1.2.3 from sourceforge.net (see Resources for a link) and install any missing binaries into your Maven repository. (This step won't be required when the IBiblio Maven repository includes all of the XDoclet 1.2.3 binaries. At the time of this writing, at least one binary is missing from the repository.)

After you have the build working correctly, you'll find in the resulting target directory a transactiondemo-ejb.sql file. This is the SQL schema for the application. If you complete the following steps, you can install the schema into the Apache Derby built-in database within Geronimo.

First, start up your Geronimo server with the following command line:

java -jar server.jar

This starts the server and the new Geronimo console, which manages your server and a list of other Geronimo services for deployment of applications. (Note: This is only true if you are using the M5 version of Geronimo. Previous versions only start a minimal server, and deploying to that would require you to start more services.)

Next, connect to the console with your Web browser by going to http://localhost:8080/console. You should see the console welcome screen, as shown in Figure 1. Log in with the default user name system and the password manager.

When you're logged in, navigate using the left navigation bar, and choose All Configurations. Look at the Installed Applications list, and ensure that you start (or see that it's running) the org/apache/geronimo/SystemDatabase configuration by clicking the Start link next to it. This starts the Apache Derby database engine so that you can configure it (see Figure 2). At a minimum, to compile and get the demo application running, you need to have at least the following configurations started:

org/apache/geronimo/RuntimeDeployer
org/apache/geronimo/JettyRuntimeDeployer
org/apache/geronimo/SystemDatabase

Next, scroll down to the bottom of the navigation bar, and select the DB Manager link. This portlet (as they are called by the console developers) provides a simple way to perform SQL queries against the system database and create new databases. Enter the SQL from the transactiondemo-ejb.sql file (without the drop table statement) into the SQL Command text area, and click the Run SQL button, as shown in Figure 3.

This creates the table needed by the demo application. You can see the tables in the database by clicking the Application link under the View Tables selection in the Database List section of the DB Manager portlet. Of course, exploring any of the other great features of the Geronimo console at this time is recommended. Now, if you've run the Maven command in the source directory, the transactiondemo application will be installed. You can access it by going to the URL http://localhost:8080/trasactiondemo where you can see the screen shown in Figure 4.

The menu links on the left side of the screen call database code with transactions in various ways. The meaning of these menu items is described below, but more precise details about each menu item's function are in subsections later in the article.

• Clear clears the Stars database table.
• Add Records with Failure adds several records, but the method throws an exception before finishing, so the CMT is rolled back automatically.
• Add Records adds records without throwing an exception.
• Directly Remove Sol demonstrates handling a transaction in the Web tier by obtaining a UserTransaction instance and using it within the Struts action.

The code for each of these options is described later in the article.

Clear the database

Selecting the Clear menu item clears the database records so you can start fresh when playing with the demo. To clear the database, the program uses a stateless session bean that automatically starts CMTs. The TransactionDemoSessionBean.java class contains a clear() method (see Listing 1) that performs the required iteration of the entities and removes each one. Because this is performed as a single transaction, the operation should be relatively fast, even though at a low level this is probably translated into one delete statement (in SQL) for each star.remove().

        
/**
 * Perform the first test.
 * @throws NamingException 
 * @throws CreateException 
 * 
 * @ejb.interface-method view-type="both"
 * @ejb.transaction      type="Required"
 */
public void clear() {
   try {
      Collection stars = StarUtil.getLocalHome().findAll();
      Iterator i = stars.iterator();
      while(i.hasNext()) {
         StarLocal star = (StarLocal)i.next();
         star.remove();
      }
   } catch (Throwable ex) {
      ex.printStackTrace();
   }
}

This code is decorated with XDoclet tags, specifically the @ejb.transaction tag, which specifies that a transaction is required for entry into the clear() method. The XDoclet tag translates into an entry in the ejb-jar.xml deployment descriptor (see Listing 2) that instructs Geronimo to create a CMT if the calling thread is not already associated with a transaction.

        
   <container-transaction>
      <method>
         <ejb-name>TransactionDemoSession</ejb-name>
         <method-intf>Local</method-intf>
         <method-name>clear</method-name>
         <method-params>
         </method-params>
      </method>
      <trans-attribute>Required</trans-attribute>
   </container-transaction>

The nice thing about CMTs is that you don't have to worry about starting them, rolling them back, or committing them. The container does all of that automatically. For example, if some sort of exception happened in the middle of removing all the star records from the database, Geronimo would initiate a rollback of the transaction, and none of the deletions would be committed within the clear() method. The following section demonstrates this rollback behavior.

Add Records with Failure

The Add Records with Failure menu item in the Transaction Demo application demonstrates what happens to a transaction when an exception occurs sometime during the operation. As mentioned in the previous section, if an exception occurs during a method that has been marked as having CMTs, the transaction will automatically be rolled back. In the code in Listing 3, there's an exception that is always thrown at the end of the method, thereby forcing a rollback.

        
 /**
  * Perform the first test. This test makes an attempt to 
  * add a number of stars, but then throws an exception.
  *
  * @throws NamingException 
  * @throws CreateException 
  * @throws IllegalStateException always
  * 
  * @ejb.interface-method view-type="both"
  * @ejb.transaction      type="Required"
  */
 public void test1() throws CreateException, NamingException, 
     IllegalStateException {
   StarLocalHome home = StarUtil.getLocalHome();
   home.create("Sol");
   home.create("Betelguese");
   home.create("Andromeda");
   throw new 
        IllegalStateException("Pretending that something"+
        " bad happened.");
   }

At the end of the method is an IllegalStateException that is always thrown. If the transactions work, you should never observe any of the stars -- Sol, Betelguese, or Andromeda -- being created within the database, because the exception rolls back any changes. As you can see, this is indeed what happens.

Add Records

The Add Records menu item in the Transaction Demo application does the opposite of the Add Records with Failure item. It demonstrates what happens if there are no exceptional circumstances; namely, it inserts records into the database. There isn't much going on in the method in Listing 4 except the fact that no exception is thrown by the code. So if all is well with the database, the CMT commits, and the records should appear in the list. Figure 5 shows the result of this operation in the test application. There is a way to produce an exception with this menu option, however. Simply running it twice will produce an error, because the same star names (which are the primary key for the table) are used again, causing an error with duplicate primary key values. If you use the fourth menu option to delete the star Sol, and then try creating the records again, Sol doesn't reappear because of this exception. The transaction is rolled back in that case.

        
/**
 * Perform the second test. This test adds the stars, 
 * and if nothing goes wrong, they will be in the database.
 * @throws NamingException 
 * @throws CreateException 
 * 
 * @ejb.interface-method view-type="both"
 * @ejb.transaction      type="Required"
 */
public void test2() throws NamingException, CreateException {
   StarLocalHome home = StarUtil.getLocalHome();
   home.create("Sol");
   home.create("Betelguese");
   home.create("Andromeda");
   home.create("Aries");
   home.create("Omicron Cetus");
}

Directly remove Sol

The Directly remove Sol menu item in the Transaction Demo application provides an example of how to call transaction code from the Web application's perspective. Here you want some code in the Web tier to access the star entities directly and actually remove one of them, named Sol. The code in Listing 5 shows how this is done by using a UserTransaction. An InitialContext object, which is part of the Java Naming and Directory Interface (JNDI) API, is used to look up an instance of UserTransaction using the J2EE standard name .java:comp/UserTransaction. After it's acquired, it's used to start and commit a transaction, and if there are any errors, the transaction is rolled back.

        
/**
* Remove the star Sol from the database by performing 
* the operation directly on the Star EJB instead of going 
* through the session bean.
* @throws NamingException if the user transaction cannot be found.
* @throws SystemException if the transaction cannot be used.
* @throws NotSupportedException if the transaction cannot be used.
*/
private void removeSol() throws NamingException, 
   NotSupportedException, SystemException {
      
InitialContext ctx = new InitialContext();
UserTransaction tx = null;
      
    try {

   // Look up the transaction
   tx = (UserTransaction)ctx.lookup("java:comp/UserTransaction");

   // Begin the transaction now
   tx.begin();
         
   StarLocal sun = 
                    StarUtil.getLocalHome().findByPrimaryKey("Sol");
      sun.remove();
         
      // We've succeeded, so commit the transaction
      tx.commit();
         
   } catch (Throwable e) {
      // An error occurred, so roll back.
      tx.rollback();
      e.printStackTrace();
   } finally {
      // Dispose of the initial context.
      if (ctx != null) {
         try {
            ctx.close();
         } catch (Throwable ex) {
         }
      }
   }
}

Back to top

Use a stateless session bean for new transactions

If you look through the Transaction Demo source code, you find very little mention of transactions. This is because the Geronimo container is handling most of them in the background, as a good J2EE container should. Every stateless session bean method that is marked with a container transaction section in the deployment descriptor (ejb-jar.xml) is automatically provided with a CMT by the Geronimo EJB container. CMTs are a very good way to simplify your code. The stateless session bean with container-managed transactional methods, as described in Listing 5 and Listing 6, reduce the complexity involved with managing database entities. When you are operating on a single type of entity bean without any complex relations, simply marking the method with a transaction type of Required or RequiresNew is sufficient (see Listing 6 for the applicable DTD).

        
"The trans-attribute element specifies how the container 
must manage the transaction boundaries when delegating a
method invocation to an enterprise bean's business method.

The value of trans-attribute must be one of the following:

   <trans-attribute>NotSupported</trans-attribute>
   <trans-attribute>Supports</trans-attribute>
   <trans-attribute>Required</trans-attribute>
   <trans-attribute>RequiresNew</trans-attribute>
   <trans-attribute>Mandatory</trans-attribute>
   <trans-attribute>Never</trans-attribute>

Used in: container-transaction"

The Transaction Demo application sets up the transaction type using the XDoclet code generator. So if you examine the documentation comments surrounding the method in Listing 4, you find the @ejb-transaction type="Required" tag. The Required transaction type specifies that the session bean method requires a transaction to be present while its code is executing. If one does not exist, the container supplies one. If one is already present in the calling thread, that transaction is used.

The RequiresNew transaction type is different. If a transaction doesn't exist on the calling thread, one is created by the container, similar to the Required transaction type. However, if there is already a transaction on the calling thread, that transaction is suspended, and a new transaction is created and used. The calling transaction is then resumed.

Back to top

Summary

You should now have a good idea of how to use transactions in a J2EE application server, with a Transaction Demo application designed to run under a Geronimo application server. You've also been given examples of how to set up CMTs using stateless session beans, and you've been shown how to create a transaction and manage its lifetime by obtaining an instance of the UserTransaction class. Now you can take advantage of using transactions with Geronimo to maintain data integrity.

Back to top

Download

Description	Name	Size	Download method
Transaction demo application	transactions.zip	34 KB	HTTP | Download Director

Information about download methods

Resources

Learn

• Visit the developerWorks Apache Geronimo project area to access resources for Geronimo developers.
  
  
• Read the article, "Java theory and practice: Understanding JTS -- An introduction to transactions" (developerWorks, March 2002).
  
  
• Check out the article, "Understanding JCA transactions" (developerWorks, October 2004).
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  
• Read "J2EE Transaction Frameworks: Building the Framework at ONJava.com."
  
  
• See the comprehensive "Transaction Management" chapter in this J2EE specification document (PDF format).
  
  
• Read the "Transactions and EJB" chapter of Professional EJB (PDF format) for excellent coverage of EJBs.
  
  

Get products and technologies

• Download a nightly build of Apache Geronimo M5 (the official M5 release will be available soon) so you can run the Transaction Demo example. You can also download the latest version of Geronimo from the Apache Software Foundation.
  
  
• Download XDoclet 1.2.3 from Sourceforge.
  
  
• Get expert technical support with the IBM Support for Apache Geronimo offering.
  
  
• Access the complete ejb-jar_2_0.dtd file. If you're using Microsoft Internet Explorer, right-click the complete ejb-jar_2_0.dtd link, and choose Save Target As... to download the file.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  
• Download Gluecode Standard Edition, an open source application server based on Apache Geronimo.
  
  

Discuss

• Participate in the discussion forum.
  
  

About the author

Neal Sanche is a Java developer recently beached in the Microsoft® .NET world and fighting for any ties back to his old, comfortable roots. His experience includes development of several commercial J2EE applications, as well as several stand-alone Java applications. In his spare time, he writes music, takes photographs, and writes technical articles. Visit his Web site to see several examples of each.

Rate this article

Comments

Back to top

Table of contents

• Transactions overview
• The sample program
• Use a stateless session bean for new transactions
• Summary
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
• Buy: Rational Application Developer

Dig deeper into Java on developerWorks

Discover knowledge paths

Skill-building guides for Java, Linux, open source, cloud, business analytics, and more.

Special offers