Sun ONE logo     
Global Container-Managed Transaction Sample Application



Global Container-Managed Transaction Sample Application


This document describes how to utilize the Global Container-Managed Transaction (transactions-globalcmt) sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

In this section, the Global Container-Managed Transaction sample application is described.

The global transaction involves the following steps:

  1. Transfer Amount is withdrawn from the Source Account in the Local Bank data source.

  2. Transfer Amount is deposited to the Recipient Account in the Foreign Bank data source. The Local Bank and Foreign Bank data sources are distinct data sources and could reside in different database servers.

    For example, the Local Bank data source could be an Oracle server while the Foreign Bank data source could be a Sybase server. In this example, both datasources are created in PointBase.

  3. If the resulting balance for the Source Account is not negative, the transaction is committed. Otherwise, the Source Account does not have enough funds to transfer and the transaction is rolled back. When a rollback occurs, both the Source and Recipient Accounts retain their original balances.


In order to successfully deploy and run the transactions-globalcmt sample application, Database resources (PointBase) needs to be setup with the Application Server.

If you want to run this sample on Oracle Database, please refer to (How to run sample applications with Oracle ) . You can also refer to the transactions-globalweb sample for the specific modification of the build.xml .


Global Transaction Resource Requirements

The global transaction sample applications in this package require the following resources:

  • com.pointbase.jdbc.jdbcUniversalDriver

  • Database Server for a Local Bank database

  • Local Bank database

  • Database User transactions

  • Database Server for a Foreign Bank database

  • Foreign Bank database

  • Database User transactions

This document will walk you through all of the necessary steps designed to make this particular application operational. These steps are not included as part of the Sun ONE Application Server installation process.

If you have already completed the deployment process you may proceed to Running the Sample Application.

This sample application illustrates the implementation of a global Container-Managed Transaction (CMT). It demonstrates how a transaction can be performed within an EJB context. The application simulates the transfer of funds from one account to another in which the accounts may come from different banks. The transaction is "global" because it involves multiple data sources: a local bank and a foreign bank.

The first page of the application, seen in Figure 1, is an HTML form that allows the user to enter the information displayed in Table 1:

Table 1   

Input Field

Description

Source Bank  

The bank that is associated with the Source Account.  

Source Account ID  

The Account Number of the Source Account from which the funds should be withdrawn.  

Recipient Bank  

The bank that is associated with the Recipient Account.  

Recipient Account ID  

The Account Number of the Recipient Account to which the funds should be deposited.  

Transfer Amount  

The amount of money to be transferred.  

Figure 1    Global Transaction from Servlet Input Form



When the user clicks the Transfer Funds button, the GlobalCmtServlet is invoked to perform the following transactional process:

  1. Get the account balance of the Source Account and Recipient Account.

  2. Withdraw the transfer amount from the Source Account.

  3. Deposit the transfer amount to the Recipient Account.

  4. Get the new account balance of the Source Account and Recipient Account.

  5. If the Source Account balance is negative, the Source Account does not have enough funds to transfer and an exception is thrown. The exception causes the container to throw a TransactionRolledbackException which rolls back all the database updates that were executed in the transferFunds( ) method. Otherwise, if the Source Account balance is not negative, the Source Account has enough funds to transfer and the container automatically commits the transaction at the end of the transferFunds( ) method.

The results of the transaction are displayed in an HTML form similar to the one shown in Figure 2.

Figure 2    Global Transaction from Servlet Output Form




Architecture and Process Flow

The architecture and process flow diagram is shown in Figure 3.

Figure 3    Global Transaction from JNDI



The GlobalCmtServlet locates the GlobalBankServiceEJB which which performs the following steps in its transferFunds( ) method without explicitly starting a transaction; the transaction is implicitly started by the container when GlobalBankServiceEJB.transferFunds( ) is called:

  1. Get the account balance for the Source Account and the Recipient Account.

  2. Withdraw the transfer amount from the Source Account by deducting the amount from its balance

    If the Source Account is from a Local Bank, LocalBankAccount.withdraw( amount ) is invoked. Otherwise, ForeignBankAccount.withdraw( amount ) is executed.

  3. Deposit the transfer amount to the Recipient Account by adding the amount to its balance.

    If the Recipient Account is from a Local Bank, LocalBankAccount.deposit( amount ) is invoked. Otherwise, ForeignBankAccount.deposit( amount ) is executed.

  4. Get the updated balance of the Source Account.

    If the balance is negative, this means that the Source Account does not have enough funds to transfer. An exception is thrown and the container automatically rolls back the transaction. On the other hand, if the balance is not negative and when no other exception is thrown, the container automatically commits the transaction that it started when the transferFunds( ) method was called.

Container-managed transactions are declared during deployment and they are automatically started, committed and/or rolled-back by the container. In this sample application, a transaction was automatically managed by the container in the transferFunds() method because the transaction attribute for GlobalBankServiceEJB.transferFunds( ) was set to Required during deployment.

To better understand sample application source code, you may refer to the related javadocs which can be accessed at <install_dir>/samples/transactions/ejb/cmt/simple/javadocs/index.html once they are generated by executing the command asant javadocs.



Compiling and Assembling the Application



To compile and assemble the application, follow these steps:

  1. Go to the src directory of the sample. For example:

    cd <install_dir>/samples/transactions/ejb/cmt/simple/src

  2. Execute asant

    The default target core will be executed to build the .jar file.

  3. To clean the application project area, execute asant clean

    This will remove the sample application assemble and build directories. This is required when you want to rebuild the application.


Configuring a second datasource

Since this application requires two different datasources for global transactions, extra steps are required to create a second instance of the PointBase server. Currently, the first datasource has already been created and pre-populated with the required LocalBank information. A second datasource is necessary for the ForeignBank account information.


Note If you have already created and configured a second datasource for the transactions/web/simple or transactions/ejb/bmt/simple application, it is not necessary to complete this procedure.



To configure a second datasource, do the following:

  1. Go to <install_dir>/pointbase directory

  2. Execute the following command:

    cp -r server server2

  3. Execute the following command:

    cd server2

  4. Open up the file StartServer.sh and change the port number to 8000. For example:

    ../../jdk/bin/java -classpath ./lib/pbserver42RE.ja com.pointbase.net.netServer/port:8000

  5. Start the server by executing the StartServer.sh script.

    Leave this window open to keep the server running.

  6. Execute the following command in the same pointbase/server2 directory:

    UNIX: java -cp ../client_tools/lib/pbclient42RE.jar:../client_tools/lib/pbtools42RE.jar com.pointbase.tools.toolsCommander com.pointbase.jdbc.jdbcUniversalDriver jdbc:pointbase://localhost:8000/sun-appserv-samples2,create=force transactions transactions

    W2K: java -cp ..\client_tools\lib\pbclient42RE.jar;..\client_tools\lib\pbtools42RE.jar com.pointbase.tools.toolsCommander com.pointbase.jdbc.jdbcUniversalDriver jdbc:pointbase://localhost:8000/sun-appserv-samples2,create=force transactions transactions

  7. You have now sucessfully created the database.

    Type exit to quit the PointBase Commander tool.

Please note that if you desire to create a database with a different port number, you will need to modify 8000 with your new port number in Step 4 and Step 6. You will also have to modify the build.xml located in the <install_dir>/samples/transactions/web/simple/src directory to reflect the new port number in the set DatabaseName2 section. This entry is displayed below:

<target name="set-DatabaseName2">

<antcall target="admin_command_common">

<param name="admin.command" value="set ${sunone.instance}.jdbc-connection-pool.ForeignPool.property.Databa

seName=jdbc:pointbase:server://localhost:8000/sun-appserv-samples2"/> </antcall>

</target>

You now have to populate this database with the relevant data. To do so, execute the following steps:

  1. Start the PointBase Server1 (if not started already) by executing the following command:

    <install_dir>/pointbase/server/StartServer.sh

  2. Go to <install_dir>/samples/transactions/ejb/cmt/src directory.

  3. Execute the command asant sql. This will populate the two databases.

  4. Restart the Sun ONE Application Server.

Again note that if you are changing the port number of the second database, you will have to change the value in the same build.xml in the target sql. This entry appears below:

<target name="sql" depends="sql_common">

<!-- Datasource #2 -->

<antcall target="sql_common">

<param name="db.file" value="sql/transactions-globalcmt-foreign.sql"/>

<param name="db.url" value="jdbc:pointbase:server://localhost:8000/sun-appserv-samples2"/>

</antcall>

</target>



Deploying the Sample Application



The deployment process includes deploying the application EAR, configuring database and registering required resources to the Sun ONE Application Server. Installation comes with a pre-configured PointBase database. If you choose to use the prepopulated PointBase database, you do not need to configure database.

You may select one of the following methods of deploying and registering the application:

  • Command Line Interface (CLI)-based Deployment describes how to manually register the sample application using a Command Line Interface (CLI). This is the fastest means of deploying the application to the application server.

  • Web Interface (GUI)-based Deployment describes how to use the Sun ONE Deployment Tool to import and deploy the sample application. Alternatively, you can also assemble the application from scratch and deploy it using the Deployment Tool.


Command Line Interface (CLI)-based Deployment

Since the sample application is supplied with a complete EAR file, the fastest means of setting up the application is to use the command line utilities as described in this section. If you would like to experience either deploying through a Web based tool, then follow instructions in Web Interface (GUI)-based Deployment.

There are two command line utilities to deploy the application, Using asant script or Using asadmin command.


Using asant script

  1. Go to the src directory of the sample. For example:

    cd <install_dir>/samples/transactions/ejb/cmt/simple/src

  2. Execute the following command:

    asant deploy


Using asadmin command

  1. Go to the bin directory of your application server installation. For example:

    cd <install_dir>/bin/

  2. Execute asadmin to deploy the module to the local application server instance. For example:

    Go to s1as_install_dir/samples/transactions/ejb/cmt/simple

  3. Execute the following command:

    asadmin deploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> transactions-globalcmt.ear

  4. Commit the changes. For example:

    asadmin reconfig -H <host> -p <Admin Port> -u <user> -w <password> <instancename>

You are now ready to exercise the application. Follow the instructions provided in Running the Sample Application.

The transactions-globalcmt.ear file is an Enterprise Archive (EAR) file that contains the Web Archive (WAR) file for the application. Since this application does not have any EJB's, there is no JAR file involved.

The deployment process involves the following operations:

  • Authenticates against the local application server's administrative server.

  • The EAR file is transferred to the administrative server.

  • The administrative server begins the registration process:

    • Parses the EAR file and embedded WAR file and JAR file

    • Explodes the bits into repository

    • Registers the J2EE application transactions-globalcmt by updating server.xml

If you would like to verify the registration of the application, proceed to Verifying Registration.

Otherwise, you are now ready to exercise the application by Running the Sample Application.


Verifying Registration

As an optional step, you can use the Sun ONE Application Server Administration Tool to verify that the application has been registered. If you do not want to verify that the application has been registered, proceed directly to Running the Sample Application.

To verify the registration of the application, execute asadmin to look at applications deployed with a server instance. For example:

asadmin list-components -u <username> -w <password> -H <host> -p <admin-port> <server instance name>

You will see the transactions-globalcmt as one of the listed applications.


Web Interface (GUI)-based Deployment

  1. Login to web-based administration tool from browser.

  2. Navigate as follows:

    Application Server Instances --> <server instance> --> Applications --> Enterprise Applications

  3. Click on the Deploy icon.

  4. Use Browse button to locate the transactions-globalcmt.ear file and then click the OK button.

  5. Type in product in "App Name" and then click OK.

  6. Verify that the application is deployed by clicking on the product link.



Running the Sample Application

This describes how to start the application, navigate through it and how to troubleshoot in the event of problems.

  1. Start the application by accessing the following URL:

    http://<web server hostname>:<port>/transactions-globalcmt/index.html

  2. Enter a value for Source Bank, Source Account ID, Recipient Bank and Recipient Account ID.

    The Local Bank Accounts are listed in Table 2.


Table 2    Local Bank Accounts

Local Bank Account ID

Initial Balance

Maximum Withdrawal Amount

001  

100  

300  

002  

500  

300  

The Foreign Bank Accounts are listed in Table 3.


Table 3    Foreign Bank Accounts

Foreign Bank Account ID

Initial Balance

1000  

1000  

1001  

5000  

  1. Enter a value for Transfer Amount.

    This must be a value that is not less than 0 and not more than the Account's Maximum Withdrawal Amount.

  2. Click on Transfer Funds to execute the transaction.



Troubleshooting

When running the application, the following error conditions, listed in Table 4, could occur and cause the transaction to roll back:


Table 4    Error Messages, Descriptions and Solutions

Error Message

Description

Solution

Please correct your entries.  

The values entered in the required fields are either blank or contain incorrect values.  

Make sure there is a value for all the required fields. Transfer Amount must be a number greater than 0.  

Account ID X does not exist.  

The value X that was entered for either the Source Account ID or Recipient Account ID is not one of the valid Account ID's listed above.  

Make sure that both Source Account ID and Recipient Account ID are in the list of valid Account ID's shown above.  

Cannot withdraw from Source Account:

Account has insufficient funds.  

The Source Account does not have enough funds to transfer the requested amount to the Recipient Account.  

Reduce the Transfer Amount to be less or equal to the Source Account Balance.  

Cannot withdraw from Source Account: Maximum withdrawal amount is 300.  

The Transfer Amount exceeds the Maximum Withdrawal Amount that was defined for the Source Account. This only happens when the Source Account is from a Local Bank. Foreign Bank Accounts do not have a maximum withdrawal amount.  

Reduce the Transfer Amount to be less or equal to the Account's Maximum Withdrawal Amount.  

  • You may also restore the second databases with the original data by executing asant sql in the <install_dir>/samples/transactions/ejb/cmt/simple/src directory.

  • When using the admin UI to restart the Sun ONE Application Server, it may be necessary to click on 'Apply Changes' then on 'Restart Server'.

  • Please make sure that you run asant undeploy before redeploying this sample. This will ensure that all modules are undeployed and the resources are disabled.



Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated July 26, 2002