Sun J2EE Developer's Guide Samples
Deployment to iPlanet Application Server

This document provides basic instructions for deploying and running Sun's J2EE Developer's Guide, version 1.2.1 EJB samples on iPlanet Application Server. Each sample is very simple and emphasizes a specific aspect of EJBs. iPlanet has augmented the original Sun samples with instructions for deploying the samples to iPlanet Application Server. Before deploying the following samples:

• Review the iPlanet Samples Getting Started document.
• Review the Application Notes for J2EE Developer's Guide Sample.
• Begin by deploying the Currency Converter stateless session bean to become familiar with iPlanet's RMI/IIOP support.

To deploy the J2EE Developer's Guide samples to iPlanet, refer to the "iPlanet Setup Instructions" column in the following table. The "Sun Tutorial Documentation" column provides links to the original Sun documentation describing the J2EE-based programming practices associated with each application.

Account: BMP Entity Bean

Modifications Made to the Sun Sample

AccountEJB.java was modified to move the logic for obtaining a connection from setEntityContext() to the private helper methods that need to interact with the database.  Since the application server supports connections pooling, it is much more efficient to obtain a connection from the pool per EJB method invocation than to have potentially many copies of EJBs holding connections from the pool for an extended period of time.

A servlet named AccountServlet.java has been added to provide a web-based means of exercising the Account EJB.

Deploying to iPlanet Application Server

Setup Database Table

Using PointBase

If Pointbase is the target database, then nothing needs to be done since the database is prepopulated. However, if you do want to navigate the database tables or want to unload and create the tables from scratch (using the account_pb.sql script in the src/schema directory), follow the instructions in the Using Pointbase with iPlanet guide.

However, the datasource needs to be registered. To do this,

Go to the directory
install_dir/ias/ias-samples/j2eeguide/account/src/schema.

Execute the command
iasdeploy regdatasource AccountDB-pointbase-type4.xml

After registering the datasource, go to the next section to assemble the application.

Using Oracle

The Account sample's database setup script will register the jdbc/j2eeguide/AccountDB datasource in the application server and then create a simple table named ACCOUNT in the database.  Since the Account sample adds rows to the database, no rows are added by the database setup script.

• Go to the directory install_dir/ias/ias-samples/j2eeeguide/account/src/schema/
• On the command line, set ORACLE_HOME
• Modify setup_ora.sh or .bat file and set IAS_INSTALL_PATH to match your install directory.
• Execute setup_ora.sh or .bat file as follows:



setup_ora.sh <TNS Name> <user name> <user password>

For example,

setup_ora.sh orcl j2eeguide j2eeguide

• Compile Servlet and EJB Sources
• Create j2eeguide-accountEjb.jar Module
• Create j2eeguide-account.war module
• Assemble j2eeguide-account.ear
• Deploy Application

Compile EJB Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the Sample Application Build Facility document for more information on using a build facility to quickly compile the application.

See Assemble EJB JAR steps in Converter documentation for additional details.

• Create an assemble/ directory under install_dir/ias/ias-samples/j2eeeguide/account/.  While using the Deployment Tool the j2eeguide-accountEjb.jar and j2eeguide-account.ear files will be saved in the assemble/ directory.
• Launch Deployment Tool.
• Create j2eeguide-accountEjb.jar file. Specify j2eeguide-accountEjb as the name of the archive file and the assemble/ directory as location where the archive will be saved.
• Insert necessary class files.  For Account, the files to be inserted include:
  • Account.class
  • AccountEJB.class
  • AccountHome.class
  • InsufficientBalanceException.class
• Modify Descriptor
  • In the General tab under Bean Name, change the name of the EJB from "Account" to "MyAccount".
  • Set Persistence Type to Bean (as in bean managed persistence)
  • Set the  Primary Key Class Name to java.lang.String
  • Click on "Enable RMI/IIOP".
  • Click on References tab. Click on New Reference and complete the following fields:
    • Resource Name: jdbc/AccountDB  (this is the name used in the AccountEJB.java file)
    • Resource Class:  javax.sql.DataSource
    • Authorization: Container
    • JNDI Name: jdbc/j2eeguide/AccountDB  (AccountDB was registered in the application server through the setup_ora.sh/.bat file)
  • Click on the Transactions tab.  Click on Add New Method Override...
    • Use the CONTROL key to select the business methods and click on:
      • getBalance()
      • credit()
      • debit()
    • For each method, select Required under Transaction Attribute
• Ensure that the j2eeguide-accountEjb.jar is selected.
• Select File->Save to save the j2eeguide-accountEjb.jar file to the assemble/ directory.
• Select File->Close to close the j2eeguide-accountEjb.jar windows.

Create j2eeguide-account.war Module

This is an optional step. If you plan on using the AccountServlet to access the Account EJB, then follow these instructions. If you plan to use the AccountClient with RMI/IIOP as the only method of accessing the Account EJB, then skip to the next series of steps to create the EAR file.

See Assemble WAR steps in Converter documentation for additional details.

• Import the class files in the new .war file:
  • Launch Deployment Tool.
  • Create j2eeguide-account.war file.
  • Insert the following class files from from j2eeeguide/account/build/classes/j2eeguide/account/
    • AccountServlet.class
• Modify Descriptor
  • In the Web App Descriptor select the EJB Reference tab. Then click on New Reference to complete the following fields:
    • Reference: MyAccount
    • Bean Type:  Entity Bean
    • Bean Home Interface: j2eeguide.account.AccountHome
    • Bean Remote Interface: j2eeguide.account.Account
    • Linked to Bean: MyAccount
  • Select File->Save to save the j2eeguide-account.war file to the assemble/ directory.
  • Select File->Close to close the j2eeguide-account.war windows.

Assemble j2eeguide-account.ear

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-account.ear
• Add j2eeguide-accountEjb.jar
• Add j2eeguide-account.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-account"
• Save j2eeguide-account.ear

Deploy the Server Application

See EJB deployment steps in Converter documentation. 

See client deployment steps in Converter documentation.  Steps for the Account sample are identical to those for Converter except for the following considerations:

• Following files must be copied to the client directory. For example: /opt/rmi-client/j2eeguide/account/:
• AccountClient.class
• InsufficientBalanceException.class
• AccountHome.class
• Account.class
• _Account_Stub.class
• _AccountHome_Stub.class

• Double check that your CLASSPATH and PATH variables are set according to the instructions.  Incorrect CLASSPATH and PATH settings are the most common cause of problems with the RMI/IIOP examples.

See Running the Application in Converter documentation.  Review the troubleshooting information as well.  For Account, you should expect the following output on the client side:

root@ias-{$PWD}: java j2eeguide.account.AccountClient localhost 9010
balance = 68.25
balance = 32.55
456: 44.77
730: 19.54
268: 100.07
456: 44.77
836: 32.55

After client application completes, the database should have the following information:

SSQL> select * from account;

ID  FIRSTNAME                LASTNAME                    BALANCE
--- ------------------------ ------------------------ ----------
456 Pat                      Smith                         44.77
836 Joe                      Jones                         32.55
730 John                     Smith                         19.54
268 Mary                     Smith                        100.07

Run the Servlet Client

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-account/AccountServlet

If your deployment process was successful, the servlet sends the same information to the browser as seen when running the RMI/IIOP client.

Whenever the client application does not display the output listed above, you should go into the database and manually clean the Account table.  If you see the following message in the kjs log file, it is most likely caused by an attempt to perform an EJB create of the Account bean with the same primary key as previous create attempt.   To fix this problem, either go into the database and delete the existing rows from the account table or rerun the setup_ora script to drop and create the table again.

[25/Apr/2000 09:31:50:0] warning: ORCL-002: GXORCL2PreparedStatement::DAEExecute(): ORA-00001: unique constraint (IASDEMO.PK_ACCOUNT) violated

In this case, the client sees a java.lang.NullPointerException.

If you are using PointBase, you can remove and recreate the sample table by using the supplied src/schema/account_pb.sql script and the PointBase tools described in Using PointBase with iPlanet guide.

As part of your troubleshooting efforts, ensure that you review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

Adder: Stateful Session Bean

Modifications Made to the Sun Sample

In the AdderServlet, the reference to the Adder EJB is saved in a instance variable of the servlet rather than in HttpSession. This artifact of the sample from Sun means that multiple users of the same servlet instance will access the same stateful session bean instance. In a production application, a more appropriate approach would be to save the Handle to the EJB instance in the HttpSession instance associated with each web session.

Deploying to iPlanet Application Server

• Compile EJB and Servlet Sources
• Create j2eeeguide-adderEjb.jar Module
• Create j2eeguide-adder.war Module
• Assemble j2eeguide-adder.ear
• Deploy Application

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the Sample Application Build Facility document for more information on using a build facility to quickly compile the application.

See Assemble EJB JAR steps in Converter documentation for additional details.

• Create an assemble/ directory under ias-samples/j2eeguide/adder/.  Through the Deployment Tool, you will be saving the j2eeguide-adderEjb.jar and j2eeguide-adder.ear files to this directory.
• Launch Deployment Tool.
• Create j2eeguide-adderEjb.jar file.
• Insert necessary class files.  For Adder, the files to be inserted include:
  • Adder.class
  • AdderEJB.class
  • AdderHome.class
• Modify Descriptor
  • In the General tab, change the Bean Name to "MyAdder".
• Select File->Save to save the name change.
• Select State Management Type of Stateful.
• Ensure that the j2eeguide-adderEjb.jar is selected.
• Select File->Save to save the j2eeguide-adderEjb.jar file to the assemble/ directory.

Select File->Close to close the j2eeguide-adderEjb.jar window.

Create j2eeguide-adder.war Module

See Assemble WAR steps in Converter documentation for additional details.

• Create j2eeguide-adder.war file.
• Insert AdderServlet.class.
• Insert adder/src/docroot/adder.html file to the root location of the WAR module.
• Select WAR module, right click and select Edit Descriptor.
• Click on Servlet Mapping and add an entry with Servlet Name set to AdderServlet and URL Patter set to /AdderAlias. (The slash "/" in front of "AdderAlias" is very important).
• Click on the References tab, under EJB references and click on New Reference.  Set the following fields:
• Reference: MyAdder
• Bean Type: Session
• Bean Home Interface: j2eeguide.adder.AdderHome
• Bean Remote Interface: j2eeguide.adder.Adder
• Linked to Bean:  MyAdder
• Click on File->Save to save the war file.
• Click on File->Close to close the j2eeguide-adder.war file.

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-adder.ear
• Add j2eeguide-adderEjb.jar
• Add j2eeguide-adder.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-adder"
• Save j2eeguide-adder.ear

See the deployment steps in Converter documentation. 

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-adder/adder.html

Enter a number and press submit. The AdderServlet will interact with the Adder EJB to add the value to a running total and display the resulting total in a web page. Enter another number and press submit again to see the updated total. Negative numbers will work as well.

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

Bank: Container-Managed Transactions

Modifications Made to the Sun Sample

Deploying to iPlanet Application Server

Setup Database Table

Using PointBase

If Pointbase is the target database, then nothing needs to be done since the database is prepopulated. However, if you do want to navigate the database tables or want to unload and create the tables from scratch (using the bank_pb.sql script in the src/schema directory), follow the instructions in the Using Pointbase with iPlanet guide.

However, the datasource needs to be registered. To do this,

Go to the directory
install_dir/ias/ias-samples/j2eeguide/bank/src/schema.

Execute the command
iasdeploy regdatasource BankDB-pointbase-type4.xml

After registering the datasource, go to the next section to assemble the application.

Using Oracle

The Bank sample's database setup script will register the jdbc/j2eeguide/BankDB datasource with the application server and then create a simple table named BANK in the database.

• Go to the directory install_dir/ias/ias-samples/j2eeeguide/bank/src/schema/
• On the command line, set ORACLE_HOME
• Modify setup_ora.sh or .bat file and set IAS_INSTALL_PATH to match your install directory.
• Execute setup_ora.sh or .bat file as follows:



setup_ora.sh <TNS Name> <user name> <user password>

For example,

setup_ora.sh orcl j2eeguide j2eeguide

• Compile EJB and Servlet Sources
• Create j2eeguide-bankEjb.jar module
• Create j2eeguide-bank.war module
• Assemble j2eeguide-bank.ear

Compile EJB and servlet sources

• To compile the application sources, simply execute "build compile" under the application's src/ directory. See the Sample Application Build Facility document for more information on using a build facility to quickly compile the application.

Create j2eeguide-bankEjb.jar Module

See Assemble EJB JAR steps in Converter documentation for additional details.

• Create an assemble/ directory under install_dir/ias/ias-samples/j2eeeguide/bank/.  Through the Deployment Tool, you will save the j2eeguide-bankEjb.jar, j2eeguide-bank.war and j2eeguide-bank.ear files to this directory.
• Launch Deployment Tool.
• Create j2eeguide-bankEjb.jar file.
• Insert necessary class files.  For Bank, the files to be inserted include:
  • Bank.class
  • BankEJB.class
  • BankHome.class
  • InsufficientBalanceException.class
• Modify Descriptor
  • In the General tab under Bean Name, change the name of the EJB from "Bank" to "MyBank".
  • Select File->Save to save the name change.
  • Select State Management type of "Stateful".
  • Select Transaction Management Type as "Container".
  • Select "Enable RMI/IIOP".
  • Click on References tab. Click on New Reference and complete the following fields:
    • Resource Name: jdbc/BankDB  (this is the name used in the BankEJB.java file)
    • Resource Class:  javax.sql.DataSource
    • Authorization: Container
    • JNDI Name: jdbc/j2eeguide/BankDB  (BankDB was registered in iPlanet through the setup_ora.sh/.bat file)
  • Click on the Transactions tab.  Click on Add New Method Override...
    • Select the transferToSaving()
    • For each method, select Required under Transaction Attribute
• Ensure that the j2eeguide-bankEjb.jar window is selected.
• Select File->Save to save the j2eeguide-bankEjb.jar file to the assemble/ directory.
• Select File->Close to close the j2eeguide-bankEjb.jar windows.

Create j2eeguide-bank.war Module

This is an optional step. If you plan on using the BankServlet to access the Bank EJB, then follow these instructions. If you plan to use the BankClient RMI/IIOP method of accessing the Bank EJB, then skip to the next series of steps to create the EAR file.

See Assemble WAR steps in Converter documentation for additional details.

• Import the class files in the new .war file:
  • Create j2eeguide-bank.war file.
  • Insert the necessary class files:
    • BankServlet.class
    • InsufficientBalanceException.class
  • Select BankServlet.class and create a descriptor for this servlet.
• Modify Descriptor
  • In the Web App Descriptor select the EJB Reference tab. Then click on New Reference to complete the following fields:
    • Reference: MyBank
    • Bean Type:  Session Bean
    • Bean Home Interface: j2eeguide.bank.BankHome
    • Bean Remote Interface: j2eeguide.bank.Bank
    • Linked to Bean: MyBank
  • Select File->Save to save the j2eeguide-bank.war file to the assemble/ directory.
  • Select File->Close to close the j2eeguide-bank.war windows.

Assemble j2eeguide-bank.ear

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-bank.ear
• Add j2eeguide-bankEjb.jar
• Add j2eeguide-bank.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-bank"
• Save j2eeguide-bank.ear

Deploy the Server Application

See EJB deployment steps in Converter documentation. 

See client deployment steps in Converter documentation.  Steps for the Bank sample are identical to those for Converter except for the following considerations:

• Following files must be copied to the client directory. For example: /opt/rmi-client/j2eeguide/bank/:
  • BankClient.class
  • InsufficientBalanceException.class
  • BankHome.class
  • Bank.class
  • _Bank_Stub.class
  • _BankHome_Stub.class

• Double check that your CLASSPATH and PATH variables are set according to the instructions.  Incorrect CLASSPATH and PATH settings are the most common cause of problems with the RMI/IIOP examples.

You have the option of using either the web client or the RMI/IIOP Java application client to exercise the Bank sample. Regardless of the client, before running the application, review the initial state of the CHECKING and SAVING database tables.

SQL> select * from saving;

ID BALANCE
--- ---------
123 500

SQL> select * from checking;

ID BALANCE
--- ---------
123 100

Run the Servlet Client

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-bank/BankServlet

If your deployment process was successful, the following information will be displayed:

checking: 20.0
saving: 580.0

Compare this output with the BankClient.java source code.

In the kjs log file, you should see the following output. BankServlet generates the output represented in bold:

[25/Jul/2000 11:22:46:1] info: --------------------------------------
[25/Jul/2000 11:22:46:1] info: BankServlet: init
[25/Jul/2000 11:22:46:1] info: --------------------------------------
looking up java:comp/env/MyBank
lookup ok
Lookup instance 5028cf0
afterBegin()
beforeCompletion()
afterCompletion: true
Unregister Object 5028cf0

Reload the URL in the browser and you will see the following:

checking: 20.0
saving: 580.0

Note that since there are only 20 dollars remaining in the checking account and each execution of the BankServlet attempts to transfer 40 dollars from checking to savings, another execution of the servlet should result in an exception. Reload the URL once more to see the following results:

Caught an exception:unchecked exception thrown by impl j2eeguide.bank.BankEJB@81d2e; nested exception is: j2eeguide.bank.InsufficientBalanceException

Since the Bank EJB calls the context.setRollbackOnly() method after updating the CHECKING table and before throwing the InsufficientBalanceException, the container will automatically rollback the update to the CHECKING table prior to returning the InsufficientBalanceException to the client. Verify the rollback occurred by checking the database content again. You should observe the following after the rollback:

SQL> select * from saving;

ID BALANCE
--- ---------
123 580

SQL> select * from checking;

ID BALANCE
--- ---------
123 20

If the rollback was not successful, you will see a negative balance in the CHECKING table.

To rerun the application from scratch, reload the database tables and follow the run steps again.

If you are using PointBase, you can remove and recreate the sample table by using the supplied src/schema/bank_pb.sql script and the PointBase tools described in Using PointBase with iPlanet guide.

Run the RMI/IIOP Client

See Running the Application in Converter documentation.  Review the troubleshooting infomation as well.  For Bank, you should expect the following output on the client side:

root@ias-{$PWD}: java j2eeguide.bank.BankClient localhost 9010
checking: 20.0
saving: 580.0

Troubleshooting

As part of your troubleshooting efforts, ensure that you review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

Cart: Stateful Session Bean with Helper Class

Modifications Made to the Sun Sample

A servlet named CartServlet.java has been added to provide a web-based means of exercising the Cart EJB.

Assemble and Deploy Cart Application

• Compile EJB and Servlet Sources
• Create j2eeeguide-cartEjb.jar Module
• Create j2eeguide-cart.war Module
• Assemble j2eeguide-cart.ear
• Deploy Application

Compile EJB Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the Sample Application Build Facility document for more information on using a build facility to quickly compile the application.

Create j2eeguide-cartEjb.jar Module

See Assemble EJB JAR steps in Converter documentation for additional details.

• Create an assemble/ directory under ias-samples/j2eeguide/cart/.  Through the Deployment Tool, you will save the j2eeguide-cartEjb.jar, j2eeguide-cart.war and j2eeguide-cart.ear files to this directory.
• Launch Deployment Tool.
• Create j2eeguide-cartEjb.jar file.
• Insert necessary class files.  For Cart, the files to be inserted include:
  • Cart.class
  • CartEJB.class
  • CartHome.class
  • BookException.class
  • IdVerifier.class
• Modify Descriptor
  • In the General tab, change the Bean Name to "MyCart".
  • Select File->Save to save the name change.
  • Select State Management Type of "Stateful"
  • Select "Enable RMI/IIOP".
• Ensure that the j2eeguide-cartEjb.jar window is selected.
• Select File->Save to save the j2eeguide-cartEjb.jar file to the assemble/ directory.
• Select File->Close to close the j2eeguide-cartEjb.jar window.

Create j2eeguide-cart.war Module

This is an optional step. If you plan on using the CartServlet to access the Cart EJB, then follow these instructions. If you plan to use the CartClient RMI/IIOP method of accessing the Cart EJB, then skip to the next series of steps to create the EAR file.

• Create j2eeguide-cart.war file.
• Insert CartServlet.class.
• Click on the Web App Descriptor tab.
• Click on the EJB References tab and click on New Reference.  Set the following fields:
  • Reference: MyCart
  • Bean Type: Session
  • Bean Home Interface: j2eeguide.cart.CartHome
  • Bean Remote Interface: j2eeguide.cart.Cart
  • Linked to Bean:  MyCart
• Click on File->Save to save the war file.  Click on Save when asked to verify if servlet descriptor should be created.
• Click on File->Close to close the j2eeguide-cart.war file.

Assemble j2eeguide-cart.ear

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-cart.ear
• Add j2eeguide-cartEjb.jar
• Add j2eeguide-cart.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-cart"
• Save j2eeguide-cart.ear

Deploy the Server Application

See EJB deployment steps in Converter documentation. 

See client deployment steps in Converter documentation.  Steps for the Cart sample are identical to those for Converter except for the following considerations:

• Following files must be copied to the client directory. For example: /opt/rmi-client/j2eeguide/cart/:
  • CartClient.class
  • CartHome.class
  • Cart.class
  • _Cart_Stub.class
  • _CartHome_Stub.class
  • BookException.class

• Double check that your client CLASSPATH and PATH variables are set according to the instructions.  Incorrect CLASSPATH and PATH settings are the most common cause of problems with the RMI/IIOP examples.

See Running the Application in Converter documentation.  Review the troubleshooting infomation as well.  You should expect the following output on the client side:

root@ias-{$PWD}: java j2eeguide.cart.CartClient localhost 9010
looking up java:comp/env/MyCart lookup ok
The Martian Chronicles
2001 A Space Odyssey
The Left Hand of Darkness
Caught a BookException: Alice in Wonderland not in cart.

Run the Servlet Client

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-cart/CartServlet

If your deployment process was successful, the servlet sends the same information to the browser as seen when running the RMI/IIOP client.

As part of your troubleshooting efforts, ensure that you review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

Checker: Accessing Environment Settings

Modifications Made to the Sun Sample

Deploying to iPlanet Application Server

• Compile Servlet and EJB Sources
• Create j2eeguide-checkerEjb.jar Module
• Create j2eeguide-checker.war module
• Assemble j2eeguide-checker.ear
• Deploy Application

Compile EJB Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the Sample Application Build Facility document for more information on using a build facility to quickly compile the application.

See Assemble EJB JAR steps in Converter documentation for additional details.

• Create an assemble/ directory under ias-samples/j2eeguide/checker/.  Through the Deployment Tool, you will save the j2eeguide-checkerEjb.jar, j2eeguide-checker.war and j2eeguide-checker.ear files to this directory.
• Launch Deployment Tool.
• Create j2eeguide-checkerEjb.jar file.
• Insert necessary class files.  For Checker, the files to be inserted include:
  • Checker.class
  • CheckerEJB.class
  • CheckerHome.class
• Modify Descriptor
  • In the General tab, change the Bean Name to "MyChecker".
  • Select File->Save to save the name change.
  • Select State Management type of Stateful.
  • Select "Enable RMI/IIOP".
• Ensure that the j2eeguide-checkerEjb.jar window is selected.
• Select File->Save to save the j2eeguide-checkerEjb.jar file to the assemble/ directory.
• Select File->Close to close the j2eeguide-checkerEjb.jar window.

Create j2eeguide-checker.war Module

This is an optional step. If you plan on using the CheckerServlet to access the Checker EJB, then follow these instructions. If you plan to use the CheckerClient RMI/IIOP method of accessing the Checker EJB, then skip to the next series of steps to create the EAR file.

See Assemble WAR steps in Converter documentation for additional details.

• Create j2eeguide-checker.war file.
• Insert CheckerServlet.class.
• Click on the Web App Descriptor tab.
• Click on the EJB References tab and click on New Reference.  Set the following fields:
  • Reference: MyChecker
  • Bean Type: Session
  • Bean Home Interface: j2eeguide.checker.CheckerHome
  • Bean Remote Interface: j2eeguide.checker.Checker
  • Linked to Bean:  MyChecker
• Click on File->Save to save the war file.  Click on Save when asked to verify if servlet descriptor should be created.
• Click on File->Close to close the j2eeguide-checker.war file.

Assemble j2eeguide-checker.ear

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-checker.ear
• Add j2eeguide-checkerEjb.jar
• Add j2eeguide-checker.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-checker"
• Save j2eeguide-checker.ear

Deploy the Server Application

See EJB deployment steps in Converter documentation. 

Deploy the Client Application

See client deployment steps in Converter documentation.  Steps for the Checker sample are identical to those for Converter except for the following considerations:

• Following files must be copied to the client directory. For example: /opt/rmi-client/j2eeguide/checker/:
  • CheckerClient.class
  • CheckerHome.class
  • Checker.class
  • _Checker_Stub.class
  • _CheckerHome_Stub.class

• Double check that your CLASSPATH and PATH variables are set according to the instructions.  Incorrect CLASSPATH and PATH settings are the most common cause of problems with the RMI/IIOP examples

See Running the Application in Converter documentation.  Review the troubleshooting infomation as well.  For Checker, you should expect the following output on the client side:

root@ias-{$PWD}: java j2eeguide.checker.CheckerClient localhost 9010
discount = 4800.0

Run the Servlet Client

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-checker/CheckerServlet

If your deployment process was successful, the servlet sends the same information to the browser as seen when running the RMI/IIOP client.

As part of your troubleshooting efforts, ensure that you review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

JSP to Bean: JSP, JavaBean and BMP Combination

Deploying to iPlanet Application Server

Since the j2eeguide-accountEjb.jar file will be included in the j2eeguide-jsptobean.ear file, you must ensure that this EJB JAR file exists and has been tested. If you already ran the Account sample, then this EJB JAR file should be available under the following directory:

ias-samples/j2eeguide/account/assemble/

Setup Database Table

Refer to the earlier Account sample if you have not already setup the database table for the Account entity bean.

Assemble and Deploy Application

• Compile JavaBean Sources
• Create j2eeguide-jsptobean.war Module
• Assemble j2eeguide-jsptobean.ear
• Deploy Application

• As a prerequisite for this example, you must ensure that the Account EJB source files are compiled. Go to the following directory and execute "build compile":

ias-samples/j2eeguide/account/src/

• Now you're ready to compile the JavaBean which calls the AccountEJB. Go to the following directory:

ias-samples/j2eeguide/jsptobean/src/

• Execute "build compile"

Create j2eeguide-jsptobean.war Module

See Assemble WAR steps in Converter documentation for additional details.

• Create an assemble/ directory under ias-samples/j2eeeguide/jsptobean/.  Through the Deployment Tool, you will save the j2eeguide-jsptobean.war and j2eeguide-jsptobean.ear files to this directory.
• Launch Deployment Tool.
• Create j2eeguide-jsptobean.war file.
• Insert the Account.jsp file from the j2eeguide/jsptobean/src/docroot/ directory.
• Next, insert the JavaBean class file AccountBean.class
• Select the WAR module, right click and select Edit Descriptor.
• Select the iAS tab:
  • Deselect Distributed Session so that the field is NOT set.
  • Select Local under Data Synchronization
  • These settings are required because the sample places non-serializable objects into HttpSession. In order to use session replication, an iPlanet value added feature, one must ensure that objects placed into HttpSession implement the serializable interface.
• Click on the EJB References tab and click on New Reference.  Set the following fields:
• Reference: Account
• Bean Type: Entity
• Bean Home Interface: j2eeguide.account.AccountHome
• Bean Remote Interface: j2eeguide.account.Account
• Linked to Bean:  MyAccount
• Close the descriptor window and answer yes when asked to save the changes.
• Click on File->Close to close the j2eeguide-jsptobean.war file.

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-jsptobean.ear
• Add j2eeguide-accountEjb.jar (You will find this file located under ias-samples/j2eeguide/account/assemble/).
• Add j2eeguide-jsptobean.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-jsptobean"
• Save j2eeguide-jsptobean.ear

Deploy the Server Application

See EJB deployment steps in Converter documentation. 

Go to the following URL to exercise the servlet front end:

http://<hostname>/NASApp/j2eeguide-jsptobean/Account.jsp

To create a new account, follow these steps:

      1. In the AccountID field, enter a three-digit integer.

      2. In the Balance field, enter the initial balance (for example, 100.00).

      3. In the First Name and Last Name fields enter your name.

      4. Under Action, select Create.

      5. Click the Submit button.

To credit an account, perform the following tasks:

      1. In the AccoundID field, enter the three-digit account identifier.

      2. In the Amount field, enter the credit amount (for example, 55.00).

      3. Under Action, select Credit.

      4. Click the Submit button.

Review the content of the Account database table directly by using sqlplus or an equivalent tool.

Troubleshooting

As part of your troubleshooting efforts, ensure that you review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

Warehouse: JDBC Transactions

Modifications Made to the Sun Sample

Deploying to iPlanet Application Server

• Compile EJB and Servlet Sources
• Create j2eeeguide-warehouseEjb.jar Module
• Create j2eeguide-warehouse.war Module
• Assemble j2eeguide-warehouse.ear
• Deploy Application

Compile EJB Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the Sample Application Build Facility document for more information on using a build facility to quickly compile the application.

Create j2eeguide-warehouseEjb.jar Module

See Assemble EJB JAR steps in Converter documentation for additional details.

• Create an assemble/ directory under ias-samples/j2eeguide/warehouse/.  Through the Deployment Tool, you will be saving the j2eeguide-warehouseEjb.jar, j2eeguide-warehouse.war and j2eeguide-warehouse.ear files to this directory.
• Launch Deployment Tool.
• Create j2eeguide-warehouseEjb.jar file.
• Insert necessary class files.  For Warehouse, the files to be inserted include:
  • Warehouse.class
  • WarehouseEJB.class
  • WarehouseHome.class
• Modify Descriptor
  • In the General tab, change the Bean Name to "MyWarehouse".
  • Select File->Save to save the name change.
  • Set State Management Type to Stateless
  • Select "Enable RMI/IIOP".
  • Click on Resource Refs tab. Click on New Reference and complete the following fields:
    • Resource Name: jdbc/WarehouseDB  (this is the name used in the WarehouseEJB.java file)
    • Resource Class:  javax.sql.DataSource
    • Authorization: Container
    • JNDI Name: jdbc/j2eeguide/WarehouseDB  (WarehouseDB was registered in iAS through the setup_ora.sh/.bat file).
  • Ensure that the j2eeguide-warehouseEjb.jar window is selected.
• Select File->Save to save the j2eeguide-warehouseEjb.jar file to the assemble/ directory.
• Select File->Close to close the j2eeguide-warehouseEjb.jar window.

This is an optional step. If you plan on using the WarehouseServlet to access the Warehouse EJB, then follow these instructions. If you plan to use the WarehouseClient RMI/IIOP method of accessing the Warehouse EJB, then skip to the next series of steps to create the EAR file.

See Assemble WAR steps in Converter documentation for additional details.

• Create j2eeguide-warehouse.war file.
• Insert WarehouseServlet.class.
• Click on the Web App Descriptor tab.
• Click on the EJB References tab and click on New Reference.  Set the following fields:
• Reference: MyWarehouse
• Bean Type: Session
• Bean Home Interface: j2eeguide.warehouse.WarehouseHome
• Bean Remote Interface: j2eeguide.warehouse.Warehouse
• Linked to Bean:  MyWarehouse
• Click on File->Save to save the war file.  Click on Save when asked to verify if servlet descriptor should be created.
• Click on File->Close to close the j2eeguide-warehouse.war file.

See Assemble EAR steps in Converter documentation for additional details.

• Create j2eeguide-warehouse.ear
• Add j2eeguide-warehouseEjb.jar
• Add j2eeguide-warehouse.war
• Select EAR module, right click and select Edit Descriptor, select Context Root tab and set the Context Root for the WAR module from "/" to "j2eeguide-warehouse"
• Save j2eeguide-warehouse.ear

Deploy the Server Application

See EJB deployment steps in Converter documentation. 

Deploy the Client Application

See client deployment steps in Converter documentation.  Steps for the Warehouse sample are identical to those for Converter except for the following considerations:

• Following files must be copied to the client directory. For example: /opt/rmi-client/j2eeguide/warehouse/:
  • WarehouseClient.class
  • WarehouseHome.class
  • Warehouse.class
  • _Warehouse_Stub.class
  • _WarehouseHome_Stub.class
• Double check that your CLASSPATH and PATH variables are set according to the instructions.  Incorrect CLASSPATH and PATH settings are the most common cause of problems with the RMI/IIOP examples

You have the option of using either the web client or the RMI/IIOP Java application client to exercise the Warehouse sample. Regardless of the client, before running the application, review the initial state of the INVENTORY and ORDER_ITEM database tables.

SQL> select * from order_item;

ORD PRO STATUS
--- --- --------
456 123 open

SQL> select * from inventory;

PRO QUANTITY
--- ---------
123 100

Go to the following URL to exercise the application:

http://<hostname>/NASApp/j2eeguide-warehouse/WarehouseServlet

Compare the following output with the WarehouseServlet.java source code. You should see the following web content displayed in the browser:

looking up java:comp/env/MyWarehouse
lookup ok
create successful
status = shipped

Since the sample client ships a quantity of 8 items of product_id 123, the tables should look like the following after running the sample:

SQL> select * from order_item;

ORD PRO STATUS
--- --- --------
456 123 shipped

SQL> select * from inventory;

PRO QUANTITY
--- ---------
123 92

You can run the sample repeatedly to see the QUANTITY decrease by 8 after each execution.

To force an exception to occur in the middle of the JDBC transaction, follow these steps:

• If you are using Oracle, execute schema/setup_ora.bat/.sh again to reset the database tables for this example. If you are using PointBase, you can remove and recreate the sample table by using the supplied src/schema/warehouse_pb.sql script and the PointBase tools described in Using PointBase with iPlanet guide.
• drop the INVENTORY table.
• run the sample again.
• check the kjs log to see the transaction failure exception:

[01/Aug/2000 18:16:27:1] info: --------------------------------------
[01/Aug/2000 18:16:27:1] info: WarehouseServlet: init
[01/Aug/2000 18:16:27:1] info: --------------------------------------
[01/Aug/2000 18:16:31:0] warning: ORCL-002: PrepareQuery oparse(): ORA-00942: table or view does not exist

[01/Aug/2000 18:16:31:2] warning: EB-invalidate_delegate: instance j2eeguide.warhouse.WarehouseEJB@62937c threw an unchecked or system exception, ex = javax.ej.EJBException: Transaction failed: prepStmt(): unable to prepare an internal statement object
[01/Aug/2000 18:16:31:2] error: Exception Stack Trace:
javax.ejb.EJBException: Transaction failed: prepStmt(): unable to prepare an internal statement object
at j2eeguide.warehouse.WarehouseEJB.ship(WarehouseEJB.java:34)
at j2eeguide.warehouse.ejb_skel_j2eeguide_warehouse_WarehouseEJB.ship(ejb_skel_j2eeguide_warehouse_WarehouseEJB.java:101)
at j2eeguide.warehouse.ejb_kcp_skel_Warehouse.ship__void__indir_wstring__indir_wstring__int(ejb_kcp_skel_Warehouse.java:269)
at com.kivasoft.ebfp.FPRequest.invokenative(Native Method)
at com.kivasoft.ebfp.FPRequest.invoke(Unknown Source)
at j2eeguide.warehouse.ejb_kcp_stub_Warehouse.ship(ejb_kcp_stub_Warehouse.java:399)
at j2eeguide.warehouse.ejb_stub_Warehouse.ship(ejb_stub_Warehouse.java:75)

• Now check the ORDER_ITEM table to ensure that the STATUS still reflects "open".

SQL> select * from order_item;

ORD PRO STATUS
--- --- --------
456 123 open

See Running the Application in Converter documentation.  For Warehouse, you should expect the following output on the client side:

root@ias-{$PWD}: java j2eeguide.warehouse.WarehouseClient localhost 9010

The output from the WarehouseClient application should be almost identical to the output seen when running the WarehouseServlet client.

Follow the steps in running the web client to verify that the application is running correctly. Then force an exception to occur during the transaction.

Troubleshooting

As part of your troubleshooting efforts, ensure that you review the General Troubleshooting section to learn how to view logs files. Also review the Troubleshooting section of the RMI/IIOP chapter of the Developer's Guide.

Other EJB Examples

For the remaining EJB examples, review the Sun sample descriptions and examine the complete XML deployment descriptors and build.xml files to develop an understanding as to how to deploy the samples to iPlanet. As long as you've tried the Converter sample and perhaps several of the samples above, you should be able to determine how to deploy and exercise the following samples:

• enroller
• order
• salesrep
• storagebin
• teller

The basic steps for deploying each of these applications is to:

1. Read the corresponding Sun tutorial section.
2. Create and populate database tables with the setup_ora script (if necessary).
3. Deploy the pre-existing EAR file.
4. Access the application via either RMI/IIOP or through the web interface.

iPlanet is in the process of packaging the following sample for iPlanet and will publish them on developer.iplanet.com shortly:

• jsptag
• converter (with Application Client Container)
• urlconnect