BEA WebLogic Enterprise 4.2    Developer Center     

        HOME   |   SITE MAP   |   SEARCH   |   CONTACT   |   GLOSSARY  |   PDF FILES |   WHAT'S NEW 
 
        GETTING STARTED    |   TABLE OF CONTENTS   |   PREVIOUS TOPIC   |   NEXT TOPIC   |   INDEX 

The JDBC Bankapp Sample Application


This chapter discusses the following topics:

Refer to the Readme.txt file in the \WLEdir\samples\corba\bankapp_java 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. The JDBC Bankapp sample application consists of a Java server application that contains the following objects:

Figure 3-1 illustrates how the JDBC Bankapp sample application works.

Figure 3-1 The JDBC Bankapp Sample Application

The JDBC Bankapp sample application demonstrates how to implement JDBC database connection pooling running in a multithreaded server application. In the JDBC Bankapp sample application, a pool of database connections is created when the Java server application is initialized. All DBAccess objects share this pool.

A minimum number of database connections is established when the server application 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.

The Development Process for the JDBC Bankapp Sample Application

This section describes the development process for the JDBC Bankapp sample application.

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

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

The OMG IDL for the JDBC Bankapp sample application defines the following CORBA interfaces:

Interface Description Methods

TellerFactory

Creates object references to the Teller object

create_Teller()

Teller

Performs banking operations

verify_pin_number()

deposit()

withdraw()

inquiry()

transfer()

report()

DBAccess

Accesses the Oracle database on behalf of the Teller object

get_valid_accounts()

read_account()

update_account()

transfer_funds()

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;
};
};

The Client Application

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, see Creating Client Applications.

The Server Application

During the development of the server application, you would write the following:

The JDBC Bankapp server application is configured to be multithreaded. Writing a multithreaded WLE 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 Creating Java 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, Teller, and DBAccess interfaces. For the JDBC Bankapp sample application, the objects have the following activation and transaction policies:

Interface Activation Policy Transaction Policy

TellerFactory

Process

Never

Teller

Method

Never

DBAccess

Method

Never

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.

The UBBCONFIG File

When using the WLE 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 WLE server application to be integrated in an WLE 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.

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 the following example, 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.

JavaServer
SRVGRP = BANK_GROUP1
SRVID = 2
CLOPT = "-A -- -M 100 Bankapp.jar TellerFactory_1"
RESTART = N

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

For the JDBC Bankapp sample application, you need to include the following information on the command-line option (CLOPT) in the SERVERS section of the UBBCONFIG file:

For example:

JavaServer
SRVGRP = BANK_GROUP1
SRVID = 2
CLOPT = "-A -- -M 10 BankApp.jar TellerFactory_1 jdbcOracle2 Beq-Local
scott tiger 2 5"
RESTART = N

Note: The information for the CLOPT parameter needs to be entered on one line.

For information about starting the JavaServer and defining parameters in the UBBCONFIG file, see the Administration Guide.

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.

If you are using Oracle as the database for the JDBC Bankapp sample application, you need to install the following software:

If you are using the Microsoft SQL Server as the database for the JDBC Bankapp sample application, you need to install the following software:

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.

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.

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.

The jdbcKona/Oracle and jdbcKona/MSSQLServer4 drivers are installed as part of the WLE installation. For more information about the jdbcKona drivers, refer to the JDBC Driver Programming Reference and Installing the WebLogic Enterprise Software.

Note: The jdbcKona/Oracle driver supports only Oracle Version 7.3.4 or higher.

Building the JDBC Bankapp Sample Application

To build the JDBC Bankapp sample application:

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

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

  3. Verify the settings of the environment variables.

  4. Run the setupJ command.

  5. Load the UBBCONFIG file.

The following sections describe these steps.

Copying 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. The files for the JDBC Bankapp sample application are located in the following directories:

Windows NT

drive:\WLEdir\samples\corba\bankapp_java\JDBC

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

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

UNIX

/usr/local/WLEdir/samples/corba/bankapp_java/JDBC

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

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

The directories contain the following:

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.

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

Table 3-1 Files Included in the JDBC Bankapp Sample Application

File Description

Bank.idl

The OMG IDL code that declares common structures and extensions for the JDBC 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.

TellerFactoryImpl.java

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.

TellerImpl.java

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.

BankAppServerImpl.java

The Java source code that overrides the Server.initialize and Server.release methods.

DBAccessImpl.java

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.

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.

InitDB.java

A Java program that initializes the database and ensures that JDBC is working properly.

ConnectionPool.java

Implements the database connection pooling mechanism.

setupJ.cmd

The Windows NT batch file that builds and runs the JDBC Bankapp sample application.

setupJ.ksh

The UNIX Korn shell script that builds and runs the JDBC Bankapp sample application.

makefileJ.mk

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.

makefileJ.nt

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.

Readme.txt

The file that provides the latest information about building and running the JDBC Bankapp sample application.

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

During the installation of the WLE 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

prompt>/bin/ksh

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

Verifying 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-2 lists the environment variables required to run the JDBC Bankapp sample application.

Table 3-2 Required Environment Variables for the JDBC Bankapp Sample Application

Environment Variable Description

TUXDIR

The directory path where you installed the WLE 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:

UNIX

ORACLE_HOME=/usr/local/oracle

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

  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 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. In the Value field, enter the correct information for the environment variable.

  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 setupJ Command

The setupJ 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 setenvJ.cmd or setenvJ.ksh file that can be used to reset the system environment variables

Enter the setupJ command, as follows:

Windows NT

prompt>cd c:\mysamples\bankapp_java\JDBC

prompt>setupJ

UNIX

prompt>/bin/ksh

prompt>cd /usr/mysamples/bankapp_java/JDBC

prompt>. ./setupJ.ksh

Loading 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

Note: If you are using the Microsoft SQL Server database, you need to manually modify the JavaServer line in the UBBCONFIG file. For information about the JavaServer information in the UBBCONFIG file, see the section "Starting the Server Application in the JDBC Bankapp Sample Application."

Initializing the Database

To initialize the Oracle database using the default arguments, enter the following command:

prompt>java InitDB

To initialize the Oracle database with user-defined attributes, enter the following command:

prompt>java InitDB JdbcOracle2 connect_string username password

where

connect_string

Is the defined connection string for the instance of the Oracle database being used with the JDBC Bankapp sample application. The default value is Beq-local.

username

Is the user name you defined for the Oracle database. The default value is scott.

password

Is the password you defined for the Oracle database. The default value is tiger.

To initialize the Microsoft SQL Server database, enter the following command:

prompt>java InitDB JdbcMSSQL4 db_server username password

where

db_server

Is the name of the machine where the Microsoft SQL Server database is installed

username

Is the user name you defined for the master instance of the Microsoft SQL Server database

password

Is the password you defined 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 following application processes:

Files Generated by the JDBC Bankapp Sample Application

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

Table 3-3 Files Generated by the JDBC Bankapp Sample Application

File Description

ubb_jdbc

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.

tuxconfig

A binary version of the UBBCONFIG file. Generated by the tmloadcf command.

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

ConnectionPool.class

Defines how database pooling works in the JDBC sample application.

InitDB.class

Initializes the database used by the JDBC Bankapp sample application. Created when InitDB.java 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 directory.

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.

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 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 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 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>tmshutdown -y

prompt>nmake -f makefileJ.nt clean

UNIX

ksh prompt>tmshutdown -y

ksh prompt>make -f makefileJ.mk clean

Using the ATM Client Application

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:

Use the keypad in the ATM client application to enter a PIN and amounts for deposit, transfer, and withdrawal. Table 3-4 describes the functions available on the keypad in the ATM client application.

Table 3-4 Keypad Functions in the ATM Client Application

Key Function

Cancel

Use this key to cancel the current operation and exit the view.

OK

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.

Period (.)

Use this key to enter decimal amounts for deposit, transfer, and withdrawal.

To use the ATM client application in the JDBC Bankapp sample application:

  1. Enter one of the following PINs: 100, 110, 120, or 130.

  2. Click OK.

    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:

  3. Click the desired banking operation.

  4. Click either the Checking Acct or Savings Acct button.

  5. Enter a dollar amount.

  6. Click OK.

    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.

  7. Click OK.

  8. Click Cancel to return to the main window of the ATM client application.


Copyright © 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: June 24, 1999.