|
|
The XA Bankapp Sample Application
This topic includes the following sections:
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:
The XA Bankapp sample application consists of two server applications:
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:
Development Process for the XA Bankapp Sample Application
This topic includes the following sections:
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.
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:
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:
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:
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:
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.
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 |
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.
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. |
To verify that the information defined during installation is correct:
Windows NT
The Control Panel appears.
The System Properties window appears.
The Environment page appears.
UNIX
ksh prompt>printenv TUXDIR
ksh prompt>printenv JAVA_HOME
ksh prompt>printenv ORACLE_HOME
Changing Settings
To change the settings:
Windows NT
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:
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:
tmadmin
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
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.
Process |
Description |
---|---|
TMSYSEVT |
BEA Tuxedo system event broker. |
TMFFNAME |
Three TMFFNAME server processes are started:
|
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:
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.
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 |
Used by the Java client application. Created when the Atm.java file is compiled. |
AccountRecordNotFound.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 |
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 |
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 |
The Server Descriptor file and Server Java Archive file generated by the buildjavaserver command in the make file. |
Bank_c.cpp |
Generated by the idl command for the interfaces defined in the Bank.idl file. |
BankDB_c.cpp |
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.
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|