Global Container-Managed Transaction Application
iPlanetTM Application Server J2EE Samples

Updated  June 12, 2001

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

This sample application illustrates the implementation of a global Container-Managed Transaction (CMT). The application simulates a transfer of funds from one account to another in which the accounts may come from different banks. The transaction is "global" because it involves multiple data sources: a local bank and a foreign bank.

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

  1. the bank that is associated with the Source Account
  2. the Account Number of the Source Account from which the funds should be withdrawn
  3. the bank that is associated with the Recipient Account
  4. the Account Number of the Recipient Account to which the funds should be deposited
  5. the amount of money to be transferred

When the user clicks the Transfer Funds button, the GlobalCmtServlet is invoked and it calls GlobalBankServiceEJB.transferFunds( ) to do the following:

  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 an exception is thrown. The exception causes the container to throw a TransactionRolledbackException which rolls back all the database updates that were executed in the transferFunds( ) method. Otherwise, if the Source Account balance is not negative, the Source Account has enough funds to transfer and the container automatically commits the transaction at the end of the transferFunds( ) method.
The results of the transaction are displayed in an HTML form similar to the one shown below:

Architecture and Process Flow

The architecture and process flow diagram is shown below:

Figure 3 - Global Container-Managed Transaction

The GlobalCmtServlet locates the GlobalBankServiceEJB which performs the following steps in its transferFunds( ) method without explicitly starting a transaction -- the transaction is implicitly started by the container when  GlobalBankServiceEJB.transferFunds( ) is called.

  1. Get the account balance for the Source Account and the Recipient Account.

    2.  
  2. Withdraw the transfer amount from the Source Account by deducting the amount from its balance. If the Source Account is from a Local Bank, LocalBankAccount.withdraw( amount ) is invoked. Otherwise, ForeignBankAccount.withdraw( amount ) is executed.

    3.  
  3. Deposit the transfer amount to the Recipient Account by adding the amount to its balance. If the Recipient Account is from a Local Bank, LocalBankAccount.deposit( amount ) is invoked. Otherwise, ForeignBankAccount.deposit( amount ) is executed.

    4.  
  4. Get the updated balance of the Source Account. If the balance is negative, this means that the Source Account does not have enough funds to transfer. An exception is thrown and the container automatically rolls back the transaction. On the other hand, if the balance is not negative and when no other exception is thrown, the container automatically commits the transaction that it started when the transferFunds( ) method was called.
Container-managed transactions are declared during deployment and they are automatically started, committed and/or rolled-back by the container. In this sample application, a transaction was automatically managed by the container in the transferFunds( ) method because the transaction attribute for GlobalBankServiceEJB.transferFunds( ) was set to Required during deployment.

Setting Up the Environment

To set up the environment, it is mandatory to satisfy a general checklist of prerequisites for deploying a sample application using iPlanet. Please refer to the Getting Started section before going further.

Configuring the Database

This sample application as deployed to iPlanet requires the following database setup prior to running the application:
  1. Register Database Driver
  2. Create Resource Managers
  3. Create Database Users
  4. Create and Populate Database Tables

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.

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

    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. You will be asked to enter the iAS installation root directory.
       
        Please enter the iAS installation root directory[eg: /usr/iplanet/ias6]:
        /usr/iplanet/ias6
         
      4. Follow the instructions to set up an iPlanet Type 2 JDBC Driver.
       
        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 1 and hit Return or simply hit the Return key.
         

      5. You will be asked if iAS should be configured with connectivity to Oracle, Sybase, Informix or DB2 databases. Enter 'y' for the database type(s) of interest. For example, if you are configuring iAS for connectivity to an Oracle database, enter 'y' for the following question:
       
        Do you want to configure iAS with Oracle connectivity [n]?  (y/n)
        y

        Enter the Oracle home directory [/usr/oracle/product/8.1.6]:
        /usr/oracle/product/8.1.6

        Enter the ORACLE_SID [IAS]:
        IAS
         

      6. You will be asked if you want to configure a Resource Manager. For this sample, you need to register Resource Managers to support distributed and possibly heterogeneous transactions. To illustrate how global transactions work, it is highly recommended that the Local Bank database and the Foreign Bank database be created on different database servers. In this case, there will be 2 Resource Managers needed: one for the Local Bank database and another for the Foreign Bank database.

      For example, here is how the Resource Managers are created for the scenario where the Local Bank database is in an Oracle server called fondue.red.iplanet.com, and the Foreign Bank database in another Oracle server called nasguru.red.iplanet.com:
       

        Do you want to configure Resource Manager (y/n) [n]?
        y

        How many Resource Managers do you want to configure [1]?
        2

        Enter Resource Manager Name: [rm1]:
        fondue

        Enter Database Type: (Oracle) [Oracle]:
        Oracle

        Construct OpenString:

        Please enter database server name:  fondue.red.iplanet.com

        Please enter database user name:  system

        Please enter database user password:  manager

        Enable this Resource Manager (y/n) [y]?
        y

        Enter Resource Manager Name: [rm2]:
        nasguru

        Construct OpenString:

        Please enter database server name:  nasguru.red.iplanet.com

        Please enter database user name:  system

        Please enter database user password:  manager

        Enable this Resource Manager (y/n) [y]?
        y

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

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

2. Create Resource Managers

    If Resource Managers were not created in the previous section, Register iPlanet Type 2 Driver if Necessary, they can be created using the iPlanet Application Server Administration Tool. A Resource Manager must be created for each database server that is used in this application. If the Local Bank database resides on one database server and the Foreign Bank database resides on another database server, 2 resource managers must be created.
    1. Start the iPlanet Application Server Administration 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. Click on the Application Server instance.
    3. Click on the Transactions button.
    4. Click on the Configuration tab.
    5. Check the Enable Global Transactions checkbox.
    6. Click on the Resource Manager tab.
    7. Click the Add button at the bottom of the Resource Manager tab to create a Resource Manager for the Local Bank database server. This will launch the New Resource Manager window. Enter the information required for accessing the database. Give the resource manager a unique name and make sure that the Enabled checkbox is checked.


      8. For example, to create a Resource Manager named fondue for an Oracle database server called fondue.red.iplanet.com:
       

      1. Enter fondue as Name.
      2. Enter the following as the Open String:

        3. Oracle_XA+DB=fondue.red.iplanet.com+Acc=P/system/manager+Sqlnet=fondue.red.iplanet.com+SesTm=90+Threads=True

        Note that the Open String for Oracle is in this format:
        Oracle_XA+DB=<SERVER_INSTANCE>+Acc=P/<USERNAME>/<PASSWORD>+Sqlnet=<SERVER_INSTANCE>+SesTm=<SESSION_TIME_OUT>+Threads=<IS_THREADSAFE>
         

      3. Set Type to oracle
      4. Set Thread Mode to multiple_associations
      5. Check the Enabled checkbox
      6. Click the OK button to close the New Resource Manager window. The new Resource Manager will appear in the Resource Manager tab.


      IMPORTANT:

      1. The machine where the iPlanet Application Server resides must have been previously configured to have access to both the Local Bank and Foreign Bank database servers before the Resource Managers are created. For example, Oracle database servers should be accessible using the SQL Plus utility on the machine where the iPlanet Application Server resides.
      2. The steps for creating a Resource Manager vary depending on the type of database. For example, when creating a Resource Manager for an Oracle database, there are recovery-related catalog tables that need to be created.


        3. To create the catalog tables required for Oracle:

      3. Navigate to the  <ORACLE_HOME>/rdbms/admin directory and find the xaview.sql script:
      4. Login to Oracle's sqlplus utility as user sys and run the xaview.sql script:

        5. SQL> @xaview
        For details on how to set up a resource manager, please refer to the iPlanet Application Server Administration Guide's section on Setting Up Resource Managers for Distributed Transactions.
         
    8. Repeat the previous step to create a Resource Manager for the Foreign Bank database server. For example, to create a Resource Manager named nasguru for an Oracle database server called nasguru.red.iplanet.com:

      9.  
      1. Enter nasguru as Name.
      2. Enter the following as the Open String:

        3. Oracle_XA+DB=nasguru.red.iplanet.com+Acc=P/system/manager+Sqlnet=nasguru.red.iplanet.com+SesTm=90+Threads=True
      3. Set Type to oracle
      4. Set Thread Mode to multiple_associations
      5. Check the Enabled checkbox
      6. Click the OK button to close the New Resource Manager window. The new Resource Manager will appear in the Resource Manager tab.

        7.  
    9. Restart the application server using iascontrol stopand iascontrol start from the command line.

3. Create Database Users

    Before you can create and populate the database tables, it is necessary to create the localbank and foreignbank users. These users will own the tables created for the sample application. To illustrate how global transactions work across multiple data sources, it is strongly recommended that the localbank user and its tables be created in one database server, and the foreignbank user and its tables be created in another database server. However, if resource constraints make this impossible, the application will also work if the localbank and foreignbank users and their tables are created in the same database server.

    The following example shows how to create 2 new users: localbank and foreignbank using the Oracle SQL Plus utility. It is mandatory that the localbank and foreignbank users be used to create the database tables for this sample application.

    To define a new Oracle user called localbank:

      1. Use SQL Plus and login to the database server where the Local Bank database will be created.

      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;

    To define a new Oracle user called foreignbank:
      1. Use SQL Plus and login to the database server where the Foreign Bank database will be created.

      SQL > create user foreignbank identified by foreignbank;

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

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

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

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

4. Create and Populate Database Tables

    For this application, the following databases need to be created on different database servers:
    1. Local Bank database
    2. Foreign Bank database

    Creating the Local Bank Database

    To create the Local Bank database, there is a script named setup_localbank_<rdbms_type>.sh for Unix (setup_localbank_<rdbms_type>.bat for Windows) which configures the database tables. (Replace <rdbms_type> with ora for Oracle, syb for Sybase). The script performs the following steps:
    1. Registers the Local Bank database as iPlanet data source java:comp/env/jdbc/transactions/global/LocalBankDB
    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/global/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_localbank_<rdbms type>.sh on Unix or setup_localbank_<rdbms type>.bat on Windows.

    Oracle Table Creation and Population

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

      setup_localbank_ora.sh <TNS Name> localbank localbank <Resource Manager>

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

      <Resource Manager> is the name of the Resource Manager that is associated with the database server where the Local Database resides. This must be the same name that was used when a Resource Manager was created for the Local Database in the previous section, Create Resource Managers.

    Creating the Foreign Bank Database

      To create the Foreign Bank database, there is a script named setup_foreignbank_<rdbms_type>.sh for Unix (setup_foreignbank_<rdbms_type>.bat for Windows) which configures the database tables. (Replace <rdbms_type> with ora for Oracle, syb for Sybase). The script performs the following steps:
      1. Registers the Foreign Bank database as iPlanet data source java:comp/env/jdbc/transactions/global/ForeignBankDB
      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/global/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_foreignbank_<rdbms type>.sh on Unix or setup_foreignbank_<rdbms type>.bat on Windows.

      Oracle Table Creation and Population

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

        setup_foreignbank_ora.sh <TNS Name> foreignbank foreignbank <Resource Manager>

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

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

        <Resource Manager> is the name of the Resource Manager that is associated with the database server where the Foreign Database resides. This must be the same name that was used when a Resource Manager was created for the Foreign Database in the previous section, Create Resource Managers.

5. Register Datasources

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

<ias-resource>
<resource>
<jndi-name>jdbc/transactions/global/ForeignBankDB</jndi-name>
<jdbc>
<datasource>pusti.world</datasource>
<database>dummy</database>
<username>foreignbank</username>
<password>foreignbank</password>
<driver-type>ORACLE_OCI</driver-type>
<resource-mgr>rm2</resource-mgr>
</jdbc>
</resource>
</ias-resource>

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

For example, if you are using Oracle,

1. Go to the directory
install_dir/ias/ias-samples/transactions/global/schema.

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

iasdeploy regdatasource localbankdb-ias-ora-type2.xml

iasdeploy regdatasource foreigndb-ias-ora-type2.xml

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

Deploying the Application

You can select any of the following ways of deploying and registering 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

Since the sample application is supplied with a complete EAR file, the fastest means of setting up the application 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 transactions-globalcmt.ear file is an Enterprise Archive (EAR) file that contains the Web Archive (WAR) file for the application. Since this application does not have any EJB's, there is no JAR file involved.

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

1. Go to the root of the application's directory:

install_dir/ias/ias-samples/transactions/global/cmt/
2. Execute iasdeploy to deploy the application to the application server:
install_dir/ias/bin/iasdeploy deployapp transactions-globalcmt.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 JAR/ directory.
  • expands the content of the J2EE modules to the APPS/transactions-globalcmt directory.
    • 3. Restart the application server using the iascontrol stop and iascontrol start commands.

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

    Graphical User Interface (GUI) Deployment

    The Deployment Tool provides an easy-to-use means of assembling J2EE applications and deploying them to the application server. Compared to the effort and risks involved in the manual creation of J2EE deployment descriptors and modules, the Deployment Tool provides an easy-to-use means of deploying your application to the application server.

    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

    Since a pre-built Enterprise ARchive (EAR) file for the sample application is shipped with the application server, you can use the Deployment Tool to quickly read in the .ear file, modify deployment settings and deploy to the application server.

    1. Launch the Deployment Tool.

    UNIX: Execute install_dir/ias/bin/deploytool

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

    2. Open the transactions-globalcmt.ear file
    1. In the startup dialog, select Browse to find the transactions-globalcmt.ear file. Alternatively, if the Deployment Tool is already open, select File->Open from the menu bar.
    2. Navigate to ias/ias-samples/transactions/global/cmt and open the transactions-globalcmt.ear file.
    3. Select Component View
    Now that the transactions-GlobalContainerManaged.ear file has been imported, you may proceed to Deploy the Application.

    GUI: Assemble Application from Scratch

    Assembling the application from scratch involves the following steps:
    1. Compile application sources.
    2. Create the JAR file.
    3. Create the WAR file.
    4. Create the 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/global/cmt/src
      2. Execute the build compile command.
      3. Create the following directory where the JAR, WAR and EAR files will be created in the next section:

        4. install_dir/ias/ias-samples/transactions/global/cmt/assemble
    2. Create the JAR File
    1. Launch the Deployment Tool:
    UNIX: Execute install_dir/ias/bin/deploytool&

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

    2. Create transactions-GlobalContainerManaged.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-GlobalContainerManaged.jar as the File Name.
    5. Click on Browse to navigate to install_dir/ias/ias-samples/transactions/global/cmt/assemble
    6. 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.
    3. Insert all class files needed in the transactions-GlobalContainerManaged.jar file:
    1. Select transactions-globalcmtEjb from the EJB Modules window and right click. Select Insert (Alternatively, select the module, select Edit->Insert)
    2. Navigate to this directory:

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

      5. install_dir/ias/ias-samples/transactions/global/cmt/build/classes/samples/transactions/global/cmt/ejb
    5. In the left hand pane, select all class files. Click on the right arrow (>) to move the selected files into the 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-globalcmtEjb folder from the EJB Modules window.
    2. Select the GlobalBankServiceEJB bean, right click and select Edit Descriptor.
    3. Set EJB Name to samples.transactions.globalbmt.ejb.GlobalBankServiceEJB to insure uniqueness.
    4. Set Transaction Management to Container. This will enable the Transactions tab.
    5. Select the Transactions tab and set the Default Transaction Attribute to Supports.
    6. Click Add at the bottom of the Transactions tab to enter the following information:

      7.  
      Method
      Transaction Attribute
      transferFunds( )
      Required
      getFromAccountOldBalance( )
      Supports
      getToAccountOldBalance( )
      Supports
      getFromAccountNewBalance( )
      Supports
      getToAccountNewBalance( )
      Supports
    7. Select the References tab from the EJB Descriptor window.
    8. Enter the following information in the References to Resources section:
    Resource Name
    Description
    Resource Class
    Authorization
    JNDI Name
    jdbc/transactions/LocalBankDB
    Local Bank Database
    javax.sql.DataSource
    Container
    jdbc/transactions/global/LocalBankDB
    jdbc/transactions/ForeignBankDB
    Foreign Bank Database
    javax.sql.DataSource
    Container
    jdbc/transactions/global/ForeignBankDB
    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.

    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-globalcmt.war as the File name.
    4. Click on Browse to navigate to this directory:

      5. install_dir/ias/ias-samples/transactions/global/cmt
    5. Click on the assemble folder and click the OK button to exit the dialog window.
    6. The WAR file appears in the Web Applications pane of the Deployment Tool window.
    7. Click on Component View to see only the name of the WAR file without the directory path.
    2. Insert all class files needed in the WAR file.
    1. Select transactions-globalcmt from the Web Applications window. Right click and select Insert. Alternatively, select Edit->Insert from the menu bar.
    2. Navigate to this directory:

      3. install_dir/ias/ias-samples/transactions/global/cmt/build/classes/samples/transactions/global/cmt/servlet
    3. Select all files.
    4. Click on the right arrow (>) to move all classes into right side of the dialog window.
    5. Click on Resolve to determine if any of the included classes depend on classes that are not part of the WAR module.
    6. 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-globalcmt 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/global/cmt/src/docroot
    3. 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-globalcmt WAR 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:

      5.  
      Reference Linked to Bean Bean Type Bean Home Interface Bean Remote Interface
      ejb/samples.transactions.global.cmt.ejb.GlobalBankServiceEJB samples.transactions.global.cmt.ejb.GlobalBankServiceEJB Session samples.transactions.global.cmt.ejb.GlobalBankServiceHome samples.transactions.global.cmt.ejb.GlobalBankService

      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-globalcmt 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-globalcmt.ear as the File name.
    4. Click on Browse to navigate to this directory:

      5. install_dir/ias/ias-samples/transactions/global/cmt/assemble
    5. 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-globalcmt from the J2EE Applications window. Right click and select Insert.
    2. Navigate to the directory install_dir/ias/ias-samples/transactions/global/cmt/assemble
    3. Select both transactions-globalcmtEjb.jar and transactions-globalcmt.war files.
    4. Click on the right arrow (>) to move the file 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. Select the file and 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-globalcmt/index.html the transactions-globalcmt 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 totransactions-globalcmt
    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-globalcmt EAR file from the J2EE Applications window.
    2. Select File->Save to save the EAR file.

    GUI: Deploy the Application

    Now you're about to deploy the application by transferring the EAR file to a target iPlanet Application Server. First, you will identify the target server. After the EAR file is deployed to the server, you will be able to run the application.
    1. Select the transactions-globalcmt 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

    After you've deployed the application, you're ready to use several application server administrative tools to verify that the application is available.

    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 a folder for the transactions-globalcmt J2EE application. The transactions-globalcmt folder with the world icon represents the web application module while the transactions-globalcmtEjb 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-globalcmt application.
    4. Expand the transactions-globalcmt folder and explore this portion of the directory tree.
    5. Now open the J2EE-Module/ tree and look for the transactions-globalcmt web application module entry and the transactions-globalcmtEjb EJB module entry.
    6. Expand each of these folders and explore their contents.

    Running the Application

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

    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-globalcmt/index.html
    2. Enter a value for Source Bank, Source Account ID, Recipient Bank and Recipient Account ID.

    The Local Bank Accounts are listed below:
     

    Local Bank Account ID
    Initial Balance
    Maximum Withdrawal Amount
    001
    100
    300
    002
    500
    300

    The Foreign Bank Accounts are listed below:
     

    Foreign Bank Account ID
    Initial Balance
    1000
    1000
    1001
    5000

    3. Enter a value for Transfer Amount. This must be a value that is not less than 0. If the Source Account is from a Local Bank, this value must not be more than the Local Account's Maximum Withdrawal Amount.

    4. Click on Transfer Funds to execute the transaction.

    Troubleshooting

    When running the application, the following error conditions could occur and cause the transaction to roll back:
     
    Error Message
    Description
    		 Solution
    Please correct your entries. The values entered in the required fields are either blank or contain incorrect values. Make sure there is a value for all the required fields.
    Transfer Amount must be a number greater than 0.
    Account ID X does not exist. The value X that was entered for either the Source Account ID or Recipient Account ID is not one of the valid Account ID's listed above. Make sure that both Source Account ID and Recipient Account ID are in the list of valid Account ID's shown above.
    Cannot withdraw from Source Account: Account has insufficient funds. The Source Account does not have enough funds to transfer the requested amount to the Recipient Account. Reduce the Transfer Amount to be less or equal to the Source Account Balance.
    Cannot withdraw from Source Account: Maximum withdrawal amount is 300. The Transfer Amount exceeds the Maximum Withdrawal Amount that was defined for the Source Account. This only happens when the Source Account is from a Local Bank. Foreign Bank Accounts do not have a maximum withdrawal amount. Reduce the Transfer Amount to be less or equal to the Account's Maximum Withdrawal Amount.

    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.

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

    1. Compile and Assemble Components and Web Application

         Execute build in the install_dir/ias/ias-samples/transactions/global/cmt/src directory.

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

    2. Redeploy Application

         Execute build deploy in the install_dir/ias/ias-samples/transactions/global/cmt/src directory.

    3. Restart the Application Server using iascontrol stop and iascontrol start on the command line.

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