The XA Bankapp Sample Application

This chapter discusses the following topics:

• How the XA Bankapp sample application works

• Software prerequisites

• The development process for the XA Bankapp sample application

• Setting up the Oracle 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 applications in the XA Bankapp sample application

• Files generated by the XA Bankapp sample application

• Starting the Automatic Teller Machine (ATM) client application in the XA Bankapp sample application

• Stopping the XA Bankapp sample application

• Using the ATM client application

Refer to the Readme.txt file in the \WLEdir\samples\corba\bankapp_java directory for troubleshooting information and for the most recent information about using the XA Bankapp sample application.

How the XA Bankapp Sample Application Works

The XA Bankapp sample application 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 (WLE) Transaction Manager to coordinate transactions between the WLE application and the Oracle database that stores account and customer information. 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

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) protocol. In JDBC Bankapp, transactions are started and stopped in the DBAccess object using the Java Database Connectivity (JDBC) protocol.

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++ Version 5.0 with Service Pack 3 for Visual Studio

• Oracle Version 7.3.4

The Development Process for the XA Bankapp Sample Application

This section describes 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.

The Client Application

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

The Server Application

For the XA Bankapp sample application, you would write the following:

• The 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 WLE domain.

• The implementation for the methods of the Teller object. The implementation for the Teller object includes invoking operations on the DBAccess object. Because the Teller object has durable state (for example, ATM statistics), which is stored in an external source (a flat file), the method implementations must also include the activate_object() and deactivate_object() methods to ensure the Teller object is initialized with its state.

• The C++ server object which initializes the C++ server and registers the DBAccess object with the WLE domain.

• The implementation for the methods of the DBAccess object.

For information about writing server applications, see Creating Java Server Applications and Creating C++ Server Applications.

The 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. For the XA Bankapp sample application, the objects have the following activation and transaction policies:

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.

The Implementation Configuration File

When writing WLE 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.

The 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 in the "Developing and Installing Applications that Use the XA Libraries" section of the Oracle7 Server 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 the Administration Guide.

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:

• Programmer/2000 Pro*C/C++, Version 2.2.4.0.0

• Oracle 7 Server, Version 7.3.4

  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

To build the XA Bankapp sample application:

1. Copy the files for the XA Bankapp sample application into a work directory.

2. Change the protection attribute on the files for the XA Bankapp sample application.

3. Verify the settings of the environment variables.

4. Run the setupX command.

5. Load the UBBCONFIG file.

6. Create a transaction log.

The following sections describe these steps.

Copying 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. 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

The directories contain the following:

• XA-contains the source files and commands needed to build and run the XA Bankapp sample application.

• client-contains files for the ATM client application. The images subdirectory contains .gif files used by the graphical user interface in the ATM client application.

• shared-contains common files for the JDBC Bankapp and XA Bankapp sample applications.

You only need to manually copy the files 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.

You will use the files listed in Table 4-1 to build and run the XA Bankapp sample application.

Changing the Protection Attribute on the Files for the XA Bankapp Sample Application

During the installation of theWLE 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/*.*

Verifying 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.

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

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

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 WLE 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.

Running the setupX Command

The setupX command automates the following steps:

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

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

3. Creating the UBBCONFIG file

4. Creating 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

Loading the UBBCONFIG File

Use the following command to load the UBBCONFIG file:

prompt>tmloadcf -y ubb_xa

Creating a Transaction Log

The transaction log records the transaction activities in a WLE 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.

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

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 following application processes:

• TMSYSEVT

  The 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

  The transaction manager service.

• BankDataBase

  The WLE server process that implements the DBAccess interface.

• JavaServerXA

  The 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

  The IIOP Listener process.

Files Generated by the XA Bankapp Sample Application

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

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 WLE 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. Figure 3-2 shows the GUI for the ATM client application.

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.