Bank Application
iPlanet^TM Application Server J2EE Samples

If you already went through the deployment process of Bank you can run the application by clicking here.

The Bank sample application provides a web-based interface to a basic online banking service. A collection of servlets interact with two stateless session beans to provide customers with balance inquiry and account transfer services. Bank customer service representatives are able to add new customers and remove existing customers from the bank's database as well as from the directory server. Additional features of note include:

• Customer information is maintained in an RDBMS.
• User authentication occurs via LDAP access to a directory server.
• J2EE form-based login feature is used to trigger user authentication.
• Single source or "local" transactions are used to ensure debits and credits occur in a consistent manner when transferring funds between accounts.

Although Bank uses several key features of the J2EE programming model, you should also consider exercising Sun Microsystem's popular Java Pet Store application on iPlanet Application Server.

Setting Up the Environment

Getting Started includes a checklist of pre-requisites for deploying the sample applications to iPlanet.

Configuring the Database describes how to setup the database schema, load the content and register the JDBC data sources for the Bank application.

Populating the Directory describes how to add Bank users and groups to the directory server.

Deploying and Running the Bank Application

Select one of two approaches to deploying and registering the application:

Command Line-based Deployment describes how to manually register the bank application in iPlanet using a Command Line Interface (CLI). This is the fastest means of deploying the Bank to the application server.

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the Bank application. Alternatively, you can also assemble the application from scratch and deploy it using the Deployment Tool.

Running the Application describes how to start the application, navigate through it and how to troubleshoot in the event of problems.

Further Exploration

Using Third Party JDBC Drivers describes how to configure the application to use a non-iPlanet JDBC driver to access the database.

Compiling and Assembling the Application describes how to use command line tools to recompile the sources and rebuild the WAR and EJB modules and the overall EAR file.

Clustering the Bank Application describes how to take advantage of the application server's load balancing and clustering features.

Configuring the Database

Ensure Database Requirements are Met

Ensure Database Driver is Registered

Identify or Create a Database User

Create and Populate Sample Database Tables

Ensure Database Requirements are Met

• Oracle
• Sybase
• DB2
• Informix
• SQL Server

Note: The bundled Pointbase database is not supported for this sample

Ensure Database Driver is Registered

Determine if the iPlanet Type 2 Driver is Registered

1. Start the Admin Tool

install_dir/ias/bin/ksvradmin

2. Connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the application server's administrator's password and click on OK.
3. Click on the Database button and expand the server name (default name of iAS1) to see the database driver settings.
4. If you see a red X on the client driver entry of interest, then you need to run the db_setup.sh script to register the native client driver in the application server. Go to the next section to register the driver.

Register Driver if Necessary

UNIX: Database Driver Registration

1. Ensure that your user ID is the same as the one used to install the application server.
2. Execute the database driver registration script:

install_dir/ias/bin/db_setup.sh

3. Follow the instructions to register the native client driver. The default application server installation root directory is /usr/iplanet/ias6.
4. For the Bank sample, you need not register a Resource Manager. (Resource Manager setup is required only in support of distributed and possibly heterogeneous transactions relying on the application server's built-in transaction manager).
5. Restart the application server using the iascontrol stop and iascontrol start commands.
6. After you've registered the driver, you can use the application server's Admin Tool (ksvradmin) to verify that the native driver entry no longer shows a red X and that the client library and other settings are accurate.

Identify or Create an RDBMS User

To define a new Oracle user:

1. Use SQL Plus to define an Oracle user name (e.g. bank).



SQL > create user bank identified by bank;

Where the first bank is the user name and the second bank is the password.

2. Grant connect, resource, and dba privileges to the bank Oracle user.



SQL> grant connect, resource, dba to bank identified by bank;

Create and Populate the Sample RDBMS Tables

1. Dynamically creates an XML file describing the JDBC datasource.
2. Invokes the application server's iasdeploy regdatasource command to register the data source resource in the application server's registry.
3. Verifies connectivity to the specified database.
4. Creates the tables required by the Bank application and populates the tables.

UNIX: Create and Populate RDBMS

Windows: Create and Populate RDBMS

UNIX: Create and Populate RDBMS

1. Ensure that the RDBMS enviornment variable is set appropriately. For example, ORACLE_HOME or SYBASE.

 
2. Edit setup_<rdbms type>.sh. Set the GX_ROOTDIR environment variable to the location of the ias/ directory in your application server installation.

For example,

GX_ROOTDIR=/usr/iplanet/ias6/ias

setup_ora.sh <TNS name> <dbusername> <dbpassword>

setup_syb.sh <Server Name> <database> <dbusername> <dbpassword>

For example using Oracle:

setup_ora.sh iassample bank bank

Where:

<TNS Name> is the Oracle service or TNS name which maps to the appropriate Oracle database instance. In the example above, "iassample" is the Oracle service or TNS name. (This assumes that the Oracle client has been configured to recognize "iassample" as a valid Oracles service/TNS name.)

<dbusername> and <dbpassword> are the Oracle user name and password under which the tables will be created and populated. These are also the values that will be used by the sample application to access the Oracle database.

Since the setup_ora.sh script uses sqlplus, ensure that LD_LIBRARY_PATH includes $ORACLE_HOME/lib.

For example using Sybase:

setup_syb.sh SYBIAS iassample iasdemo iasdemo

Where:

<Server Name> is the Sybase server name and port number. In the example above, ?SYBIAS? is the Sybase server name.

<database> is the Sybase database name.

<dbusername> and <dbpassword> are the Sybase user name and password under which the tables will be created and populated. These are also the values that will be used by the sample application to access the Sybase database.

Windows: Create and Populate RDBMS

2. Run setup_<rdbms type>.bat with the following arguments:

setup_ora <TNS name> <dbusername> <dbpassword>

setup_syb <Server Name> <database> <dbusername> <dbpassword>

setup_mssql <Server Name> <database> <dbusername> <dbpassword>

For example using Oracle:

setup_ora iassample bank bank

Where:

<TNS Name> is the Oracle service or TNS name which maps to the appropriate Oracle database instance. In the example above, "iassample" is the Oracle service or TNS name. (This assumes that the Oracle client has been configured to recognize "iassample" as a valid Oracles service/TNS name.)

<dbusername> and <dbpassword> are the Oracle user name and password under which the tables will be created and populated. These are also the values that will be used by the sample application to access the Oracle database.

For example using Sybase:

setup_syb SYBIAS iassample rrs rrs

Populating the Directory

Prepare the LDIF File

1. Edit the file install_dir/ias/ias-samples/bank/src/schema/BankUser.ldif
2. Change all references to "iplanet.com" to the same domain name as defined in the directory server installation. For example, change all "iplanet.com" entries to "yourcompany.com".
3. Now follow one of the following two sections to run the ldapmodify utility to populate the directory with users and groups needed by the Bank application.

UNIX: ldapmodify

ps -ef | grep slapd

nobody 27315 1 0 Dec 04 ? 4:53 ./ns-slapd -f /usr/iPlanet/iAS 6/slapd-miwok/config/slapd.conf

export LD_LIBRARY_PATH=install_dir/ias/gxlib:$LD_LIBRARY_PATH

For example,

export LD_LIBRARY_PATH=/usr/iplanet/ias6/ias/gxlib:$LD_LIBRARY_PATH

This setting will enable ldapmodify to find the necessary libraries.

install_dir/shared/bin/ldapmodify -D"cn=Directory Manager" -w <password> -a -f BankUser.ldif

For example,

/usr/iplanet/ias6/shared/bin/ldapmodify -D"cn=Directory Manager" -w password -a -f  BankUser.ldif

Where:

-D"cn=Directory Manager" specifies the distinguished name with which to authenticate to the server. This is the name that was supplied during installation of the application server.

-w <password> specifies the password for the directory server Directory Manager.

If you're running the directory server on a port other than 389, then add the -p option to supply a port number. For example, -p 1049.

If the directory server is on another host that the local host, then add the -h option to specify the target host name of the directory server. For example, -h cyclops.

Windows: ldapmodify

Start->Settings->Control Panel and start Services.

Verify that Netscape Directory Server is running.

ldapmodify -D"cn=Directory Manager" -w <password> -a -f BankUser.ldif

For example,

/usr/iplanet/ias6/shared/bin/ldapmodify -D"cn=Directory Manager" -w password -a -f BankUser.ldif

Where:

-D"cn=Directory Manager" specifies the distinguished name with which to authenticate to the server. This is the name that was supplied during installation of the application server.

-w <password> specifies the password for the directory server Directory Manager.

If you're running the directory server on a port other than 389, then add the -p option to supply a port number. For example, -p 1049.

If the directory server is on another host that the local host, then add the -h option to specify the target host name of the directory server. For example, -h cyclops.

If the following error occurs, it most likely means that you specified an incorrect domain name in the BankUser.ldif file.

root@canteloupe: /usr/iplanet/ias6/shared/bin/ldapmodify -D"cn=Directory Mana...

adding new entry uid=j2ee, ou=People, o=red.iplanet.com

ldap_add: No such object

Edit the .ldif file and change the "o=" attribute to the proper value. In this example, iplanet.com should be used in place of red.iplanet.com.

Verify Directory Server Additions

UNIX:

install_dir/startconsole

Windows:

Start->Programs->Netscape Server Family->Netscape Console 4.0

In the Directory Server admin tool, click on Directory tab and expand your domain name's folder to see the Groups and People defined for your domain.

Click on Groups. You should see several groups under the group name BankApp of interest to the Bank application: BankAdmin and BankUser. These two subordinate groups are used by the BankService EJB. Under each group, you can click on the Members tab to see who belongs to each group.

Command Line-based Deployment

You have a choice of  deploying and registering the Bank application through either command line utilities or the iPlanet Application Server Deployment Tool GUI. Since a complete EAR file is supplied, the fastest means of setting up Bank is to use the command line utilities as described in this section. If you would like to experience either deploying through a GUI tool or assembling an application from scratch, then follow instructions in GUI-based Deployment.

The pre-built bank.ear file is a Enterprise ARchive file that contains the Web Archive (WAR) and EJB JAR files for the Bank application. Within each of these JAR files reside the XML deployment descriptor files, application class files, JSPs and other content required by the application.

Deploying the pre-built bank.ear file is simple.

1. Go to the root of the Bank sample directory:

install_dir/ias/ias-samples/bank/

2. Execute iasdeploy to deploy Bank to the local application server instance:

install_dir/ias/bin/iasdeploy deployapp bank.ear

The deployment process will take 30 seconds to a minute or so to complete.

The deployment process involves the following operations:

• iasdeploy authenticates against the local application server's administrative server.
• the EAR file is transferred to the administrative server.
• the administrative server begins the registration process:
  • parses the EAR file and embedded WAR and EJB JAR files
  • registers the J2EE application "bank" in the iPlanet Registry within the directory server
  • registers the embedded J2EE modules (WARs and EJB JARs) in the iPlanet Registry within the directory server
  • extracts the EJB JAR and WAR modules to the JAR/ directory.
  • expands the content of the J2EE modules to the APPS/bank/ directory.

Your next step is to customize several environment settings to suit your network environment.

Modifying BankService EJB Environment Settings

To run Bank in your specific network domain, you will need to modify one or more these environment settings.

There are two means by which you can modify the EJB environment settings:

1. iPlanet Application Server Deployment Tool
2. iPlanet Application Server Registry Editor

BankService EJB Environment Settings

Using the Application Server Registry Editor

1. Execute install_dir/ias/bin/kregedit to start the Registry Editor GUI.
2. Navigate to the SOFTWARE/Netscape/Application Server/6.0/ portion of the tree.
3. Expand the J2EE-Module/ tree and look for the "bankEjb" module.
4. Expand the "bankEjb" module, expand "ejbs"
5. Note the GUID number associated with the BankService EJB.
6. Go up to the "6.0/" folder and expand the "ClassDef/" portion of the tree.
7. Expand the folder that has the same GUID as the BankService EJB.
8. Expand the folder that has a version number.
9. Expand the "SessionDescriptor/" folder.
10. Expand the "env-entry/" folder.
11. Expand the folders associated with the environment entries that must change for your network environment and application server installation. See the table above for the meaning of each environment property.
12. Double click on an "env-entry-value" to change its value.
13. After you've changed the necessary environment entries, exit the Registry Editor.

Now you're ready to exercise the Bank application. Proceed to Running the Application.

GUI-based Deployment

Two approaches to using the Deployment Tool are described:

Import Pre-existing EAR File to quickly deploy the Bank application. None of the application assembly steps are covered by this section. On average, this approach will take 15 minutes.

or

Assemble Bank Application to learn how to use Deployment Tool to assemble and deploy the Bank application. On average, this approach will take from 30 to 60 minutes.

Import Pre-existing EAR File

Import the EAR File

1. Launch the Deployment Tool.

UNIX:

Execute install_dir/ias/bin/deploytool

Windows:

Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool

• In the startup dialog, select "Browse for more applications" to find the bank.ear file.
• Navigate to ias/ias-samples/bank/ and open the bank.ear file.
• Select Component View
• Click on the file name to expand the EAR file.

Modify Environment Settings

1. Expand the bankEjb.jar module.
2. Select BankService EJB, right click and select Edit Descriptor.
3. Select the Environment tab.
4. Modify the environment entries to suit your installation environment. The default domain of "iplanet.com" will need to be changed to match your domain name.  The default HOST and PORT values might also need to be modified for your installation. See the BankService EJB Environment Settings section for information on these properties.
5. Save the environment changes by closing the closing the descriptor window.
6. Select the bank EAR module and select File->Save to save the descriptor changes to the EJB JAR and EAR files.

Assemble Bank Application

• Compile Application Sources
• Create bankEjb.jar Module
• Create bank.war Module
• Assemble bank.ear
• Deploy Application

Compile Application Sources

Create bankEjb.jar Module

Insert EJBs and Supporting Classes

Create the new directory install_dir\ias\ias-samples\bank\assemble\ outside the Deployment Tool. You will assemble the application into JAR files and save them to this directory.

UNIX: Execute install_dir/ias/bin/deploytool&

Windows: Programs->iPlanet Application Server 6.0->iAS Deployment Tool

• In the startup dialog, select New EJB Application (.jar file)
• Alternatively, if Deployment Tool is already started, select File -> New.
• Click on EJB JAR Module.
• Enter "bankEbj.jar" as the archive file name.
• Click on Browse to navigate to the directory install_dir\ias\ias-samples\bank\assemble\
• Click on OK to exit the dialog window.
• The EJB JAR module appears in the EJB pane of the Deployment Tool window.
• Click on Component View to see only the name of the EJB JAR module without the directory path.

• Select the EJB JAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
• Choose the path install_dir\ias\ias-samples\bank\build\lib\classes. (Merely select the "classes" folder. Do not drill down into the classes folder).
• In the left hand pane, select all classes except for the servlet class files. Click on the double arrows (>>) to move the selected classes into right side of the dialog window. For Bank, we're placing all of the class files save for servlet classes in the EJB JAR module and only servlet classes in the WAR module.
• Click on Resolve to determine if any of the included classes depend on classes that are not part of the EJB JAR module. (You'll notice that the classes change from red to blue as they are resolved. Any files remaining as red are dependent on classes not included in the EJB JAR module. The unresolved references do not inhibit you from adding the classes to the EJB JAR module.) You might encounter a warning of unresolved class dependencies. Click on Resolve again to attempt the resolution again.
• Click on Insert to add the classes to the EJB JAR module.
• Since you selected Component View, you'll see the EJB listed in the EJB module window. Deployment Tool introspects the classes to determine the EJBs, if any, contained in the inserted classes.
• Click on File View to see the complete list of files added to the module.

Modify EJB Names

• For each bean:
• select the bean, right click and select Edit Descriptor
• modify the Bean Name based on the names specified in the table below.
• after modifying the name, click on the X in the upper right hand corner of the descriptor window to close the descriptor and save the name change. (Note that the name of the EJB in the EJB Modules window will not change until the EJB JAR module is closed and reopened).
• After renaming all beans, select the EJB JAR file, and select File->Close to save and close the EJB JAR file. You will notice that EJB stubs and skeletons will be created during the save operation.
• Reopen the EJB JAR file by selecting File->Open.
• Click on component view to see the renamed beans.

Modify Deployment Descriptor Settings for BankService

• Click on Component View.
• Select the BankService, right mouse click and select Edit Descriptor.
• Adjust the EJB descriptor window size to see all of the settings.
• Note the unique GUID (Globally Unique IDentifier) assigned to the EJB. This ID is used by the application server to manage the EJB as a unique component throughout the application server.
• The next steps in this section lead you through modifications to the EJB descriptor.

• Set Transaction Management Type to Bean.
• Set State Management Type to Stateless

This EJB requires several environment settings to be declared in advance. Select the Environment Tab to add the following variables. You might have to modify the bold values according to your environment and installation options.
 

Key Name	Type	Value
GROUP_DN	String	cn=BankUser, cn=BankApp, ou=Groups, o=iplanet.com
AUTH_PASSWORD	String	admin
AUTH_DOMAIN	String	uid=admin, ou=Administrators, ou=TopologyManagement, o=NetscapeRoot
HOST	String	localhost
PORT	Integer	389
USER_ROOT	String	ou=People, o=iplanet.com

4. Resource References

In the References Tab, enter the following data under the References to Resources:

 

Resource Name	Resource Class	Authorization	JNDI Name
BankDataSource	javax.sql.DataSource	Container	jdbc/bank/BankDB

5. Close the Descriptor for the EJB

Now we can close the EJB descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

Modify Deployment Descriptor Settings for CustomerService

• Click on Component View.
• Select the CustomerService, right mouse click and select Edit Descriptor.

• Set Transaction Management Type to Bean.
• Set State Management Type to Stateless

In the References Tab, enter the following data under the References to Resources:

 

Resource Name	Resource Class	Authorization	JNDI Name
BankDataSource	javax.sql.DataSource	Container	jdbc/bank/BankDB

Now we can close the EJB descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

Save and close bankEjb.jar

• Before closing the EJB JAR file, you might find it useful to double check your settings against the previous instructions.
• Select the bankEjb module in the EJB Modules window.
• Select File->Close to save and close the bankEjb.jar file.

Create bank.war Module

Identify the Content for WAR File

• In the startup dialog, select New Web Application (.war file)
• Alternatively, if Deployment Tool is already started, select File -> New.
• Click on Web Application.
• Enter "bank.war" as the archive file name.
• Click on Browse to navigate to the directory install_dir\ias\ias-samples\bank\assemble\
• Click on OK to exit the dialog window.
• The WAR module appears in the Web Applications pane of the Deployment Tool window.
• Click on Component View to see only the name of the WAR module without the directory path.

• Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
• Choose the path install_dir\ias\ias-samples\bank\build\lib\classes\com\iplanet\ias\bank\servlets
• Click on the double arrows (>>) to move all servlet classes into right side of the dialog window.
• Click on Resolve to determine if any of the included classes depend on classes that are not part of the WAR module.
• Click on Insert to add the classes to the WAR module.
• Click on File View to see the complete list of files added to the module.

• Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
• Navigate to path install_dir\ias\ias-samples\bank\src\docroot directory.
• Press Shift key, then select all .jsp, .js and .html files.
• Click on the double arrows (>>) to move these files into right side of the dialog window.
• Click on Resolve to modify the location of these files relative to the root of the WAR file.
• Select al files using the Shift key.
• Set the Update Destination Path to blank since the application requires that these files be located at the root of the WAR module. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
• Click on Insert to close the insert dialog window and to add the files to the WAR.

• Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
• Navigate to path install_dir\ias\ias-samples\bank\src\docroot\images directory.
• Press Shift key, then select all .gif and .jpg image files.
• Click on the double arrows (>>) to move these files into right side of the dialog window.
• Click on Resolve to modify the location of these files relative to the root of the WAR file.
• Select al files using the Shift key.
• Set the Update Destination Path to images/ since the application requires that these files be located under this directory relative to the root of the WAR module. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
• Click on Insert to close the insert dialog window and to add the files to the WAR.

Modify Names of All Servlets

• For each servlet:
• select the servlet, right click and select Edit Descriptor
• modify the Servlet Name based on the names specified in the table below.
• after modifying the name, click on the X in the upper right hand corner of the descriptor window to close the descriptor and save the name change. (Note that the name of the Servlet in the Web Applications window will not change until the WAR module is closed and reopened).
• After renaming all beans, select the WAR file, and select File->Close to save and close the WAR file.
• Reopen the WAR file by selecting File->Open.
• Click on Component View to see the renamed beans

 

Initial Name	New Name
For all servlets except for the following 3 names:  xyzServlet	xyz e.g. "BankServlet" becomes "Bank"
TransferDetailsServlet	ShowTransferDetails
ViewTransactionServlet	ViewTransactions
BankLoginServlet	Login

Modify Web Application Descriptor

As described for the bankEjb.jar, in the following paragraphs, the title gives the tab name, where you have to enter the data given below.

1. General Tab

 

Name:	bank
Distributable	checked
Session Timeout (seconds):	400
Authentication Type	form
Login Form	/bank/index.jsp
Login Error Page	/bank/LoginError.jsp

 

Distributed Session	checked
Timeout (seconds):	400
Timeout Type	Since last access
Data Synchronization	Distributed

EJB References:
 

Reference	Bean Type	Linked to Bean	Bean Home Interface	Bean Remote Interface
BankServiceBean	Session	BankService	com.iplanet.ias.bank.bank.IBankServiceHome	com.iplanet.ias.bank.bank.IBankService
CustomerServiceBean	Session	CustomerService	com.iplanet.ias.bank.customer.ICustomerServiceHome	com.iplanet.ias.bank.customer.ICustomerService

Security Roles

5. Security Tab

Define Resource Collections

Access Control for Resource Collections

Save and close bank.war

• Before closing the WAR file, you might find it useful to double check your settings against the previous instructions.
• Select the WAR module in the Web Applications window.
• Select File->Close to save and close the bank.war file.

Assemble bank.ear

• In the startup dialog, select New J2EE Application (.ear file)
• Alternatively, if Deployment Tool is already started, select File -> New.
• Click on J2EE Application.
• Enter "bank.ear" as the archive file name.
• Click on Browse to navigate to the directory install_dir\ias\ias-samples\bank\assemble\
• Click on OK to exit the dialog window.
• The EAR file appears in the J2EE Applications pane of the Deployment Tool window.
• Click on Component View to see only the name of the EAR without the directory path.

• Select the bank EAR entry.
• Right click, select Insert Files.
• Navigate to the install_dir\ias\ias-samples\bank\assemble\ directory.
• Select both the EJB JAR and WAR files.
• Click on the double arrows (>>) to move these files into right side of the dialog window.
• Click on Resolve to modify the location of this file relative to the root of the EAR file.
• Select all files using the Shift key.
• Set the Update Destination Path to blank since the J2EE modules should appear at the root of the EAR file. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
• Click on Insert to close the insert dialog window and to add the files to the EAR.

• Select the EAR and Edit Descriptor.
• Select Security Roles and add the following entries:

 

Role Name	Description
BankUser	customers
BankAdmin	administrators

Next, we need to set the context root of the web application. This value will appear in URLs that access web application components. For example, in the URL http://localhost/NASApp/bank/Login the "bank" value is the context root of the web application.

• Select EAR module, double click and select the Context Root tab.
• Set the Context Root to "bank".
• Close the descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

• Select the EAR file in the J2EE Applications window.
• Select File->Close to save and close the EAR file

Deploy the Application

If you followed the assembly instructions, then bank.ear is opened in Deployment Tool. If you opened the pre-existing EAR file, you are working with install_dir\ias\ias-samples\bank\bank.ear. If you are following the "Create EAR File from Scratch" instructions, you are modifying install_dir\ias\ias-sample\bank\assemble\bank.ear.

If you entered all deployment information manually, you can skip the following steps 1 to 3, because you have entered this information already.

1. Select the bank.ear file under the J2EE Application window.

2. Select File -> Deploy

3. If you have not already registered a target application server, do so now by clicking on the Register button. Enter the host name, administrative port number and username/password for the target application server. Otherwise, select a pre-registered target server.

Note: You may authorize additional users to deploy applications to an application server server by using the application server's Administrative Console. See the Security settings tab in the Administrative Console.

5. Click on Deploy to start the deployment process.

6. Role Mapping for Bank: If you read in the pre-built EAR file, the mapping between logical J2EE roles and the groups and users found in the directory server has already been made. In this case, simply click on OK to accept the pre-assigned mappings. If you are assembling the application from scratch, you will need to resolve the J2EE roles to groups and/or users found in the directory server.

6a) Click on "BankAdmin" and click on Edit to map this role to the BankAdmin group.

6b) Do the same for the "BankUser" role (which maps to the group named BankUser) and click OK to accept the role assignments.

Verifying Registration

1. Start the Application Server Admin Tool

UNIX:

install_dir/ias/bin/ksvradmin

Windows:

Start->Programs->iPlanet Application Server->iAS Administration Tool

2. Connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the application server administrator's password and click on OK.
3. Select the server name (default name of iAS1) and select the Application button in the top right hand corner of the window to see the applications registered in this instance of the application server.
4. You should see several folders for the "bank" J2EE application. The "bank" folder with the world icon represents the web application module while the "bankEjb" folder represents the EJB module packaged as part of the Bank application.

1. Execute kregedit to start the application server's Registry Editor GUI.
2. Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.
3. Browse the J2EE-Application/ tree and look for the "bank" application.
4. Expand the "bank" folder and explore this portion of the directory tree.
5. Now open the J2EE-Module/ tree and look for the "bank" web application module entry and the "bankEjb" EJB module entry.
6. Expand each of these folders and explore their contents.
7. Once you find the GUID associated with each EJB in the Bank application, you can navigate through the SOFTWARE/iPlanet/Application Server/ClassDef/ folders to find out more details on each EJB. Expanding the matching GUID folders under the ClassDef folder will show you the detailed settings associated with each EJB. Many of these settings appear in the XML deployment descriptors for EJBs.

Running the Application

Start the application either by clicking here or, if you've deployed the web server on a separate machine, by accessing:

http://<web server hostname>:<port>/NASApp/bank/Login

1. After the login page appears, login as one of the bank customers listed on the login page.

2. Explore the available services. Transfer money from one account to another, view balances, etc.

3. Logout and log back in as a Customer Service Representative (bankrep/bankrep).

4. Explore the different set of services available to a Customer Service person.

• Search for customer information. Note that search operations are case sensitive.
• Update customer information.
• Create a new customer account: Once you've created a new customer account, you will see that a user has been added to the directory server. Open up the Directory Server console and search the directory for your newly created user.
• Remove the newly added customer. You will see the customer removed from the directory server as well.

Note that although the application supports adding new customers, there is no easy means of logging in as the newly added customer. Since there is no password data entry field in the new customer form, you will not know the password assigned to this user. You should be able to go into the directory server, modify the user's password and then try to login to the Bank application.

To explore the application further by deploying it to a cluster, performance testing the application, etc., see the list of additional topics to explore.

Troubleshooting

As part of your troubleshooting efforts, ensure that you first review the General Troubleshooting section to learn how to view logs files.

Problem: When accessing the Bank application login page, a login dialog window pops up in the browser.

• Probable cause: Browser has stale session information from previous failed access attempt.
• Solution: Restart browser.

• Probable cause: Database driver has not been configured.
• Solution: Ensure that you followed the database driver setup steps.

• Probable cause: Directory connection information contained in the J2EE deployment descriptor of the BankService EJB was not updated.
• Solution: See the instructions above for modifying the domain name, LDAP port number, etc. to suit your environment.

Using Third Party JDBC Drivers

1. Register the JDBC Driver with the Application Server
2. Reregister the JDBC Data Source for the Bank Application
3. Restart the Application Server

See the iPlanet Application Server SP3 Release Notes for a complete description of registering third party JDBC drivers in the application server. The basic steps are as follows:

UNIX:

Execute the db_setup.sh script to register a third party JDBC driver.

a) Enter the application server installation root directory:

Please enter the iAS installation root directory:
/usr/iplanet/ias6

b) Select option 2, Third Party JDBC Drivers

Do you want to use third party JDBC drivers or native drivers.
1. Native drivers
2. Third party jdbc drivers
To accept the default shown in brackets, press the Enter key.

Select the component you want to install (1/2) [1]:
(SELECT OPTION 2 FOR JDBC )

c) Enter a logical name for the driver. This name must be supplied in the next step when configuring the datasource XML file.

d) Enter the driver class name.

e) Enter the fully qualified path of the driver JAR or ZIP file.

f) Enter the path for the driver's native libraries. (Optional: applies to Type 2 drivers only)

Execute the jdbcsetup.exe program to register a third party JDBC driver.

a) Enter a logical name for the driver. This name must be supplied in the next step when configuring the datasource XML file.

b) Enter the driver class name.

c) Enter the fully qualified path of the driver JAR or ZIP file.

d) Enter the path for the driver's native libraries. (Optional: applies to Type 2 drivers only)

Modify the supplied datasource XML files to suit your driver and database connection requirements. The logical driver name you assigned to your third party driver in the driver registration instructions must be the same name as set in the <DRIVER-TYPE> tag of the datasource XML file. Although an example is provided for the Oracle Type 4 JDBC driver, you should be able to use any of the supported JDBC drivers listed in the iPlanet Application Server Service Pack 1 Release Notes. See the following sample:

ias-samples/bank/src/schema/BankDB-ora-type4.xml

<ias-resource>
<resource>
<jndi-name>jdbc/bank/BankDB</jndi-name>
<jdbc>
<driver-type>ora-type4</driver-type>
<database-url>jdbc:oracle:thin:@192.18.117.186:1521:orcl</database-url>
<username>bank</username>
<password>bank</password>
</jdbc>
</resource>
</ias-resource>

After modifying the datasource XML files to suit your database connection requirements, run the iasdeploy regdatasource command against each file to register the datasource in the application server. For example,

iasdeploy regdatasource BankDB-ora-type4.xml

3. Restart the Application Server

After restarting the application server to pick up the third party database driver and datasource changes, restart your browser and rerun the sample application.

Compiling and Assembling the Application

To easily recompile, assemble and deploy the application, see the Sample Application Build Facility document for details on using a build facility to quickly perform these tasks.

To rebuild the entire sample from scratch, you can simply execute:

build all

From the directory install_dir/ias/ias-samples/bank/src/

On UNIX, you might need to modify your PATH to ensure that install_dir/ias/bin is included to pickup the build script.

Clustering the Bank Application

To ensure that Bank makes the most use of a cluster environment, we must make sure that it is configured with these key settings:

• The web application is configured to support distributed sessions. This means that HttpSession data will be made available to each application server instance in the cluster.
• All servlets are configured as "sticky" so as to ensure that all web requests associated with the same user session get directed to the exact same JVM (kjs). Since the distributed setting implies that session is available across the cluster, it is generally more efficient to direct web requests associated with a session back to the same JVM on which the session was instantiated.

Multiple Web Server Instances Require Domain Setting in Web App Descriptor

JDBC Data Sources Must be Registered on Each App Server Instance

Application Must be Registered on Each App Server Instance

Next Steps

1. Validate and exercise the two machine cluster as described in the cluster servlet sample.

2. Run setup_ora.sh/.bat file on each server in the cluster to register the JDBC datasource with each application server instance.

3. Populate the directory server with the Bank users. Since the directory server is shared in the sample cluster, you need to perform the population step only once.

4. If you intend to distribute web requests from the browser across the two different web server instances, you must set the domain field of the web application. See the Cluster Servlet sample setup instructions for details on how to modify this setting.

5. Since a the BankService EJB relies on environment settings to point it to the appropriate directory server, you must modify the environment settings such that the EJB points to the common directory server used across the cluster. The default host name of localhost will not work properly when deploying Bank to multiple machines in a cluster.

6. Register the application on each server in the cluster. Since the application server instances share a directory server for the registration of the applications, it is very important that you register the application across the server instances in a sequential manner. See the Cluster Servlet sample deployment section for details.

When exercising the application in a cluster, use multiple browsers on multiple machines to observe how new sessions are load balanced across different JVMs and how each session "sticks" to the JVM on which it was instantiated.

Exercise the same failure scenarios as those used in the Cluster Servlet sample against the Bank sample.

Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved.