Sun ONE logo
Java TM Duke's Bank Sample Application

 

Java TM Duke's Bank Sample Application
 

This document describes how to utilize the Java TM Duke's Bank sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:

Overview

This section describes the Duke's Bank application, an online banking application. Duke's Bank has two clients: a J2EE application client used by administrators to manage customers and accounts, and a Web client used by customers to access account histories and perform transactions. The clients access the customer, account, and transaction information maintained in a database through enterprise beans. The Duke's Bank application demonstrates how all the component technologies--enterprise beans, J2EE application clients, and Web components--presented in this tutorial are put together to provide a simple but functional application.

Figure 1 provides a high level view of how the components interact.


Figure 1    Duke's Bank Component Interaction

For additional information, please see Duke's Bank documentation available on java.sun.com with the J2EE Tutorial.
 

Setting up the environment

In order to successfully deploy and run theDuke's Bank sample application, several resources need to be setup with the Application Server. These resources include:

  • JDBC resource

  • JDBC connection pool

  • the main application.
Setting up the Database

The PointBase database server is automatically populated with all the necessary data for the Duke's Bank application when it is started.

Start the PointBase database server by running one of the following scripts, depending on your operating system:

  • Solaris
  • <install_root>/pointbase/server/StartServer.sh
  • Windows 2000
  • <install_root>/pointbase/server/StartServer.bat
For more information on using PointBase, please refer to the Using PointBase document.

If you prefer to re-create the database from scratch, you can use the sql files in src/sql to manually create schema and data in your PointBase server.
 
 

Compiling, Assembling and Deploying the Application



This section contains instructions to build and assemble the Duke's Bank sample application.
  1. Set AS_HOME environment variable. For example:
  2. For Solaris, do setenv AS_HOME <install_root> and setenv PATH ${AS_HOME}/bin:${PATH}
    For Windows 2000, do set AS_HOME=<install_root>
    This is needed to set up the right classpath for compiling the application. Be sure you set this variable from the shell where you plan to compile the application.
  3. Compile and Deploy the application. For example:
  4. Execute the command asant all under <install_root>/samples/dukesbank/src
    This will compile all sources, assemble the module and deploy the application.  The command asant all compiles all the sources, assembles the module and deploys the application, jdbc resource and jdbc connection pool.  To deploy again, type asant undeploy at the command line to undeploy the application, jdbc resource and jdbc connection pool followed by asant all.
    And then restart the server instance.
  5. Clean the application project area (optional).
  6. Execute the command asant clean to remove all files generated in Step 2.
  7. Generate javadocs (optional). For example:
  8. Execute the command asant javadocs under <install_root>/samples/dukesbank/src
    Javadocs will be located under <install_root>/samples/dukesbank/javadocs
  9. Verify Deployment (optional).
  10. You may use the Sun ONE Application Server Administration Tool to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.
    To verify the registration of the application, execute asadmin list-component to look at applications deployed with a server instance. For example:
    <install_root>/bin/asadmin list-components -u <username> -w <password> -H <host> -p <port> <server instance name>
    You will see the Duke's Bank Application listed.
Running the Sample Application

In this section, you will learn how to run the Duke's Bank sample application. In order to run the application, you must first do the following:
  • Deploy the application

  • Start your PointBase database server

Running the J2EE Application Client

To run the J2EE application client, do the following:

  1. In a terminal window, go to /dukesbank/src/jar.

  2. Set the APPCPATH environment variable to
  3. <appserver-install-dir>/domains/domain1/<instance>/applications/j2ee-apps/DukesBankApp_*/DukesBankAppClient.jar
  4. Edit the file <appserver-install-dir>/domains/domain1/<instance>/config/sun_acc.xml, modify it to have value<client-credential user-name="admin" password="j2ee"/>
  5. To run the English version of the client, execute the following command:
  6. <appserver-install-dir>/bin/appclient -client
    <appserver-install-dir>/domains/domain1/<instance>/applications/j2ee-apps/DukesBankApp_*/DukesBankAppClient.jar
    -name BankAdmin -xml  <appserver-install-dir>/domains/domain1/<instance>/config/sun-acc.xml
You should see the application displayed as shown in Figure 2.


Figure 2    English Version of Client running
 

Running the Web Client

To run the Web client, do the following:

  1. From your web brpwser, open the bank URL. For example: http://<server>:<port>/bank/main, in a Web browser.
  2. If your J2EE server is running on the same host as your Web browser, replace <host> with localhost.
  3. The application will display the login page.
  4. Enter 200 for the customer ID and j2ee for the password.
  5. Click submit.

  6. Select an application function: Account List, Transfer Funds, ATM, or Logoff.
  7. Once you have a list of accounts, you can get an account history by selecting an account link.
If you select Account List, you will see the screen shown in the Figure 3.


Figure 3    Account List Screen



Note The first time you select a new page, particularly a complicated page like an account history, it takes some time to display because the J2EE server must translate the page into a servlet class and compile and load the class. 


 

Configuring for use with the Oracle Database


The product application requires the following database setup prior to running:

    Ensure Database Requirements are Met

    See the Sun One Application Server Release Notes for database version requirements. The Product sample includes schema script for Oracle.

    Create an RDBMS User

      cd <install_root>/samples/docs

      sqlplus to oracle as system user and create a user called dukesbank

      SQL> @cr_ora_user.sql

      exit sqlplus

    Create and Populate the Product RDBMS Tables
      cd <install_root>/samples/dukesbank/src/sql

      sqlplus to oracle as dukesbank user

      SQL> @dukesbank-ora.sql;

      exit sqlplus

    Register JDBC Driver
    Make sure that JDBC driver zip/jar files are in classpath-suffix attribute of java-config element in server.xml of the instance running this product application. You may like to edit this file if necessary. Please make sure that the server.xml is also copied to backup directory.

    Create a new Oracle JDBC Connection Pool
    If you have followed the instructions for Compiling, Assembling and Deploying the Application against the PointBase server then:

     
    Change to the directory <install_root>/samples/dukesbank/src
    Execute the command asant delete-jdbc-resource
    Execute the command asant delete-jdbc-connection-pool
    Execute the command asant deploy-ora -Ddb.host=<host> -Ddb.port=<port> -Ddb.sid=<sid>
    And then restart the server instance.

    If you have not followed the instructions for Compiling, Assembling and Deploying the Application against the PointBase server:

    Change to the directory <install_root>/samples/dukesbank/src
    Execute the command asant all
    Execute the command asant delete-jdbc-resource
    Execute the command asant delete-jdbc-connection-pool
    Execute the command asant deploy-ora -Ddb.host=<host> -Ddb.port=<port> -Ddb.sid=<sid>
    And then restart the server instance.

    Rerun the Sample Application
    You may now run the application again using the steps under Running the J2EE Application Client and Running the Web Client in the Running the Sample Application section.

Troubleshooting
  • If you encounter problems when running the application, review the log files at <install-root>/domains/<domain-instance>/<server-instance>/logs/server.log to learn what exactly went wrong.

  • If you make changes to the application, you can use the build.xml in that specific module to rebuild the ear files. Your changes will be effective after you redeploy the ear file.

  • If you receive an error while logging into the Web client as user 200 and password j2ee, please make sure the keyfile is updated appropriately through the asant all call. Also please make sure that the PointBase database server is up and running, and the jdbc resource and jdbc connection pool is properly deployed in the Application Server.

  • If you receive an error that the jdbc resource or jdbc connection pool already exists, type "asant undeploy" at the command line before typing "asant all" again.

  • If you would like to run the command asant all at the command line after Configuring for use with the Oracle Database,  edit the db.host, db.port, and db.sid and replace the create-jdbc-connection-pool with deploy-ora for the target deploy_jdbc_resource.

  •  
Known Issues
  • If you Create a new user using the Appclient Admin Screen, you need to Generate the keyfile entry for the newly create user.  For example, to genetrate the keyfile entry for a user 200, group Customer and password j2ee run the command:
    • asadmin create-file-user --user <admin> --password <adminuser> --host <host> --port <port> --userpassword j2ee --groups Customer 200

      asadmin reconfig --user <admin> --password <adminuser> --host <host> --port <port> <server> --discardmanualchanges=true

      And restart the server instance.

  • When logging in If you see "CORBA.OBJECT_NOT_EXIST" exception, restart the instance.  This issue is being addressed currently.
  • The sample can not be deployed from the application server administration GUI, if Run verifier or Precompile JSPs option is selected. Solution is, try deploying the application without Run verifier and Precompile JSPs, or deploy using asant.

  • The sample can not be deployed using asadmin with option --verify=true or --precompilejsp=true. Solution is, try deploying the application without the option --verify=true and --precompilejsp=true, or deploy using asant.

  • The sample uses a jdbc resource by the name jdbc/Cloudscape. The name is misleading and the application works with PointBase by default and will work with Oracle by following necessary instructions provided in the doc.
 

Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated July 16, 2002