![]() |
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 Java (tm) System Application Server 7.This sample application document contains the following sections:
Overview
Compiling and Assembling the Application
Deploying the Sample Application
Overview
In this section, the Global Container-Managed Transaction sample application is described.The global transaction involves the following steps:
Transfer Amount is withdrawn from the Source Account in the Local Bank data source.
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.
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.
- 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.
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
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 Java (tm) System Application Server installation process.Database Server for a Local Bank database
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:
Input Field
Description
The Account Number of the Source Account from which the funds should be withdrawn.
The Account Number of the Recipient Account to which the funds should be deposited.
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:
Get the account balance of the Source Account and Recipient Account.
The results of the transaction are displayed in an HTML form similar to the one shown in Figure 2.Withdraw the transfer amount from the Source Account.
Deposit the transfer amount to the Recipient Account.
Get the new account balance of the Source Account and Recipient Account.
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.
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:
Get the account balance for the Source Account and the Recipient Account.
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.Withdraw the transfer amount from the Source Account by deducting the amount from its balance
Deposit the transfer amount to the Recipient Account by adding the amount to its balance.
- If the Source Account is from a Local Bank, LocalBankAccount.withdraw( amount ) is invoked. Otherwise, ForeignBankAccount.withdraw( amount ) is executed.
Get the updated balance of the Source Account.
- If the Recipient Account is from a Local Bank, LocalBankAccount.deposit( amount ) is invoked. Otherwise, ForeignBankAccount.deposit( amount ) is executed.
- 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.
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:
Go to the src directory of the sample. For example:
Execute asant
To clean the application project area, execute asant clean
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:
Go to <install_dir>/pointbase directory
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:Execute the following command:
Execute the following command:
Open up the file StartServer.sh and change the port number to 8000. For example:
Start the server by executing the StartServer.sh script.
Execute the following command in the same pointbase/server2 directory:
You have now sucessfully created the database.
- 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
<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>
You now have to populate this database with the relevant data. To do so, execute the following steps:
Start the PointBase Server1 (if not started already) by executing the following command:
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:<install_dir>/pointbase/server/StartServer.sh
Go to <install_dir>/samples/transactions/ejb/cmt/src directory.
Execute the command asant sql. This will populate the two databases.
Restart the Sun Java (tm) System Application Server.
<target name="sql" depends="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"/>
Deploying the Sample Application
The deployment process includes deploying the application EAR, configuring database and registering required resources to the Sun Java (tm) System 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 Java (tm) System 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.
Go to the bin directory of your application server installation. For example:
You are now ready to exercise the application. Follow the instructions provided in Running the Sample Application.Execute asadmin to deploy the module to the local application server instance. For example:
Execute the following command:
Commit the changes. For example:
- asadmin deploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> transactions-globalcmt.ear
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.
If you would like to verify the registration of the application, proceed to Verifying Registration.The EAR file is transferred to the administrative server.
The administrative server begins the registration process:
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 Java (tm) System 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
Login to web-based administration tool from browser.
Click on the Deploy icon.
Use Browse button to locate the transactions-globalcmt.ear file and then click the OK button.
Type in product in "App Name" and then click OK.
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.
Start the application by accessing the following URL:
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
- The Foreign Bank Accounts are listed in Table 3.
Table 3    Foreign Bank Accounts
Foreign Bank Account ID
Initial Balance
Enter a value for Transfer Amount.
Click on Transfer Funds to execute the transaction.
- This must be a value that is not less than 0 and not more than the Account's Maximum Withdrawal Amount.
Troubleshooting
When running the application, the following error conditions, listed in Table 4, could occur and cause the transaction to roll back:
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 Java (tm) System 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