The JDBC Bankapp Sample Application
This topic includes the following sections:
Refer to the Readme.txt file in the \WLEdir\samples\corba\bankapp_java\JDBC directory for troubleshooting information and for the latest information about using the JDBC Bankapp sample application.
How the JDBC Bankapp Sample Application Works
The JDBC Bankapp sample application implements an automatic teller machine (ATM) interface and uses Java Database Connectivity (JDBC) to access a database that stores account and customer information. This topic includes the following sections:
Java Server Objects
The JDBC Bankapp sample application consists of a Java server application that contains the objects listed in Table 3-1.
Table 3-1 Objects in the Java Server Application of the JDBC Bankapp
Object
Description
The TellerFactory object creates the object references to the Teller object.
The Teller object receives and processes requests for banking operations from the ATM client application.
The DBAccess object receives and processes requests from the Teller object to the database.
Figure 3-1 illustrates how the JDBC Bankapp sample application works.
Figure 3-1 The JDBC Bankapp Sample Application
JDBC Connection Pooling
The JDBC Bankapp sample application demonstrates how to use JDBC database connection pooling running in a multithreaded server application. In the JDBC Bankapp sample application, the WebLogic Enterprise software creates and initializes a pool of database connections that the sample application uses. All DBAccess objects share this pool. For more information about JDBC connection pools, see Using the JDBC Drivers.
A minimum number of database connections are established when the server applications is initialized. The number of connections is increased on demand. When a worker thread receives a request for a DBAccess object, the corresponding DBAccess method gets an available database connection from the pool. When the call to the DBAccess method completes, the database connection is returned to the pool. If there is no database connection available and the maximum number of database connections has been established, the worker thread waits until a database connection becomes available.
Development Process for the JDBC Bankapp Sample Application
This topic includes the following sections:
This topic describes the development process for the JDBC Bankapp sample application.
Note: The steps in this topic have been done for you and are included in the JDBC Bankapp sample application.
Object Management Group (OMG) Interface Definition Language (IDL)
Table 3-2 lists the CORBA interfaces defined in the OMG IDL for the JDBC Bankapp sample application:
Table 3-2 CORBA Interfaces Defined in the JDBC Bankapp OMG IDL
Interface
Description
Methods
Creates object references to the Teller object
Performs banking operations
Accesses the Oracle database on behalf of the Teller object
Listing 3-1 shows the BankApp.idl file that defines the TellerFactory and Teller interfaces in the JDBC Bankapp sample application. A copy of this file is included in the directory for the JDBC Bankapp sample application.
Listing 3-1 OMG IDL Code for the TellerFactory and Teller Interfaces
#pragma prefix "beasys.com"
#pragma javaPackage "com.beasys.samples"
#include "Bank.idl"
module BankApp exception IOException <>;
exception TellerInsufficentFunds();
struct BalanceAmounts float fromAccount;
float toAccount;
>;
struct TellerActivity long totalRequests;
long totalSuccesses;
long totalFailures;
float currentBalance;
>;
//Process Object
interface Teller void verify_pin_number(in short pinNo,
out Bank::CustAccounts accounts)
raises(Bank::PinNumberNotFound, IOException);
float deposit(in long accountNo, in float amount)
raises(Bank::AccountRecordNotFound,IOException);
float withdraw(in long accountNo, in float amount)
raises(Bank::AccountRecordNotFound,
Bank::InsufficentFunds,
IOException, TellerInsufficientFunds);
float inquiry(in long accountNo)
raises(Bank::AccountRecordNotFound, IOException);
void transfer(in long fromAccountNo,
in long toAccountNo,in float amount,
out BalanceAmounts balAmounts)
raises(Bank::AccountRecordNotFound,
Bank::InsufficientFunds,
IOException);
void report(out TellerActivity tellerData)
raises(IOException);
>;
interface TellerFactory Teller createTeller(in string tellerName);
>;
Listing 3-2 shows the BankDB.idl file that defines the DBAccess interface in the JDBC Bankapp sample application. A copy of this file is included in the directory for the JDBC Bankapp sample application.
Listing 3-2 OMG IDL Code for the DBAccess Interface
#pragma prefix "beasys.com"
#pragma javaPackage "com.beasys.samples"
#include "Bank.idl"
module BankDB struct AccountData long accountID;
float balance;
>;
interface DBAccess void get_valid_accounts(in short, pinNo,
out Bank::CustAccounts accounts)
raises(Bank::DatabaseException,
Bank::PinNumberNotFound);
void read_account(inout AccountData data)
raises(Bank::DatabaseException,
Bank::AccountRecordNotFound);
void update_account(inout AccountData data)
raises(Bank::DatabaseException,
Bank::AccountRecordNotFound,
Bank::InsufficientFunds);
void transfer_funds(in float_amount,
inout AccountData fromAcct,
inout AccountData toAcct,
raises(Bank::DatabaseException,
Bank::AccountRecordNotFound, Bank::InsufficientFunds);
>;
Listing 3-3 shows the Bank.idl file that defines common exceptions and structures. It is included by both BankApp.idl and BankDB.idl . A copy of this file is included in the directory for the JDBC Bankapp sample application.
Listing 3-3 OMG IDL Code for the Exceptions and Structures in JDBC Bankapp
#pragma prefix "beasys.com"
#pragma javaPackage "com.beasys.samples"
module Bank
exception DataBaseException <>;
exception PinNumberNotFound ();
exception AccountRecordNotFound ();
exception InsufficientFunds ();
struct CustAccounts long checkingAccountID;
long savingsAccountID;
>;
During the development of the client application, you would write Java code that does the following:
A Java client application, referred to as the ATM client application, is included in the JDBC Bankapp sample application. For more information about writing Java client applications that use transactions, see Using Transactions.
During the development of the server application, you would write the following:
The implementations for the Teller object include invoking operations on the DBAccess object.
Because the Teller object has durable state (for example, ATM statistics) that 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 JDBC Bankapp server application is configured to be multithreaded. Writing a multithreaded WebLogic Enterprise Java server application is the same as writing a single-threaded Java server application; you cannot establish multiple threads programmatically in your object implementations. Instead, you establish the number of threads for a Java server application in the UBBCONFIG file. For information about writing Java server applications and using threads in Java server applications, see Using Transactions.
Server Description File (BankApp.xml)
During development, you create a Server Description File ( BankApp.xml ) that defines the activation and transaction policies for the TellerFactory , Teller , and DBAccess interfaces. Table 3-3 shows the activation and transaction policies for the JDBC Bankapp sample application.
Table 3-3 Activation and Transaction Policies for JDBC Bankapp
Interface
Activation Policy
Transaction Policy
A Server Description File for the JDBC 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.
When using the WebLogic Enterprise software, the server application is represented by a Java ARchive (JAR). The JAR must be loaded into the Java Virtual Machine (JVM) to be executed. The JVM must execute in a WebLogic Enterprise server application to be integrated in an WebLogic Enterprise application. By default, the server application that loads the JVM is called JavaServer . You include the options to start JavaServer in the Servers section of the application's UBBCONFIG file. For information about starting the JavaServer and defining parameters in the UBBCONFIG file, see "Creating the Configuration File" in the Administration Guide.
Enabling Multithreaded Support
If your Java server application is multithreaded, you can establish the number of threads by using the command-line option ( CLOPT ) -M in the SERVERS section of the UBBCONFIG file. In Listing 3-4, the -M 100 option enables multithreading for the JavaServer and specifies 100 as the maximum number of worker threads that a particular instance of JavaServer can support. The largest number that you can specify is 500.
Listing 3-4 Enabling Multithreaded Support in UBBCONFIG
JavaServer
SRVGRP = BANK_GROUP1
SRVID = 2
SRVTYPE = JAVA
CLOPT = "-A -- -M 100 Bankapp.jar TellerFactory_1 bank_pool"
RESTART = N
Notes: The SRVTYPE=JAVA line is required when using JDBC connection pooling.
The information for the CLOPT parameter needs to be entered on one line.
You also need to set the MAXACCESSERS parameter in the RESOURCES section of the UBBCONFIG file to account for the number of worker threads that each server application is configured to run. The MAXACCESSERS parameter specifies the number of processes that can attach to a WebLogic Enterprise application.
Setting Up the Connection Pool
For the JDBC Bankapp sample application, you need to include the name of the connection pool on the command-line option ( CLOPT ) in the SERVERS section of the UBBCONFIG file, as shown in Listing 3-5.
Listing 3-5 Specifying the Connection Pool Name (bank_pool) in UBBCONFIG
CLOPT = "-A -- -M 100 Bankapp.jar TellerFactory_1 bank_pool"
Note: The information for the CLOPT parameter needs to be entered on one line.
In addition, you need to include the following information on the JDBCCONNPOOLS section of the UBBCONFIG file:
Listing 3-6 provides an example of the JDBCCONNPOOLS section in the UBBCONFIG .
Listing 3-6 Specifying JDBCCONNPOOLS Information in UBBCONFIG
JDBCCONNPOOLS
bank_pool
SRVGRP = BANK_GROUP1
SRVID = 2
DRIVER = "weblogic.jdbc20.oci815.Driver"
URL = "jdbc:weblogic:oracle:Beq-local"
PROPS = "user=scott;password=tiger;server=Beq-Local"
ENABLEXA = N
INITCAPACITY = 2
MAXCAPACITY = 10
CAPACITYINCR = 1
CREATEONSTARTUP = Y
Setting Up the Database for the JDBC Bankapp Sample Application
The JDBC Bankapp sample application uses a database to store all the bank data. You can use either the Oracle or the Microsoft SQL Server database with the JDBC Bankapp sample application.
Before you can build and run the JDBC Bankapp sample application, you need to follow the steps in the product documentation to install the desired database.
The jdbcKona/Oracle and jdbcKona/MSSQLServer4 drivers are installed as part of the WebLogic Enterprise installation. For more information about the jdbcKona drivers, refer to the Using the JDBC Drivers and the BEA WebLogic Enterprise Installation Guide.
Note: The jdbcKona/Oracle driver supports Oracle Version 7.3.4 and Oracle8i (for Solaris and Windows NT) and versions 8.04 and 8i (for HP-UX). By default, this sample application supports Oracle version 7.3.4 on NT/Solaris and version 8.0.4 on HP. You can use a different Oracle version by specifying command line parameters, as described in Step 4: Run the setupJ Command.
Setting Up an Oracle Database
If you are using Oracle as the database for the JDBC Bankapp sample application, you need to install the following software:
When using the Oracle database, you use the default database created by the Oracle installation program. You need the connection string you defined for the Oracle database and the default user id and password. Refer to the Oracle product documentation for details about obtaining this information.
Setting Up a Microsoft SQL Server Database
If you are using the Microsoft SQL Server as the database for the JDBC Bankapp sample application, you need to install the following software:
When using the Microsoft SQL Server database, you use the master database instance. You need the name of the machine where the Microsoft SQL Server database is installed and the user name and password you defined for the master instance of the Microsoft SQL Server database. Refer to the Microsoft product documentation for details about obtaining this information.
Building the JDBC Bankapp Sample Application
This topic describes the following steps, which are required to build the JDBC Bankapp sample application:
Step 1: Copy the Files for the JDBC Bankapp Sample Application into a Work Directory
You need to copy the files for the JDBC Bankapp sample application into a work directory on your local machine.
Source File Directories
The files for the JDBC Bankapp sample application are located in the following directories:
Windows NT
UNIX
Table 3-4 describes the contents of these directories.
Table 3-4 Source File Directories for the JDBC Bankapp Sample Application
Directory
Description
Source files and commands needed to build and run the JDBC Bankapp sample application.
Files for the ATM client application. The images subdirectory contains .gif files used by the graphical user interface in the ATM client application.
Common files for the JDBC Bankapp and XA Bankapp sample applications.
Copying Source Files to the Work Directory
You need to manually copy only the files in the \JDBC directory. The other sample application files are automatically copied from the \client and \shared directories when you execute the setupJ command. For example:
Windows NT
prompt> cd c:\mysamples\bankapp _ java\JDBC
prompt> copy c:\WLEdir\samples\corba\bankapp_java\JDBC\*
UNIX
ksh prompt> cd /usr/mysamples/bankapp_java/JDBC/*
ksh prompt> cp $TUXDIR/samples/bankapp_java/JDBC/* .
Note: You cannot run the JDBC Bankapp sample application in the same work directory as the XA 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 JDBC Bankapp Sample Application
Table 3-5 lists the files used to build and run the JDBC Bankapp sample application.
Table 3-5 Files Included in the JDBC Bankapp Sample Application
File
Description
The OMG IDL code that declares common structures and extensions for the JDBC Bankapp sample application.
The OMG IDL code that declares the TellerFactory and Teller interfaces.
The OMG IDL code that declares the DBAccess interface.
The Java source code that implements the createTeller method. This file is in the com.beasys.samples package. It is automatically moved to the com/beasys/samples directory by the setupJ command.
The Java source code that implements the verify , deposit , withdraw , inquiry , transfer , and report methods. This file is in the com.beasys.samples package. It is automatically moved to the com/beasys/samples directory by the setupJ command.
The Java source code that overrides the Server.initialize and Server.release methods.
The Java source code that implements the get_valid_accounts , read_account , update_account , and transfer methods. This file is in the com.beasys.samples package. It is automatically moved to the com/beasys/samples directory by the setupJ command.
The Java source code for the ATM client application.
Contains methods to initialize, read from, and write to the flat file that contains the ATM statistics.
The Server Description File used to associate activation and transaction policy values with CORBA interfaces.
A Java program that initializes the database and ensures that JDBC is working properly.
The Windows NT batch file that builds and runs the JDBC Bankapp sample application.
The UNIX Korn shell script that builds and runs the JDBC Bankapp sample application.
The make file for the JDBC Bankapp sample application on the UNIX operating system. The UNIX make command needs to be in the path of your machine.
The make file for the JDBC Bankapp sample application on the Windows NT operating system. The Windows NT nmake command needs to be in the path of your machine.
The file that provides the latest information about building and running the JDBC Bankapp sample application.
Step 2: Change the Protection Attribute on the Files for the JDBC Bankapp Sample Application
During the installation of the WebLogic Enterprise software, the files for the JDBC Bankapp sample application are marked read-only. Before you can edit or build the files in the JDBC 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
ksh prompt>chmod u+w / workdirectory /*.*
Step 3: Verify the Settings of the Environment Variables
Before building and running the JDBC 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 3-6 lists the environment variables required to run the JDBC Bankapp sample application.
Table 3-6 Required Environment Variables for the JDBC Bankapp Sample Application
Environment Variable
Description
The directory path where you installed the WebLogic Enterprise software. For example:
Windows NT
UNIX
The directory path where you installed the JDK software. For example:
Windows NT
UNIX
The directory path where you installed the Oracle software. For example:
Windows NT
UNIX
Note: This environment variable applies only if you are using the Oracle database on the Solaris operating system.
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
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 setupJ Command
The setupJ command automates the following steps:
The syntax for the setupJ command is:
prompt>setupJ DB_DRIVER DB_SERVER DB_USER DB_PASSWORD
Parameter
Description
Name of the database driver. Valid values include:
Defaul values are jdbcOracle734 (on Solaris or NT) or jdbcOracle804 (on Hewlett-Packard).
Name of the machine where the database is installed. Default values are Beq-Local (on NT) or null (on Solaris or Hewlett-Packard).
Username defined for the database. Default value is scott .
Password defined for the database. Default value is tiger .
Note: SetupJ uses default values unless you explicitly specify arguments. For example, to use Microsoft SQL Server, you must specify all command line parameters.
Follow these steps to enter the setupJ command:
Windows NT
prompt>cd c:\mysamples\bankapp _ java\JDBC
prompt>setupJ jdbcOracle815 Beq-Local scott tiger
UNIX
prompt>. ./setupJ.ksh jdbcOracle815 null scott tiger
Step 5: Load the UBBCONFIG File
Use the following command to load the UBBCONFIG file:
prompt>tmloadcf -y ubb_jdbc
Compiling the Client and Server Applications
The directory for the JDBC Bankapp sample application contains a make file that builds the client and server sample applications. During development, 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 JDBC Bankapp sample application, these steps are included in the make file.
Use the following commands to build the client and server applications in the JDBC Bankapp sample application:
Windows NT
prompt>nmake -f makefileJ.nt
UNIX
prompt>make -f makefileJ.mk
Initializing the Database
This topic includes the following sections:
Initializing an Oracle Database
To initialize an Oracle database using the default arguments, enter the following command:
To initialize the Oracle database with user-defined attributes, enter the following command:
prompt>java InitDB driver_name connect_string username password
Parameter
Description
Name of the database driver. Valid values include:
Defaul values are jdbcOracle734 (on Solaris or NT) or jdbcOracle804 (on Hewlett-Packard).
Connection string for the instance of the Oracle database being used with the JDBC Bankapp sample application. Default values are Beq-Local (on NT) or null (on Solaris or Hewlett-Packard).
User name for the Oracle database. Default value is scott .
Password for the Oracle database. Default value is tiger .
Initializing a Microsoft SQL Server Database
To initialize a Microsoft SQL Server database, enter the following command:
prompt>java InitDB JdbcMSSQL4 db_server username password
Parameter
Description
Name of the database driver for Microsoft SQL Server. This is the only valid value.
Name of the machine on which the Microsoft SQL Server database is installed.
User name for the master instance of the Microsoft SQL Server database.
Password for the master instance of the Microsoft SQL Server database.
Starting the Server Application in the JDBC Bankapp Sample Application
Start the server application in the JDBC Bankapp sample application by entering the following command:
prompt>tmboot -y
The tmboot command starts the application processes listed in Table 3-7.
Table 3-7 Application Processes Started by tmboot Command
Process
Description
BEA Tuxedo system event broker.
Three TMFFNAME server processes are started:
Server process that implements the TellerFactory , Teller, and DBAccess interfaces.
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 JDBC Bankapp Sample Application
Table 3-8 lists the files generated by the JDBC Bankapp sample application.
Table 3-8 Files Generated by the JDBC Bankapp Sample Application
File
Description
The UBBCONFIG file for the JDBC Bankapp sample application. This file is generated by the setupJ command.
setenvJ.cmd and setenvJ.ksh
Contains the commands to set the environment variables needed to build and run the JDBC Bankapp sample application. setenvJ.cmd is the Windows NT version and setenvJ.ksh is the UNIX Korn shell version of the file.
A binary version of the UBBCONFIG file. Generated by the tmloadcf command.
A log file that contains messages generated by the tmboot command. The log file also contains messages generated by the server applications and by the tmshutdown command.
A file that contains the security encryption key database. The subdirectory is created by the tmloadcf command.
Used by the Java client application. Created when the Atm.java file is compiled.
Initializes the database used by the JDBC Bankapp sample application. Created when InitDB.java is compiled.
Generated by the m3idltojava command for the interfaces defined in the Bank.idl file. These files are created in the com/beasys/samples/Bank directory.
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.
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.
The Server Descriptor File and Server Java Archive file generated by the buildjavaserver command in the make file.
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.
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.
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 JDBC 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 Teller1
UNIX
ksh prompt>java -classpath .:$TUXDIR/udataobj/java/jdk
/m3envobj.jar -DTOBJADDR=$TOBJADDR Atm Teller1
The GUI for the ATM client application appears. Figure 3-2 shows the GUI for the ATM client application.
Figure 3-2 GUI for ATM Client Application
Stopping the JDBC Bankapp Sample Application
Before using another sample application, enter the following commands to stop the JDBC Bankapp sample application and to remove unnecessary files from the work directory:
Windows NT
prompt>nmake -f makefileJ.nt clean
UNIX
ksh prompt>tmshutdown -y
ksh prompt>make -f makefileJ.mk clean
Using the ATM Client Application
This topic includes the following sections:
Available Banking Operations
In the ATM client application, a customer enters a personal identification number (PIN) and performs one of the following banking operations:
One special PIN number (999) allows customers to receive statistics about the ATM machine. The following statistics are available:
For example, an inquiry is one request, and a withdrawal is one request.
For example, when a customer attempts to withdraw more money than is in his account, the request fails.
The ATM machine starts with $10,000 and the amount decreases with each withdrawal request.
Use the keypad in the ATM client application to enter a PIN and amounts for deposit, transfer, and withdrawal. Table 3-9 describes the functions available on the keypad in the ATM client application.
Table 3-9 Keypad Functions in the ATM Client Application
Key
Function
Use this key to cancel the current operation and exit the view.
Use this key to accept the entered data. After you enter a PIN or an amount for deposit, transfer, or withdrawal, you need to click the OK button to have the action take effect.
Numerics (0 through 9)
Use these keys to enter your PIN and an amount for deposit, transfer, and withdrawal amounts.
Use this key to enter decimal amounts for deposit, transfer, and withdrawal.
Steps for Using the ATM Client Application
To use the ATM client application in the JDBC Bankapp sample application:
The Operations view appears. Figure 3-3 shows the Operations view in the ATM client application.
Figure 3-3 Operations View in the ATM Client Application
From the Operations view, you can perform the follow banking operations:
An updated account balance appears.
Note: After you click OK, you cannot cancel the operation. If you enter an amount and then select Cancel, the ATM client application cancels your operation and displays the previous screen.
Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.