The XA Bankapp Sample Application

 

This topic includes the following sections:

• How the XA Bankapp Sample Application Works

• Development Process for the XA Bankapp Sample Application

• Setting Up the Database for the XA Bankapp Sample Application

• Building the XA Bankapp Sample Application

• Compiling the Client and Server Applications

• Initializing the Oracle Database

• Starting the Server Application in the XA Bankapp Sample Application

• Files Generated by the XA Bankapp Sample Application

• Starting the ATM Client Application in the XA Bankapp Sample Application

• Stopping the XA Bankapp Sample Application

• Using the ATM Client Application

For troubleshooting information and the most recent information about using the XA Bankapp sample application, see the Readme.txt file in the \WLEdir\samples\corba\bankapp_java\XA directory.

 

---

How the XA Bankapp Sample Application Works

The XA Bankapp sample application is a CORBA application that implements the same automatic teller machine (ATM) interface as the JDBC Bankapp sample application. However, the XA Bankapp sample application uses the Oracle XA library and the WebLogic Enterprise Transaction Manager to coordinate transactions between the WebLogic Enterprise application and the Oracle database that stores account and customer information.

This topic includes the following sections:

• Server Applications

• Application Workflow

Server Applications

The XA Bankapp sample application consists of two server applications:

• A Java server application, which implements the TellerFactory and Teller objects.

• A C++ server application, which processes requests on objects that implement the DBAccesss interface.

Application Workflow

Figure 4-1 illustrates how the XA Bankapp sample application works.

Figure 4-1 The XA Bankapp Sample Application

In the XA Bankapp sample application, transactions are started and stopped in the Teller object using the Java Transaction Service (JTS) API. In the JDBC Bankapp sample application, transactions are started and stopped in the DBAccess object using the Java Database Connectivity (JDBC) API.

In the XA Bankapp sample application, the DBAccess object is implemented in C++ instead of Java and resides in its own server application. The object reference for the DBAccess object is generated in its Server::initialize method and is registered with the FactoryFinder environmental object.

Software Prerequisites

To run the XA Bankapp sample application, you need to install the following software:

• Visual C++

• Oracle

 

---

Development Process for the XA Bankapp Sample Application

This topic includes the following sections:

• Object Management Group (OMG) Interface Definition Language (IDL)

• Client Application

• Server Application

• Server Description File

• Implementation Configuration File

• UBBCONFIG File

These sections describe the development process for the XA Bankapp sample application.

Note: The steps in this section have been done for you and are included in the XA Bankapp sample application.

Object Management Group (OMG) Interface Definition Language (IDL)

The BankApp.idl file used in the XA Bankapp sample application defines the TellerFactory and Teller interfaces and the Bank.idl file defines exceptions and structures. The transfer_funds interface has been removed from the BankDB.idl because transactions are now started and stopped by the Teller object.

Client Application

The XA Bankapp sample application uses the same client application as the JDBC Bankapp sample application.

Server Application

For the XA Bankapp sample application, you would write a Java Server object, which initializes the Java server application in the XA Bankapp sample application and registers a factory for the Teller object with the WebLogic Enterprise domain.

Server Description File

During development, you create a Server Description File (BankApp.xml) that defines the activation and transaction policies for the TellerFactory and Teller objects. Table 4-1 shows the activation and transaction policies for the XA Bankapp sample application.

Table 4-1 Activation and Transaction Policies for XA Bankapp Sample Application

Interface	Activation Policy	Transaction Policy
TellerFactory	Process	Never
Teller	Method	Never

A Server Description File for the XA Bankapp sample application is provided. For information about creating Server Description Files and defining activation and transaction policies on objects, see Creating Java Server Applications.

Implementation Configuration File

When writing WebLogic Enterprise C++ server applications, you create an Implementation Configuration File (ICF), which is similar to the Server Description File. This file has been created for you and defines an activation policy of transaction and a transaction policy of always for the DBAccess interface.

For information about creating ICF files and defining activation and transaction policies on objects, see Creating C++ Server Applications.

UBBCONFIG File

During development, you need to include the following information in the UBBCONFIG file:

• The OPENINFO parameter, defined according to the XA parameter for the Oracle database. The XA parameter for the Oracle database is described the "Developing and Installing Applications that Use the XA Libraries" section of the Oracle7 Distributed Systems manual.

• The pathname to the transaction log (TLOG) in the TLOGDEVICE parameter.

For information about the transaction log and defining parameters in the UBBCONFIG file, see Using Transactions.

 

---

Setting Up the Database for the XA Bankapp Sample Application

The XA Bankapp sample application uses an Oracle database to store all the bank data. Before using the XA Bankapp sample application, you need to install the following Oracle components:

• Oracle Server

• Pro*C/C++ (for more information about supported compilers, see the Oracle product documentation)

  Note: When installing the specified Oracle components, other Oracle components are also installed. However, you will not use these additional components with the XA Bankapp sample application.

You also need to start the Oracle database daemon and enable an XA resource manager.

For information about installing the Oracle database and performing the necessary setup tasks, see the product documentation for the Oracle database.

 

---

Building the XA Bankapp Sample Application

This topic includes the following sections:

• Step 1: Copy the Files for the XA Bankapp Sample Application into a Work Directory

• Step 2: Change the Protection Attribute on the Files for the XA Bankapp Sample Application

• Step 3: Verify the Settings of the Environment Variables

• Step 4: Run the setupX Command

• Step 5: Load the UBBCONFIG File

• Step 6: Create a Transaction Log

These sections describe how to build the XA Bankapp sample application.

Step 1: Copy the Files for the XA Bankapp Sample Application into a Work Directory

You need to copy the files for the XA Bankapp sample application into a work directory on your local machine.

Source File Directories

The files for the XA Bankapp sample application are located in the following directories:

Windows NT

drive:\WLEdir\samples\corba\bankapp_java\XA

drive:\WLEdir\samples\corba\bankapp_java\client

drive:\WLEdir\samples\corba\bankapp_java\shared

UNIX

/usr/local/WLEdir/samples/corba/bankapp_java/XA

/usr/local/WLEdir/samples/corba/bankapp_java/client

/usr/local/WLEdir/samples/corba/bankapp_java/shared

Table 4-2 describes the contents of these directories:

Table 4-2 Source File Directories in the XA Bankapp Sample Application

Directory	Description
XA	Source files and commands needed to build and run the XA Bankapp sample application.
client	Files for the ATM client application. The images subdirectory contains .gif files used by the graphical user interface in the ATM client application.
shared	Common files for the JDBC Bankapp and XA Bankapp sample applications.

Copying Source Files to the Work Directory

You need only to copy the files manually in the XA directory. The other files are automatically copied from the \client and \shared directories when you execute the setupX command. For example:

Windows NT

prompt> cd c:\mysamples\bankapp_xa\XA

prompt> copy c:\WLEdir\samples\corba\bankapp_xa\XA\*

UNIX

ksh prompt> cd /usr/mysamples/bankapp_xa/XA/*

ksh prompt> cp $TUXDIR/samples/bankapp_xa/XA/*

Note: You cannot run the XA Bankapp sample application in the same work directory as the JDBC Bankapp sample application, because some of the files for the JDBC Bankapp sample application have the same name as files for the XA Bankapp sample application.

Source Files Used to Build the XA Bankapp Sample Application

Table 4-3 lists the files used to build and run the XA Bankapp sample application.

Table 4-3 Files Included in the XA Bankapp Sample Application

File	Description
Bank.idl	The OMG IDL code that declares common structures and extensions for the XA Bankapp sample application.
BankApp.idl	The OMG IDL code that declares the TellerFactory and Teller interfaces.
BankDB.idl	The OMG IDL code that declares the DBAccess interface.
BankDB.icf	The ICF file that defines activation and transaction policies for the DBAccess interface.
BankDBServer.cpp	The C++ source code that implements the Server::initialize and Server::release methods for the C++ server application.
TellerFactoryImpl.java	The Java source code that implements the createTeller method.
TellerImpl.java	The Java source code that implements the verify, deposit, withdraw, inquiry, transfer, and report methods. In addition, it includes a reference to the TransactionCurrent environmental object and invokes operations on the DBAccess object within a transaction.
BankAppServerImpl.java	The Java source code that overrides the Server.initialize and Server.release methods.
Atm.java	The Java source code for the ATM client application.
BankStats.java	Contains methods to initialize, read from, and write to the flat file that contains the ATM statistics.
BankApp.xml	The Server Description File used to associate activation and transaction policy values with CORBA interfaces.
DBAccess_i.h DBAccess_i.pc	The Oracle Pro*C/C++ code that implements the DBAccess interface.
InitDB.sql	The Oracle SQL *Plus script that creates and populates the database tables.
setupX.cmd	The Windows NT batch file that builds and runs the XA Bankapp sample application.
setupX.ksh	The UNIX Korn shell script that builds and runs the XA Bankapp sample application.
makefileX.mk	The make file for the XA Bankapp sample application on the UNIX operating system. The UNIX make command needs to be in the path of your machine.
makefileX.nt	The make file for the XA Bankapp sample application on the Windows NT operating system. The Windows NT nmake command needs to be in the path of your machine.
Readme.txt	Provides the latest information about building and running the XA Bankapp sample application.

Step 2: Change the Protection Attribute on the Files for the XA Bankapp Sample Application

During the installation of the WebLogic Enterprise software, the files for the XA Bankapp sample application are marked read-only. Before you can edit or build the files in the XA Bankapp sample application, you need to change the protection attribute of the files you copied into your work directory, as follows:

Windows NT

prompt>attrib -r drive:\workdirectory\*.*

UNIX

prompt>/bin/ksh

ksh prompt>chmod u+w /workdirectory/*.*

Step 3: Verify the Settings of the Environment Variables

Before building and running the XA Bankapp sample application, you need to ensure that certain environment variables are set on your system. In most cases, these environment variables are set as part of the installation procedure. However, you need to check the environment variables to ensure they reflect correct information.

Environment Variables

Table 4-4 lists the environment variables required to run the XA Bankapp sample application.

Table 4-4 Required Environment Variables for the XA Bankapp Sample Application

Environment Variable	Description
TUXDIR	The directory path where you installed the WebLogic Enterprise software. For example: Windows NT TUXDIR=c:\WLEdir UNIX TUXDIR=/usr/local/WLEdir
JAVA_HOME	The directory path where you installed the JDK software. For example: Windows NT JAVA_HOME=c:\JDK1.2 UNIX JAVA_HOME=/usr/local/JDK1.2
ORACLE_HOME	The directory path where you installed the Oracle software. For example: ORACLE_HOME=/usr/local/oracle You need to set this environment variable on the Solaris operating system only.

Verifying Settings

To verify that the information defined during installation is correct:

Windows NT

1. From the Start menu, select Settings.

2. From the Settings menu, select the Control Panel.

   The Control Panel appears.

3. Click the System icon.

   The System Properties window appears.

4. Click the Environment tab.

   The Environment page appears.

5. Check the settings for TUXDIR, ORACLE_HOME, and JAVA_HOME.

UNIX

ksh prompt>printenv TUXDIR

ksh prompt>printenv JAVA_HOME

ksh prompt>printenv ORACLE_HOME

Changing Settings

To change the settings:

Windows NT

1. On the Environment page in the System Properties window, click the environment variable you want to change or enter the name of the environment variable in the Variable field.

2. Enter the correct information for the environment variable in the Value field.

3. Click OK to save the changes.

UNIX

ksh prompt>TUXDIR=directorypath; export TUXDIR

ksh prompt>JAVA_HOME=directorypath; export JAVA_HOME

ksh prompt>JAVA_HOME=directorypath; export ORACLE_HOME

Note: If you are running multiple WebLogic Enterprise applications concurrently on the same machine, you also need to set the IPCKEY and PORT environment variables. See the Readme.txt file for information about how to set these environment variables.

Step 4: Run the setupX Command

The setupX command automates the following steps:

1. Copy the required files from the \client and \shared directories.

2. Set the PATH, TOBJADDR, APPDIR, TUXCONFIG, and CLASSPATH system environment variables.

3. Create the UBBCONFIG file.

4. Create a setenvX.cmd or setenvX.ksh file that can be used to reset the system environment variables.

Enter the setupX command, as follows:

Windows NT

prompt> cd c:\mysamples\bankapp_xa\XA

prompt>setupX

UNIX

prompt>/bin/ksh

prompt> cd /usr/mysamples/bankapp_xa/XA/*

prompt>. ./setupX.ksh

Step 5: Load the UBBCONFIG File

Use the following command to load the UBBCONFIG file:

prompt>tmloadcf -y ubb_xa

Step 6: Create a Transaction Log

The transaction log records the transaction activities in a WebLogic Enterprise session. During the development process, you need to define the location of the transaction log (specified by the TLOGDEVICE parameter) in the UBBCONFIG file. For the XA Bankapp sample application, the transaction log is placed in your work directory.

To open the transaction log for the XA Bankapp sample application:

1. Enter the following command to start the Interactive Administrative Interface:

   tmadmin

2. Enter the following command to create a transaction log:

   crdl -b blocks -z directorypath TLOG
   crlog -m SITE1

   where

   blocks specifies the number of blocks to be allocated for the transaction log and directorypath indicates the location of the transaction log. The directorypath option needs to match the location specified in the TLOGDEVICE parameter in the UBBCONFIG file. The following is an example of the command on Windows NT:

   crdl -b 500 -z c:\mysamples\bankapp_java\XA\TLOG

3. Enter quit to exit the Interactive Administrative Interface.

 

---

Compiling the Client and Server Applications

The directory for the XA Bankapp sample application contains a make file that builds the client and server applications. During the development process, you use the buildjavaserver command to build the server application, and your Java product's development commands to build the client application. However, for the XA Bankapp sample application, this step is included in the make file.

Use the following commands to build the client and server applications in the XA Bankapp sample application:

Windows NT

prompt>nmake -f makefileX.nt

UNIX

prompt>make -f makefileX.mk

 

---

Initializing the Oracle Database

Use the following command to initialize the Oracle database used with the XA Bankapp sample application:

Windows NT

prompt>nmake -f makefileX.nt InitDB

UNIX

ksh prompt>make -f makefileX.mk InitDB

 

---

Starting the Server Application in the XA Bankapp Sample Application

Start the server application in the XA Bankapp sample application by entering the following command:

prompt>tmboot -y

The tmboot command starts the application processes listed in Table 4-5.

Table 4-5 Application Processes Started by tmboot Command

Process	Description
TMSYSEVT	BEA Tuxedo system event broker.
TMFFNAME	Three TMFFNAME server processes are started: The TMFFNAME server process with the -N and -M options is the master NameManager service. The NameManager service maintains a mapping of the application-supplied names to object references. The TMFFNAME server process started with the -N option only is the slave NameManager service. The TMFFNAME server process started with the -F option contains the FactoryFinder object.
TMS_ORA	Transaction manager service.
BankDataBase	WebLogic Enterprise server process that implements the DBAccess interface.
JavaServerXA	Server process that implements the TellerFactory and Teller interfaces. The JavaServer process has two options: BankApp.jar, which is the Java Archive (JAR) file that was created by the buildjavaserver command. TellerFactory_1, which is passed to the Server.initialize method. JavaServerXA is a special version of JavaServer that uses the same XA switch as the BankDataBase server process. It is created by the buildXAJS command.
ISL	IIOP Listener process.

Note: The JavaServer will not start on Microsoft Windows NT if JDK bin is in the path after the network drive. Make sure the JDK bin directories (that is, jre/bin and jre/bin/classic) are set in the PATH before any network driver path elements via the Control Panel before booting the JavaServer.

 

---

Files Generated by the XA Bankapp Sample Application

Table 4-6 lists the files generated by the XA Bankapp sample application.

Table 4-6 Files Generated by the XA Bankapp Sample Application

File	Description
ubb_xa	The UBBCONFIG file for the XA Bankapp sample application. This file is generated by the setupX command.
setenvX.cmd and setenvX.ksh	Contains the commands to set the environment variables needed to build and run the XA Bankapp sample application. setenvX.cmd is the Windows NT version and setenvX.ksh is the UNIX Korn shell version of the file.
tuxconfig	A binary version of the UBBCONFIG file. Generated by the tmloadcf command.
TLOG	The transaction log.
ULOG.<date>	A log file that contains messages generated by the tmboot command. The log file also contains messages generated by the server applications and the tmshutdown command.
.adm/.keybd	A file that contains the security encryption key database. The subdirectory is created by the tmloadcf command.
Atm$1.class Atm.class AtmAppletStub.class AtmArrow.class AtmButton.class AtmCenterTextCanvas.class AtmClock.class AtmScreen.class AtmServices.class AtmStatus.class	Used by the Java client application. Created when the Atm.java file is compiled.
AccountRecordNotFound.java AccountRecordNotFoundHelper.java AccountRecordNotFoundHolder.java CustAccounts.java CustAccountsHelper.java CustAccountsHolder.java DataBaseException.java DataBaseExceptionHelper.java DataBaseExceptionHolder.java InsufficientFunds.java InsufficientFundsHelper.java InsufficientFundsHolder.java PinNumberNotFound.java PinNumberNotFoundHelper.java PinNumberNotFoundHolder.java	Generated by the m3idltojava command for the interfaces defined in the Bank.idl file. These files are created in the \com\beasys\samples\Bank subdirectory.
BalanceAmounts.java BalanceAmountsHelper.java BalanceAmountsHolder.java IOException.java IOExceptionHelper.java IOExceptionHolder.java Teller.java TellerActivity.java TellerActivityHelper.java TellerActivityHolder.java TellerFactory.java TellerFactoryHelper.java TellerFactoryHolder.java TellerInsufficientFunds.java TellerInsufficientFundsHelper.java TellerInsufficientFundsHolder.java _TellerFactoryImplBase.java _TellerFactoryStub.java _TellerImplBase.java _TellerStub.java	Generated by the m3idltojava command for the interfaces defined in the BankApp.idl file. These files are created in the \com\beasys\samples\BankApp subdirectory.
AccountData.java AccountDataHelper.java AccountDataHolder.java DBAccessHelper.java DBAccessHolder.java _DBAccessImplBase.java _DBAccessStub.java	Generated by the m3idltojava command for the interfaces defined in the BankDB.idl file. These files are created in the \com\beasys\samples\BankDB subdirectory.
Bankapp.ser Bankapp.jar	The Server Descriptor file and Server Java Archive file generated by the buildjavaserver command in the make file.
Bank_c.cpp Bank_c.h Bank_s.cpp Bank_s.h	Generated by the idl command for the interfaces defined in the Bank.idl file.
BankDB_c.cpp BankDB_c.h BankDB_s.cpp BankDB_s.h	Generated by the idl command for the interfaces defined in the BankDB.idl file.
dbaccess_i.cpp	Generated from the DBAccess_i.pc file by the Oracle Pro*C/C++ compiler.
BankDataBase.exe	The WebLogic Enterprise server application that implements the DBAccess interface.
TMS_ORA.exe	The server process for the Transaction Manager service.
JavaServerXA	The special version of the JavaServer that uses the same XA switches as the BankDataBase server process.
stderr	Generated by the tmboot command. If the -noredirect JavaServer option is specified in the UBBCONFIG file, the System.err.println method sends the output to the stderr file instead of to the ULOG file.
stdout	Generated by the tmboot command. If the -noredirect JavaServer option is specified in the UBBCONFIG file, the System.out.println method sends the output to the stdout file instead of to the ULOG file.
tmsysevt.dat	Contains filtering and notification rules used by the TMSYSEVT (system event reporting) process. This file is generated by the tmboot command.

 

---

Starting the ATM Client Application in the XA Bankapp Sample Application

Start the ATM client application by entering the following command:

Note: The following command sets the Java CLASSPATH to include the current directory and the client JAR file (m3envobj.jar). The full WebLogic Enterprise JAR file (m3.jar) can be specified instead of the client JAR file.

Windows NT

prompt>java -classpath .;%TUXDIR%\udataobj\java\jdk\m3envobj.jar -DTOBJADDR=%TOBJADDR% Atm Teller2

UNIX

ksh prompt>java -classpath .:$TUXDIR/udataobj/java/jdk
/m3envobj.jar -DTOBJADDR=$TOBJADDR Atm Teller2

The GUI for the ATM client application appears.

 

---

Stopping the XA Bankapp Sample Application

Before using another sample application, enter the following commands to stop the XA Bankapp sample application and to remove unnecessary files from the work directory:

Windows NT

prompt>tmshutdown -y

prompt>nmake -f makefileX.nt clean

UNIX

ksh prompt>tmshutdown -y

ksh prompt>make -f makefileX.mk clean

 

---

Using the ATM Client Application

The ATM client application in the XA Bankapp sample application works as it does in the JDBC Bankapp sample application. For instructions, see Using the ATM Client Application.