An application uses JEUS transaction manager to perform transaction related tasks on the resource manager.

Either a local transaction or global transaction can be used depending on how many resource managers an application uses. In addition, the configuration and application programming methods depend on which agent has the authority over the transactions.

JEUS provides two transaction managers, the server transaction manager and client transaction manager.

The server transaction manager provides all functions for managing a global transaction, while the client transaction manager only acts as the proxy of a server transaction.

Server Transaction Manager

The server transaction manager implements all of the Java Transaction API and is used when a server application uses a transaction.

When a global transaction is started, the server transaction manager collects all the information related to the global transaction and proceeds with the tasks acting as the transaction coordinator. Depending on the situation, the role of the server transaction manager consists of the root coordinator and sub coordinator.

[Figure 7.1] Relationship between Root Coordinator and Sub Coordinator

Client Transaction Manager

The client transaction manager operates as the proxy of the server transaction manager.

The server transaction manager that receives the signal from a global transaction becomes the root coordinator and collects and processes all information related to the transaction. To commit the transaction, the transaction manager sends the commit signal to the root coordinator and receives the result of the commit.

Applications can perform tasks with various resource managers. Connection managers manage connections to the resource manager.

JEUS provides four types of connection managers (JDBC Connection Manager, JMS Connection Manager, WebT Connection Manager, and Connector Manager). Connection managers report transaction related information to the transaction manager for processing a global transaction.

In JEUS transaction manager, a multiple number of worker threads are used to support communication with other transaction managers. The transaction manager uses the system thread pool on the server by default. The thread pool can be configured on a server where transaction and fast processing is important.

As previously described, the system thread pool or dedicated thread pool can be selected for use. However, the pool type cannot be changed during server operation. The server must be restarted to apply the modified pool type. However, with the exception of the dedicated thread pool's queue size, the pool configurations can all be dynamically changed without restarting the server.

Using WebAdmin

The following describes the process of changing a thread pool in WebAdmin. The thread pool configuration can be changed in the lower part of the page. To configure a thread pool, check the Pooling checkbox.

Using the Console Tool

The following describes how to change a thread pool by using the console tool.

The JEUS transaction manager uses various timeout mechanisms for processing exceptions. The transaction manager can be tuned to be suitable for the application system by adjusting the timeout mechanism. The timeout configuration is static and requires a server restart. The configuration must be set before starting the server or the server must be restarted if it is changed while the server is running.

Using WebAdmin

The following describes how to change the timeout setting in WebAdmin. A multiple number of timeout configurations can be changed from the bottom section of the Tm Config page.

[Figure 7.4] Changing the Timeout Setting in WebAdmin

The following tables describe the configuration items.

Using the Console Tool

The following describes how to change the timeout setting in the console tool.

The transaction manager's timeout setting can be changed by executing modify-transaction-manager. For more information about the command, refer to JEUS Reference Book. "4.2.13.1. modify-transaction-manager".

[DAS]domain1.adminServer>modify-transaction-manager server1 -activeTimeout 20000
Successfully performed the MODIFY operation for transaction of server (server1), but all changes were non-dynamic. They will be applied after restarting.
Check the results using "show-transaction-manager server1 or modify-transaction-manager server1"

The transaction manager is divided into the root coordinator and sub coordinator depending on its role. Since the sub coordinator gets transaction-related information from the root coordinator, it must register itself with the root coordinator and make sure that the root coordinator knows that the sub coordinator exists.

The configuration consists of the following two system properties. The user should set the properties carefully by keeping performance and safety in mind.

JEUS transaction manager joins the transaction resources of the same resource manager. This allows tasks to be performed without creating additional transaction branches and decreases the overhead. However, this method can be a problem in situations such as when Oracle OCI is used like RAC.

To prepare for such problems, set the following option to "true".

-Djeus.tm.disableJoin=true

The client transaction manager is initialized when the client application performs a JNDI lookup. However, depending on the client application, there are situations when the transaction manager is not used. To remove any additional overhead that occurs in such situation, the following information is saved in the start script.

-Djeus.tm.not_use=true

The client transaction manager is only used in the client container. By default, the transaction manager is used in the client, but to use the server transaction manager in the client, add the following setting to the client application script. For information about the difference between the server transaction manager and client transaction manager, refer to

"7.1.2. JEUS Transaction Manager".

-Djeus.tm.version=server

The client transaction manager uses the TCP/IP port to communicate with other transaction managers.

The client transaction manager automatically finds and uses the appropriate port. To manually set the configuration, add the following setting to the client application script.

-Djeus.tm.port=<port number>

The worker thread pool setting configures the worker thread pool information.

The following describes how to configure the transaction manager from a client.

Using a local transaction is an effective way to manage the transaction tasks of a single resource manager. Since a local transaction is light and fast, it is used whenever possible. The local transaction has nothing to do with JEUS transaction manager and can use all types of containers.

The following is an example of using a local transaction. Although it is a Java application, some of the code can be used in other Java EE programs such as a servlet or EJB.

import javax.naming.*;
import javax.rmi.PortableRemoteObject;
import java.util.*;
import javax.transaction.UserTransaction;
import java.sql.*;
import javax.sql.*;

public class Client {
    private static Connection con;

    private static Connection getConnection() throws
                              NamingException, SQLException {
         // get a JDBC connection
    }

    private static String insertCustomer(String id, String name,
             String phone) throws NamingException, SQLException {
        // insert a product entity given by the arguments to DB
    }

    private static void deleteCustomer(String id) throws
                              NamingException, SQLException {
        // delete a product entity given by the arguments from DB

    }
 
    public static void main(String[] args) {
        try {
          // get a JDBC connection
          con = getConnection();

          // set the autocommit attribute as false
          con.setAutoCommit(false);

          // insert customers
          for (int i=0 ; i<number/2 ; i++) {
              System.out.println("inserting customer id="+i+"c... from Client");
              customers[i] =
                  insertCustomer(i+"c", "Hong Kil Dong "+i, "000-123-1234-"+i);
          }
          System.out.println("completed inserting customers!!");
          con.commit();

          // delete customers
          for (int i=0 ; i<number/2 ; i++) {
             System.out.println(
                 "deleting customerid="+customers[i]+" ... from Client");
             deleteCustomer(customers[i]);
          }
          System.out.println("completed deleting customers!!");
          con.commit();

       } catch (NamingException ne) {
          System.out.println("Naming Exception caught : " + ne.getMessage());
       } catch (SQLException sqle) {
          System.out.println("SQL Exception caught : " + sqle.getMessage());
       } catch(Exception e) {
          try {
             con.rollback();
          } catch (Exception ee) {
             System.out.println("Transaction Rollback error : " + ee.getMessage());
          }
          System.out.println("Error caught : " + e.getMessage());
          e.printStackTrace();
      } finally {
         try {
             if (con!=null) con.close();
         } catch (SQLException se) {}
      }
   }
}

A global transaction can be used in an application of a client container (client managed transaction). The client itself manages transactions by using UserTransaction and calls EJB to process the actual task.

The following is an example of this.

Client

Before starting a global transaction, import a javax.transaction.UserTransaction instance by looking up 'java:comp/UserTransaction'. After starting a global transaction by calling 'begin' on the instance, call the EJB bean multiple times. To commit the transaction task on the EJB Bean, call the commit method of the UserTransaction instance to notify that the transaction is complete.

The method terminates if the transaction is successfully committed. If the global transaction is not committed due to a failure, then an exception is thrown in the method. The javax.transaction.RollbackException is thrown by JEUS transaction manager to guarantee that the global transaction is rolled back. There are also other exceptions that are thrown to notify that JEUS transaction manager is attempting to rollback the global transaction due to an unexpected exception. However, not all transaction tasks of the global transaction are completely rolled back. The rollback method of the UserTransaction instance is called directly from the catch query to roll back the global transaction.

package umt;

import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.rmi.PortableRemoteObject;
import java.util.*;
import javax.transaction.UserTransaction;

public class Client {
 public static void main(String[] args) {
   UserTransaction tx = null;
   try {
       InitialContext initial = new InitialContext();
       ProductManager productManager =
           (ProductManager)initial.lookup("productmanager");
       System.out.println("");
       System.out.println("< Testing ProductManager EJBBean " +
               "Using User Managed Transaction >>");
       System.out.println("");
       int number = 10;
       String products[] = new String[number];
       tx = (UserTransaction)initial.lookup("java:comp/UserTransaction");
       tx.begin();
       // insert products
       for (int i=0 ; i<number/2 ; i++) {
            System.out.println("inserting product id="+i+"b...");
           // bean call
            products[i] = productManager.insertProduct(i+"b","ball pen", i*10); 
        }
        for (int i=number/2 ; i<number ; i++) {
            System.out.println("inserting product id="+i+"f...");
            products[i] = productManager.insertProduct(i+"f", "fountain pen", (i-number/3)*50);
        }
        System.out.println("completed inserting products!!");
        // delete products
        for (int i=0 ; i<number ; i++) {
           System.out.println("deleting productid="+products[i]+" ...");
           productManager.deleteProduct(products[i]); // bean call
        }
       System.out.println("completed deleting products!!");
       tx.commit();
   } catch (javax.transaction.SystemException se) {
      System.out.println("Transaction System Error caught : " + se.getMessage());
   } catch (javax.transaction.RollbackException re) {
      System.out.println("Transaction Rollback Errorcaught : " + re.getMessage());
   } catch(Exception e) {
      try {
           tx.rollback();
      } catch (Exception ee) {
          System.out.println("Transaction Rollback error : " + ee.getMessage());
      }
            System.out.println("Error caught : " + e.getMessage());
            e.printStackTrace();
      }
  }
 }
}

package umt;

import javax.ejb.*;
import javax.annotation.*;

@Stateless
@TransactionManagement(TransactionManagementType.CONTAINER) 
public class ProductManagerEJB implements ProductManager {
    ....

    public String insertProduct(String id, String name, double price) {
        // insert a product entity given by the arguments to DB
    }

    public void deleteProduct(String id) {
        // delete a product entity indicated by the argument from
        // DB
    }
    .....
}

A bean managed transaction uses JTA in an application of a web container and EJB container to explicitly mark the boundaries of a global transaction. It is useful when the application needs to fine-tune the global transaction. The application can decide to rollback and commit on its own since client requests can be processed according to the execution order.

The following is an example of an application executing a global transaction in the EJB container.

Client

In a BMT (Bean-Managed Transaction), an EJB bean processes the global transaction area. Hence, a client simply needs to call the method that performs the transaction tasks.

package bmt;

import javax.naming.*;
import javax.rmi.PortableRemoteObject;
import java.util.*;

public class Client {
    public static void main(String[] args) {
        try {
            ProductManager productManager;
            .......
            // Getting a reference to an instance of
            // ProductManager EJB bean.
            .......
            productManager.transactionTest();
        } catch(Exception e) {
           e.printStackTrace();
        }
    }
}

EJB

An EJB bean uses javax.transaction.UserTransaction to start a global transaction. It uses javax.ejb.EJBContext (since EJB is a Session Bean in this example, javax.ejb.SessionContext is used) to get a UserTransaction instance. The global transaction begins and commits through a method call.

For an EJB to run as a bean managed transaction, the TransactionManagement must be set to 'TransactionManagementType.BEAN' using an annotation.

package bmt;

import javax.ejb.*;
import javax.naming.*;
import java.sql.*;
import java.util.*;
import javax.annotation.*;
import javax.transaction.UserTransaction;

@Stateless
@TransactionManagement(TransactionManagementType.BEAN) 
public class ProductManagerEJB implements ProductManager {
    @Resource SessionContext ejbContext;   

    public void transactionTest() {
        UserTransaction tx = null;
        try {
          int number = 20;
          String products[] = new String[number];
          tx = ejbContext.getUserTransaction();
          tx.begin();
          // insert products
          for (int i=0 ; i<number/2 ; i++) {
               System.out.println("inserting product id="+i+"b ...");
               products[i] = insertProduct(i+"b", "ball pen", i*10);
           }
           for (int i=number/2 ; i<number ; i++) {
               System.out.println("inserting product id="+i+"f...");
               products[i] = insertProduct(
                       i+"f", "fountain pen", (i-number/3)*50);
           }
           System.out.println("completed inserting products!!");
            // delete products
           for (int i=0 ; i<number ; i++) {
               System.out.println("deleting product id="+products[i]+" ...");
               deleteProduct(products[i]);
           }
           System.out.println("completed deleting products!!");
           tx.commit();
        } catch (javax.transaction.SystemException se) {
            throw new EJBException(
                "Transaction System Error caught : " + se.getMessage());
        } catch (javax.transaction.RollbackException re) {
            throw new EJBException(
                "Transaction Rollback Error caught : " + re.getMessage());
        } catch(Exception e) {
           try {
              tx.rollback();
           } catch (Exception ee) {
              throw new EJBException(
                  "Transaction Rollback error : " + ee.getMessage());
           }
           throw new EJBException("Error caught : " + e.getMessage());
        }
    }

    private String insertProduct(String id, String name, double price) 
        throws NamingException, SQLException {
        // insert a product entity given by the arguments to DB
    }

    private void deleteProduct(String id) throws NamingException,
                                                 SQLException {
        // delete a product entity indicated by the argument from
        // DB
    }
    // some EJB callback methods
}

According to the Java EE specification, an application can delegate the demarcation of a global transaction to a container. A Web or EJB container manages the global transactions related to the method. An application can configure the transaction attributes for each method in the configuration file. This is the easiest way to process a global transaction.

The following is an example of a global transaction managed by an EJB container.

Client

In the following example, a server-side EJB container is managing the global transaction tasks of the EJB in a container managed transaction.

package bmt;

import javax.naming.*;
import javax.rmi.PortableRemoteObject;
import java.util.*;

public class Client {
    public static void main(String[] args) {
        try {
            ProductManager productManager;
            // getting a reference to an instance of
            // ProductManager EJB bean.
            productManager.transactionTest();
        } catch(Exception e) {
            e.printStackTrace();
        }
    }
}

EJB

The advantage of using a container-managed transaction is that it prevents the developer from implementing transaction-related codes in the business logic.

As long as appropriate attributes are set in the method of an EJB bean, global transaction related tasks are all delegated to the EJB container. In the following example, the transactionTest method does not contain any transaction related codes. To notify the EJB container to run the EJB Bean as a container managed transaction, either set the TransactionManagement Annotation to TransactionManagerType.CONTAINER or don't set it to anything.

package cmt;

import javax.ejb.*;
import javax.naming.*;
import java.sql.*;
import java.util.*;
import javax.annotation.*;

@Stateless
@TransactionManagement(TransactionManagementType.CONTAINER) 
public class ProductManagerEJB implements ProductManager {
    public void transactionTest() {
      try {
          int number = 20;
          String products[] = new String[number];
          // insert products
          for (int i=0 ; i<number/2 ; i++) {
              System.out.println("inserting product id="+i+"b...");
              products[i] = insertProduct(i+"b", "ball pen", i*10);
          }
          for (int i=number/2 ; i<number ; i++) {
          System.out.println("inserting product id="+i+"f...");
          products[i] = insertProduct(i+"f", "fountain pen", (i-number/3)*50);
      }
      System.out.println("completed inserting products!!");
      // delete products
      for (int i=0 ; i<number ; i++) {
        System.out.println("deleting product id="+products[i]+" ...");
        deleteProduct(products[i]);
      }
      System.out.println("completed deleting products!!");
     } catch(Exception e) {
       throw new EJBException("Error caught : " +  e.getMessage());
     }
  }

    private String insertProduct(String id, String name, double price) 
        throws NamingException, SQLException {
        // insert a product entity given by the arguments to DB
    }

    private void deleteProduct(String id) throws NamingException,
                                                 SQLException {
        // delete a product entity indicated by the argument from
        // DB
    }

    // some EJB callback methods
}

A transaction manager can be obtained by looking up the name of java:appserver/TransactionManager from the JNDI Context. A transaction manager can start and end a transaction and provide the function that registers an XAResource or gets a transaction object. For more information, refer to Java Transaction API (JTA) specification.

A transaction manager must have a recovery plan for failures that can happen during a transaction. The recovery plan is focused on guaranteeing the integrity of the transactions that were in progress. The recovery plan varies depending on whether the manager is the root coordinator or the sub coordinator, and whether tasks are performed with an external task manager instead of JEUS.

The following shows the recovery process of a transaction manager.

[Figure 7.5] Simplified Transaction Recovery Process

The recovery method differs slightly according to the transaction manager's role, but overall it follows the aforementioned process. A brief description of each element that participates in the recovery and related configurations are described next.

The Recovery Process by Transaction Manager Type

The transaction manager plays a central role in the transaction recovery. The following describes how the recovery method differs according to the role of the transaction manager.

Automatic Transaction Recovery

In an automatic transaction recovery, if the current transaction manager shuts down abnormally in a cluster environment, another server's transaction manager automatically recovers any "indoubt" transactions. To properly execute this function, servers must be in a cluster configuration and the server that is executing the recovery must be able to access the transaction log of the failed server.

The following describes the process of configuring the automatic transaction recovery by using WebAdmin or the console tool. This configuration is applied dynamically without restarting the server.

The following are the two types of log files that are used to recover transactions.

The log file is created in a sub directory of 'SERVER_HOME/workspace/mlog' by default. For the path of SERVER_HOME, refer to "1.5. Directory Structure". The log file path can be changed as described in the following.

For example, a public directory can be designated if it is preferable to save a log to a location where many servers can access for automatic recovery. Back up the log and then restart JEUS if a recovery related problem occurs during operation due to a transaction that doesn't need recovery.

The following describes the process of configuring recovery related log files using WebAdmin or the console tool.

Recovery related configurations are listed in this section. They must be added to the server's JVM configuration as system properties. For information about how to add each configuration, refer to ????.

Recovery logging can be blocked for when the system administrator is executing recovery or when performance improvement is needed.

-Djeus.tm.noLogging=true

If recovery fails due to a problem, then the transaction manager will attempt to recover the resource again. Recovery executes once every two minutes, and the user can designate the retry count.

Add the following property to the script to set the retry count. (Default Value: 30)

-Djeus.tm.recoveryTrial=<number of trial>

If there is a transaction that needs to be recovered when a server starts, recovery is performed before the server goes into STANDBY. If there's a failed resource during recovery, then recovery is reattempted in the background.

The retry interval can be configured. (Default Value: (120000) 2min)

-Djeus.tm.recoveryInterval=<time in milliseconds>

JEUS cannot boot if a TM log file is deleted and cannot be recovered. If recovery is not needed, JEUS detects the broken file and resets and deletes all TM log files for a successful startup. (Default Value: false)

-Djeus.tm.ignore.broken.log.file=<true or false>

When the resource manager fails, the system manager uses the console tool to manually perform recovery. This is because JEUS transaction manager cannot find out whether the resource manager is again in a state where it can perform transaction processing.

After resolving the problem with the resource manager, recovery is proceeded by executing the recover-transactions command in the console tool. For more information about using the console tool, refer to JEUS Reference Book. "4.2.13.2. recover-transactions".