Local JDBC Transaction Application
iPlanet^TM Application Server J2EE Samples

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

The first page of the application is an HTML form which allows the user to enter the following:

1. Source Account ID - the Account Number of the Source Account from which the funds should be withdrawn.
2. Recipient Account ID - the Account Number of the Recipient Account to which the funds should be deposited.
3. Transfer Amount - the amount of money to be transferred.

Figure 1 - Local JDBC Transaction Input Form

When the user clicks the Transfer Funds button, the LocalJdbcTransactionServlet is invoked to perform the following transaction:

1. Get the account balance of the Source Account and Recipient Account
2. Withdraw the transfer amount from the Source Account
3. Deposit the transfer amount to the Recipient Account
4. Get the new account balance of the Source Account and Recipient Account
5. If the Source Account balance is negative, the Source Account does not have enough funds to transfer and the transaction must be rolled back. Otherwise, if the Source Account balance is not negative, the Source Account has enough funds to transfer and the transaction will be committed.

Architecture and Process Flow

Figure 3 - Local JDBC Transaction

The LocalJdbcTransactionServlet locates the LocalBankServiceEJBbean which actually performs the transaction. The transaction involves the following steps:

(1) Get a database connection to the Local Bank data source using JNDI.

javax.sql.DataSource ds = new InitialContext( ).lookup( "java:comp/env/jdbc/transactions/LocalBankDB" );
java.sql.Connection m_connection = ds.getConnection( );

The sample application performs this step in the LocalBankAccount.getDBConnection( ) method. It is important to note that for database statements to be in the same transaction, they must be executed using the same database connection.

(3) Withdraw the transfer amount from the Source Account by deducting the amount from its balance. This is implemented in the samples.transactions.components.LocalBankAccount.withdraw( amount ) method.

(4) Deposit the transfer amount to the Recipient Account by adding the amount to its balance. This is implemented in the samples.transactions.components.LocalBankAccount.deposit( amount ) method.

(5) Get the updated balance of the Source Account. If the balance is not negative,  the transaction can be completed and all database updates within the transaction should be committed. This is implemented using the java.sql.Connection.commit( ) method. On the other hand, if the balance is negative, this means that the Source Account does not have enough funds to transfer. When this exception or any other exception occurs, the transaction cannot be completed -- the transaction must be rolled back so that the database updates will not take effect. This is implemented using the java.sql.Connection.rollback( ) method.

The Local JDBC Transaction is implemented in the samples.transactions.local.jdbc.ejb.LocalBankServiceEJB.transferFunds( ) method.

Setting Up the Environment

Configuring the Database

1. Register Database Driver
2. Create Database User
3. Create and Populate Database Tables and Register the Data Source

1. Register Database Driver

This section describes how to register an underlying database driver with iPlanet in the event that a driver was not registered during installation of the application server. The following instructions address only the registration of the database driver. A subsequent section of this document describes how to populate the database tables and register the data sources required by the sample.

This sample uses a local transaction. Therefore, it can be deployed using either one of these types of database drivers:

iPlanet Type 2 Database Driver

Third-party Type 4 Database Driver

Registering an iPlanet Type 2 Database Driver

1. Determine if the iPlanet Type 2 Driver is Registered

On Windows, the application server automatically detects whether or not drivers for any of the supported databases are available. If a suitable driver is present, the driver will be automatically registered during installation of the application server.

On UNIX, if during installation, either "Typical" or "Express" options were selected, JDBC database drivers will not be registered with the application server. If you are unsure as whether or not the client driver was registered, use the application server administrative tool to determine the drivers registered with the application server.

1. Start the application server administrative tool:

install_dir/ias/bin/ksvradmin

2. If the application server instance is not listed automatically, connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the iPlanet Application Server 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. 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 with the application server. Go to the next section to register the driver.

2. Register iPlanet Type 2 Driver if Necessary

For UNIX, if the driver has not been registered (you see the red X in the Admin Tool), then you must use the db_setup.sh command to register the driver with iPlanet.

UNIX: Type 2 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 iPlanet Type 2 native client driver. The default iPlanet installation root directory is /usr/iplanet/ias6.

4. For this sample, you do not need to register a Resource Manager. (Resource Manager setup is required only in support of distributed and possibly heterogeneous transactions relying on the transaction manager built into iPlanet Application Server).

5. Restart the application server using either the Application Server Administrative Tool or the iascontrol stop and iascontrol start commands. Refer to the Getting Started section for more information.

6. Verify that the database driver was registered, by going through the steps in the previous section, Determine if the iPlanet Type 2 Driver is Registered.

Registering a Third-party Type 4 Database Driver

1. Determine if Type 4 Driver is Registered

If you are not sure whether or not the Type 4 driver is registered, use the application server's Administrative Tool to determine the status of JDBC drivers.

1. Start the Admin Tool

install_dir/ias/bin/ksvradmin

2. Connect to your application server instance by selecting File->New->Server. Click on Local Host 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 JDBC driver settings.

4. If you don't see the JDBC driver entry of interest under the External JDBC Drivers folder, then you need to run the db_setup.sh script to register the JDBC driver in the application server. Go to the next section to register the driver.

On Windows, the application server automatically detects whether or not drivers for any of the supported databases are available. If a driver is present, the driver will be automatically registered during installation of the application server.

2. Register Type 4 Driver if Necessary

For UNIX, if the driver has not been registered, then you must use the db_setup.sh command to register the driver in the application server.

UNIX: JDBC 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 (db_setup.sh):

install_dir/ias/bin/db_setup.sh

3. Enter the application server installation root directory.

4. You will be asked what driver you want to use.

Do you want to use third party JDBC drivers or native drivers.
1. iPlanet Type 2 JDBC 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]:

  Enter 2 for Third party JDBC Drivers.

5. Enter the number of drivers you want to configure.

6. Enter a logical name for the JDBC driver. This name will be used in the next step when configuring the Data Source XML file.

7. Enter the driver's class name.

     For example, for Oracle, enter oracle.jdbc.driver.OracleDriver
     For example, for Sybase, enter com.sybase.jdbc2.jdbc.SybDriver

8. Enter the fully qualified path of the driver's JAR or ZIP file.

    For example, for Oracle, enter <ORACLE_HOME>/jdbc/lib/classes12.zip
    For example, for Sybase, enter <jConnect install>/classes/jconn2.jar

9. You will be asked to enter the Third Party Native Driver Directory. Do not enter anything because this applies only to Type 2 drivers.

10. Restart the application server using the iascontrol stop and iascontrol start commands. Refer to the Getting Started section for more information.

11. Verify that the JDBC Driver was registered, by going through the steps in the previous section, Determine if Type 4 Driver is Registered.

Windows: JDBC Driver Registration

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

1. Enter a logical name for the driver. This name will be used when configuring the Data Source XML file.

2. Enter the driver class name.

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

4. Don't enter anything for driver's native libraries. (Optional: applies to Type 2 drivers only)

2. Create Database User

Before you can create and populate the database tables, it is necessary to define the RDBMS user for the sample application. This RDBMS user will own the tables created for the sample application. The following example shows how to create a new user called localbank using the Oracle SQL Plus utility. It is mandatory that the localbank user be used to create the database tables for this sample application.

To define a new Oracle user:

1. Use SQL Plus and define the Oracle user name and password.

SQL > create user localbank identified by localbank;

The first localbank is the user name and the second localbank is the password.

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

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

Now that you've identified the user for the application tables, the next step is to create and populate the tables.

3. Create and Populate Database Tables

A script named setup_<rdbms type>.sh for UNIX (setup_<rdbms_type>.bat for Windows) configures the database tables to be used by the sample application. (Replace <rdbms_type> with ora for Oracle, syb for Sybase). The script performs the following steps:

1. Registers the database as an iPlanet data source.
2. Verifies connectivity to the specified database.
3. Creates the tables required by the sample application and populates the tables.


Go to the install_dir/ias/ias-samples/transactions/local/jdbc/src/schema directory and find the appropriate file that corresponds to the database of interest.

The following instructions assume that you have either the Oracle sqlplus facility or the Sybase client software loaded on your system.

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

2. Run setup_<rdbms type>.sh on UNIX or setup_<rdbms type>.bat on Windows.

Oracle Table Creation and Population

For example, with Oracle, run the setup_ora.sh script as shown below:
 

setup_ora.sh <TNS Name> localbank localbank

Where:

<TNS Name> is the Oracle service or TNS name which maps to the appropriate Oracle database instance.

localbank and localbank 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.
 

Sybase Table Creation and Population

For example, with Sybase, run the setup_syb.sh script with the following arguments:
 

setup_syb.sh <Server Name(port:PORT)> <database> <dbusername> <dbpassword>

setup_syb.sh SYBIAS(port:11920) db1 localbank localbank

3. Register Datasource

The datasource needs to be registered to the iPlanet Application Server. Go to the directory install_dir/ias/ias-samples/transactions/local/jdbc/src/schema. Make necessary changes to the XML datasource file. Here is an example of a datasource file with Oracle as the database (localbank-ias-ora-type2.xml):

<ias-resource>
<resource>
<jndi-name>jdbc/transactions/local/LocalBankDB</jndi-name>
<jdbc>
<datasource>iassample.world</datasource>
<database>dummy</database>
<username>localbank</username>
<password>localbank</password>
<driver-type>ORACLE_OCI</driver-type>
</jdbc>
</resource>
</ias-resource>

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

For example, to use Oracle,

1. Go to the directory
install_dir/ias/ias-samples/transactions/local/jdbc/src/schema.

2. Execute the following command to register the JDBC datasources:

iasdeploy regdatasource localbank-ias-ora-type2.xml.xml

Now that you've registered the JDBC driver and datasource for the sample, you're ready to deploy the application.

Deploying the Application

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

Graphical User Interface (GUI)-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the sample application. Alternatively, you can also assemble the application from scratch and deploy it using the Deployment Tool.

Command-Line Interface (CLI) Deployment

The transactions-localjdbc.ear file is an Enterprise Archive (EAR) file that contains the Web Archive (WAR) and EJB JAR files for the application. Within each of these files reside the XML deployment descriptor files, application class files, JSPs and other content required by the application.

Deploying the pre-built transactions-localjdbc.ear file is simple.

1. Go to the root of the Local JDBC Transaction Sample directory:

install_dir/ias/ias-samples/transactions/local/jdbc/

install_dir/ias/bin/iasdeploy deployapp transactions-localjdbc.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 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 install_dir/ias/JAR/directory.

expands the content of the J2EE modules to the install_dir/ias/APPS/transactions-localjdbc directory.

Now that the application has been deployed, proceed to Verifying Registration.

Graphical User Interface (GUI) Deployment

Two approaches to using the Deployment Tool are described:

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

or

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

GUI: Import Pre-existing 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, click Browse to find the transactions-localjdbc.ear file.
• Navigate to ias/ias-samples/transactions/local/jdbc and open the transactions-localjdbc.ear file.
• Select Component View

GUI: Assemble Application from Scratch

1. Compile application sources.
2. Create JAR file.
3. Create WAR file.
4. Create EAR file.

1. Compile Application Sources

To compile the application sources, do the following from the command line:

1. Change directory to install_dir/ias/ias-samples/transactions/local/jdbc/src
2. Execute the build compile command.

1. Create assembly location:

Create the directory install_dir/ias/ias-samples/transactions/local/jdbc/assemble from the command line. You will assemble the application into JAR files and save them to this directory.

2. Launch the Deployment Tool:

UNIX: Execute install_dir/ias/bin/deploytool&

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

3. Create transactions-localjdbcEjb.jar:

1. In the startup dialog, select New EJB Application (.jar file)
2. Alternatively, if Deployment Tool is already started, select File -> New.
3. Click on EJB JAR Module.
4. Enter transactions-localjdbcEjb.jar as the File Name.
5. Click on Browse to navigate to this directory:

install_dir/ias/ias-samples/transactions/local/jdbc
6. Select assemble and click on OK to exit the dialog window.
7. The EJB JAR module appears in the EJB pane of the Deployment Tool window.
8. Click on Component View to see only the name of the EJB JAR module without the directory path.

4. Insert all class files needed in the transactions-localjdbcEjb.jarfile:

1. Select transactions-localjdbcEjb from the EJB Modules window. Right click and select Insert (Alternatively, select the module, select Edit->Insert)
2. Navigate to this directory:

install_dir/ias/ias-samples/transactions/local/jdbc/build/classes/samples/transactions/components
3. In the left hand pane, select all classes. Click on the right arrow (>) to move the selected classes into right side of the dialog window.
4. Navigate to this directory:

install_dir/ias/ias-samples/transactions/local/jdbc/build/classes/samples/transactions/local/jdbc/ejb
5. In the left hand pane, select all classes. Click on the right arrow (>) to move the selected classes into right side of the dialog window.
6. Click on Resolve to determine if any of the included classes depend on classes that are not part of the EJB JAR module
7. Click on Insert to add the classes to the EJB JAR module.
8. Since you selected Component View, you'll see the EJB listed in the EJB module window.

5. Edit the EJB Descriptor.

1. Expand the transactions-localjdbcEjb folder from the EJB Modules window.
2. Select the LocalBankServiceEJB bean, right click and select Edit Descriptor.
3. Set the EJB Name to samples.transactions.local.jdbc.ejb.LocalBankServiceEJBto insure uniqueness.
4. Set the State Management Type to Stateless.
5. Select the References tab from the EJB Descriptor window.
6. Click the Add button in the References to resource factories section.
7. Enter the following information:

Resource Name	Description	Resource Class	Authorization	JNDI Name
jdbc/transactions/LocalBankDB	Local Bank Database	javax.sql.DataSource	Container	jdbc/transactions/local/LocalBankDB

Close the EJB Descriptor window by clicking on the X in the upper right hand corner of the window. Click on Yes when asked to save the changes.

6. Save and close the JAR file.

1. Select the transactions-localjdbcEjb file from the EJB Modules window.

Select File->Close from the menu bar and click on Yes when asked to save the changes.

3. Create the WAR File

1. Create a new WAR file.

1. In the startup dialog, select New Web Application (.war file). Alternatively, if Deployment Tool is already started, select File -> New.
2. Click on Web Application.
3. Enter transactions-localjdbc.war as the File name.
4. Click on Browse to navigate to this directory:

install_dir/ias/ias-samples/transactions/local/jdbc
5. Select assemble and click on OK to exit the dialog window.
6. The WAR module appears in the Web Applications pane of the Deployment Tool window.
7. Click on Component View to see only the name of the WAR module without the directory path.

2. Insert all class files needed in the WAR file.

1. Select transactions-localjdbc from the Web Applications window. Right click and select Insert. Alternatively, select Edit->Insert from the menu bar.
2. Navigate to this directory: install_dir/ias/ias-samples/transactions/local/jdbc/build/classes/samples/transactions/local/jdbc/servlet
3. Select all classes and click on the right arrow (>) to move the classes into right side of the dialog window.
4. Click on Resolve to determine if any of the included classes depend on classes that are not part of the WAR module.
5. Click on Insert to add the classes to the WAR module.

3. Add all JSP and HTML files needed in the WAR file.

1. Select transactions-localjdbc from the Web Applications window. Right click and select Insert. Alternatively, select Edit->Insert from the menu bar.
2. Navigate to path install_dir/ias/ias-samples/transactions/local/jdbc/src/docroot
3. Press Shift key, then select all files.
4. Click on the right arrow (>) to move these files into right side of the dialog window.
5. Click on Resolve to modify the location of these files relative to the root of the WAR file.
6. For each file: click the file name, set the Update Dest. 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.
7. Click on OK to close the Resolve dialog window.
8. Click on Insert to close the insert dialog window and to add the files to the WAR file.

4. Edit the Web Application Descriptor.

1. Select the transactions-localjdbc file from the Web Applications window. Right click and select Edit Descriptor. Alternatively, select Edit->Edit Descriptor from the menu bar.
2. Click on the References tab.
3. Click the Add button in the References to EJBs defined elsewhere section.
4. Enter the following information:

 

Reference	Linked to Bean	Bean Type	Bean Home Interface	Bean Remote Interface
ejb/samples.transactions.local.jdbc.ejb.LocalBankServiceEJB	samples.transactions.local.jdbc.ejb.LocalBankServiceEJB	Session	samples.transactions.local.jdbc.ejb.LocalBankServiceHome	samples.transactions.local.jdbc.ejb.LocalBankService

Make sure you hit the Return or Enter key after each entry.
 

5. Click on X in the upper right hand corner of the Web App Descriptor window in order to close it. Click on Yes when asked to save the changes.

5. Save and close the WAR file.

1. Select the transactions-localjdbc file from the Web Applications window.
2. Select File->Close from the menu bar and click on Yes when asked to save the changes.

4. Create the EAR File

1. Create a new EAR file:

1. In the startup dialog, select New J2EE Application (.ear file). Alternatively, if Deployment Tool is already started, select File -> New.
2. Click on J2EE Application.
3. Enter transactions-localjdbc.ear as the File name.
4. Click on Browse to navigate to this directory:

install_dir/ias/ias-samples/transactions/local/jdbc
5. Select assemble and click on OK to exit the dialog window.
6. The EAR file appears in the J2EE Applications pane of the Deployment Tool window.
7. Click on Component View to see only the name of the EAR without the directory path.

2. Add JAR and WAR files:

1. Select transactions-localjdbc from the J2EE Applications window. Right click and select Insert.
2. Navigate to the directory install_dir/ias/ias-samples/transactions/local/jdbc/assemble
3. Select both the transactions-localjdbcEjb.jar and transactions-localjdbc.war files.
4. Click on the right arrow (>) to move these files into right side of the dialog window.
5. Click on Resolve to modify the location of this file relative to the root of the EAR file.
6. For each file: Set the Update Dest. Path to blank since the J2EE modules should appear at the root of the EAR file. Click on Update to modify the relative location.
7. Click on OK to close the Resolve dialog window.
8. Click on Insert to close the Insert dialog window and to add the files to the EAR file.

3. Set Context Root for Web Application

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/transactions-localjdbc/index.html the transactions-localjdbc value is the context root of the web application.

1. Select the EAR file from the J2EE Applications window. Right click and select Edit Descriptor
2. Under the Context Root tab, set both the web application (WAR) name and the context root to transactions-localjdbc
3. Close the Application Descriptor window by clicking on the X in the upper right hand corner of the window. Click on Yes when asked to save the changes.

4. Save the EAR file.

1. Select the transactions-localjdbc EAR file from the J2EE Applications window.
2. Select File->Save to save the EAR file.

GUI: Deploy the Application

1. Select the transactions-localjdbc EAR file from the J2EE Applications 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.

4. Click on Overwrite modules in case you are repeating the deployment step.

5. Click on Deploy to start the deployment process.

6. Now the file transfer and application registration begins. See the Deploy tab for the status of the deployment. The deployment may take several minutes to complete. Once the status of the deployment changes to Success, proceed to the next step.

7. Restart the application server using the iascontrol stop and iascontrol start commands.

Verifying Registration

1. Start the Application Server Admin Tool

UNIX: install_dir/ias/bin/ksvradmin

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

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 transactions-localjdbc J2EE application. The transactions-localjdbc folder with the world icon represents the web application module while the transactions-localjdbcEjb folder represents the EJB module that is packaged as part of the application.

To see more details associated with the application, you can use the Registry Editor tool:

1. Launch the Registry Editor: install_dir/ias/bin/kregedit
2. Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.
3. Browse the J2EE-Application/ tree and look for the transactions-localjdbc application.
4. Expand the transactions-localjdbc folder and explore this portion of the directory tree.
5. Now open the J2EE-Module/ tree and look for the transactions-localjdbc web application module entry and the transactions-localjdbcEjb 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 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

1. 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/transactions-localjdbc/index.html

2. Enter a value for Source Account ID and Recipient Account ID. The entry for these fields must be any of the valid Account ID's listed below:
 

3. Enter a value for Transfer Amount. This must be a value that is not less than 0 and not more than the Account's Maximum Withdrawal Amount.

4. Click on Transfer Funds to execute the transaction. The Local JDBC Transaction Output Form will be displayed with the results of the transaction.

Troubleshooting

Compiling and Assembling the Application

For example, to rebuild the entire application from scratch, follow these steps:

1. Compile and Assemble EJB JAR Components and Web Application

     Execute the build command in this directory:

install_dir/ias/ias-samples/transactions/local/jdbc/src directory.

     This will compile the source code and rebuild the EJB JAR, WAR and EAR files.

2. Redeploy Application

     Execute the build deploy command in this directory:

install_dir/ias/ias-samples/transactions/local/jdbc/src

3. Restart Application Server

     Execute the iascontrol stop and iascontrol start commands.

An application server restart will be necessary if you've modified either deployment descriptors or EJBs. For servlet and/or JSP modification,  no restart is is necessary.

To clean the web application project area, execute build clean

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