Java^TM Pet Store 1.1.2 on iPlanet
iPlanet^TM Application Server Samples

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

Java Pet Store 1.1.2 is the Sun J2EE sample application that demonstrates many facets of the J2EE specification. See the Architectural Overview document for more information regarding the design and implementation of this popular J2EE application. The Blueprints area of http://java.sun.com offers many resources on the design of J2EE applications.

Implementation of Pet Store on iPlanet enables you to develop an understanding of the value added features provided by the iPlanet J2EE platform. After you deploy and run the application on iPlanet, you will be able to explore load balancing, clustering and other aspects of the iPlanet platform that enhance the portable Java Pet Store application.

Changes Made to the Sun's Java Pet Store describes the changes made to Sun's Pet Store application in order to run it on iPlanet Application Server.

Setting Up the Environment

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

Configuring the Database describes how to register the JDBC data sources for the Pet Store application.

Select one of two approaches to deploying the application:

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

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the Pet Store application.

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

Known Issues describes known problems with the sample

Further Exploration

Modifying the Deployment Decriptor describes how to modify the application to use a database other than PointBase.

Recompiling and Assembling the Application demonstrates the use of Ant to recompile the sources and rebuild the WAR and EJB modules and the overall EAR file of the application.

Deploying the Administrative Application describes how to deploy and run the administrative application made available in Java Pet Store 1.1.2.

Deploying the Mailer Mini Application describes how to deploy and run the mailer mini application made available in Java Pet Store 1.1.2.

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

Performance Testing the Pet Store Application describes how to tweak the application configuration and application server settings to maximize performance of the application.

Enabling Order Confirmation via E-mail explains how to configure e-mail based notification of events via iPlanet's Java Mail interface.

Exercising the Excel and Staroffice Demos describe how to use popular spreadsheet applications to view order information via HTTP access to the Pet Store application.

Changes Made to Sun's Java Pet Store

Support for PointBase
Since the Java Pet Store Application from Sun Microsystems does not support PointBase as a database, iPlanet enhanced the application to allow PointBase to be supported. The affected files are:

• components/customer/src/ejb-jar.xml: The "ejb/order/OrderDAOClass" parameter has been modified to support PointBase as the default database.
• components/customer/src/com/sun/j2ee/blueprints/customer/order/dao/OrderDAOPointBase.java : (new file) Contains code to interface with PointBase.
• petstore/src/docroot/WEB-INF/sql/PointBase.sql: Contains sql code to populate tables into PointBase.
• petstore/src/docroot/populate_install.jsp: Added a link to install PointBase tables.
• petstore/src/com/sun/j2ee/blueprints/tools/populate/web/PopulateServlet.java: Added support for PointBase as a database.

PointBase is the default database used in the copy of Java Pet Store included in iPlanet Application Server.

Request Mappings XML File Modified
Since iPlanet has not yet certified the Japanese language support in this sample, the reference to the Japanese language screen definitions was removed from the following file:

petstore/src/docroot/WEB-INF/xml/

<screen-definition url="/WEB-INF/xml/ja/screendefinitions.xml" language="ja_ JP"/>

URL Modified in populate.jsp

The populate.jsp file was modified to work around a <welcome-file-list> issue in the application server. A "/" was added to just after the getContextPath() call:

<td> <a href="<%=request.getContextPath()%>/" ><font color="white">Return to Java Petstore Demo</font></a></td>

Ant build.xml Enhancements
The Ant-based build.xml files were enhanced to support iPlanet-specific EJB compiler and deployment functions.

Configuring the Database

iPlanet supports and has tested deployment of Java Pet Store on iPlanet against PointBase, Oracle and Sybase databases. By default, PointBase is configured as the default database. Other databases supported by the application server should work in conjunction with Pet Store, but iPlanet has not tested these combinations. Please use the PointBase, Oracle and Sybase sample configuration files as the basis for using other databases.

In Java Pet Store 1.1.2 database population occurs automatically during the first interaction with the application. In previous versions of the application separate setup steps were required to populate the database. Although the database is populated automatically, you are still required to setup the JDBC database driver and JDBC datasources used by the application.

Running Pet Store with PointBase

Running Pet Store with Oracle or Sybase

To use a database other than PointBase, you will need to follow these steps:

1. Register JDBC Driver
2. Identify RDBM User
3. Register JDBC Datasources
4. Modify Deployment Decriptor

1. Register JDBC Driver

For installations that will not use PointBase, 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 client driver. A subsequent section of this document describes how to register the JDBC data sources required by the sample.

You have the option of using either the iPlanet Type 2 JDBC driver or an external driver such as the Oracle Type 4 JDBC driver. A Type 4 driver is easier to configure in that it requires only a JAR file containing the RDBM client classes. Type 2 drivers require native client libraries.

• Third Party JDBC Driver
• iPlanet Type 2 JDBC Driver

Register Third Party JDBC Driver

UNIX:

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

a) Enter the application server installation root directory:

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

b) Select option 2, Third Party JDBC Drivers

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

Select the component you want to install (1/2) [1]:

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

For example, for Oracle Type 4, the sample uses "ora-type4"

For example, for Sybase jConnect, the sample uses "jconnect".

d) Enter the driver class name.

For example, for Oracle, "oracle.jdbc.driver.OracleDriver"

For example, for Sybase, "com.sybase.jdbc2.jdbc.SybDriver"

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

For example, forOracle, "<ORACLE_HOME>/jdbc/lib/classes12_01.zip"

For example, for Sybase, "<jConnect install>/classes/jconn2.jar"

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

g) Restart the application server using the iascontrol kill and iascontrol start commands. Refer to the Getting Started section for more information. You must use the kill subcommand to ensure that the Java Engines (kjs') are completely stopped.

h) The next step is to identify an RDBMS user under which you will create and populate the application tables.

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

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

For example, for Oracle Type 4, the sample uses "ora-type4"

For example, for Sybase jConnect, the sample uses "jconnect".

b) Enter the driver class name.

For example, for Oracle, "oracle.jdbc.driver.OracleDriver"

For example, for Sybase, "com.sybase.jdbc2.jdbc.SybDriver"

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

For example, forOracle, "<ORACLE_HOME>/jdbc/lib/classes12_01.zip"

For example, for Sybase, "<jConnect install>/classes/jconn2.jar"

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

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

f) The next step is to identify an RDBMS user under which you will create and populate the application tables.

Register iPlanet Type 2 JDBC Driver

Determine if the iPlanet Type 2 Driver is Registered

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.
4. If you see a red X on the client driver entry of interest, then you need to run the db_setup.sh script to register the native client driver with the application server. Go to the next section to register the driver.

Register iPlanet Type 2 Driver if Necessary

UNIX: Database Driver Registration

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

install_dir/ias/bin/db_setup.sh

3. Follow the instructions to register the iPlanet Type 2 native client driver. The default iPlanet installation root directory is /usr/iplanet/ias6.
4. For the Pet Store 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. After you've registered the driver, you can use the Admin Tool to verify that the native driver entry no longer shows a red X and that the client library and other settings are accurate

2. Identify an RDBMS User

To define a new Oracle user:

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



SQL > create user estore identified by estore;

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

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



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

3. Register JDBC Datasources

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

The Pet Store datasource files for PointBase do not require modification.
 

Driver Type	Sample Datasource XML Files	What to Change?
PointBase Type 4 JDBC Driver	EstoreDB-pointbase-type4.xml InventoryDB-pointbase-type4.xml SignOnDB-pointbase-type4.xml	nothing
Oracle Type 4 JDBC Driver	EstoreDB-ora-type4.xml InventoryDB-ora-type4.xml SignOnDB-ias-syb-type2.xml	<driver-type> <database-url> <username> <password>
Sybase JConnect Type 4 JDBC Driver	EstoreDB-syb-type4.xml InventoryDB-syb-type4.xml SignOnDB-syb-type4.xml	<driver-type> <database-url> <username> <password>
iPlanet Type 2 JDBC Driver for Oracle	EstoreDB-ias-ora-type2.xml InventoryDB-ias-ora-type2.xml SignOnDB-ias-ora-type2.xml	<datasource> <username> <password>
iPlanet Type 2 JDBC Driver for Sybase	EstoreDB-ias-syb-type2.xml InventoryDB-ias-syb-type2.xml SignOnDB-ias-syb-type2.xml	<datasource> <username> <password>

The following is an example of the EstoreDB datasource XML file as configured for an Oracle Type 4 JDBC driver. Note that the <database> and <datasource> tags are not required when registering datasources for third party JDBC drivers.

Oracle Type 4 example,

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

<ias-resource>
<resource>
<jndi-name>jdbc/estore/EstoreDB</jndi-name>
<jdbc>
<driver-type>jconnect</driver-type>
<database-url>jdbc:sybase:Tds:192.138.151.39:4444</database-url>
<username>estore</username>
<password>estore</password>
</jdbc>
</resource>
</ias-resource>

For example, to use PointBase,

1. Go to the directory
install_dir/ias/ias-samples/jps1.1.2/schema.

2. Eexecute the following commands to register the JDBC datasources:

iasdeploy regdatasource EstoreDB-pointbase-type4.xml

iasdeploy regdatasource InventoryDB-pointbase-type4.xml

iasdeploy regdatasource SignOnDB-pointbase-type4.xml

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

Command Line-based Deployment

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

If you've decided to use a database other than PointBase, you must first modify the deployment descriptor to specify the appropriate database.

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

Deploying the petstore.ear file is simple.

1. To use the pre-built EAR file as configured for PointBase, go to the root of the Pet Store sample directory:

install_dir/ias/ias-samples/jps1.1.2/

Alternatively, if you modified the deployment descriptor to support a database other than PointBase, you will navigate to the location at which the reassemble EAR file exists:

install_dir/ias/ias-samples/jps1.1.2/src/petstore/build/

iasdeploy deployapp petstore.ear

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 "petstore" 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/petstore/ directory.

Otherwise, you're ready to exercise the Pet Store application by Running the Application.

GUI-Based Deployment

Open Pre-existing EAR File

Open the pre-existing Pet Store 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

2. Open the EAR file

In the startup dialog, select "Browse for more applications" to find the petstore.ear file.

Navigate to ias/ias-samples/jps1.1.2/ and open the petstore.ear file.

Select Component View

Click on the file name to expand the EAR file.

3. If you are not using PointBase, you must modify the application's deployment descriptor to specify the appropriate database. Do this now before deploying the application.

Deploy the Application

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

2. Select File -> Deploy

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

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

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

Verifying Registration

If you don't already have the Application Server Administrative Tool running, see the Getting Started section for startup instructions.

1. 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.
2. You should see several folders for the "petstore" J2EE application. The "petstore" folder with the world icon represents the web application module while the "*Ejb" folders represent the EJB modules packaged as part of the Pet Store application.

1. Execute kregedit from the command line to start the iPlanet Registry Editor.
2. Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.
3. Browse the J2EE-Application/ tree and look for the "petstore" application.
4. Expand the "petstore" folder and explore this portion of the directory tree. Note the modules that make up the Pet Store application.
5. Now open the J2EE-Module/ tree and look for the "petstore" web application module entry and the "*Ejb" EJB module entries that you noted earlier.
6. Expand each of these folders and explore their contents.
7. Once you find the GUID associated with each EJB in the Pet Store 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

http://<hostname>/NASApp/estore/index.html

Populate the Database (first run only)
If this is the first time the application has been run, a page will be displayed to populate the database.

Select the Install Tables link and then choose the appropriate database. Assuming you are using PointBase, select the PointBase entry.

After a few moments a page will be displayed indicating that the database tables have been populated.

Run the Application

Once you've successfully populated the database, access the store's main page again:

http://<hostname>/NASApp/estore/index.html

If you experience problems when accessing the application, read through the troubleshooting section for assistance.

Note that the URL above contains "estore" rather than "petstore". Since the context root of the petstore.war module has been set to "estore" in the application.xml file, you use "estore" in place of "petstore" to refer to the web application components.

Explore the Application
Browse through the application by adding various pets to your shopping cart. When you are ready to order, either login as the predefined "j2ee" customer with password "j2ee" or create a new account.

Note that when you attempt to place an order and have not already signed in, the authentication mechanism will automatically prompt you for a user name and password before granting access to the place order screen. If you had already signed in, then the authentication page would have been bypassed and you would have proceeded directly to the place order screen.

You might find it helpful to review the Architectural Overview document to understand the design approach for the Pet Store application.

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

Known Issues

Search functionality does not work with Pointbase

The version of Pointbase which ships with iPlanet Application Server 6.0 sp3 does not support SQL subqueries which are needed for the search functionality. Therefore, the search functionality will not work with Pointbase.

Auto Install of Tables does not work for Oracle as the database if user is not estore

This issue is still being investigated. As a workaround, use estore as the database user.

Troubleshooting

Problem: Error: 500 SC_INTERNAL_SERVER_ERROR No detailed message after clicking on an image in the first page. kjs log shows general failure while attempting to obtain a database connection.

[02/Jun/2000 18:41:21:4] info: --------------------------------------

[02/Jun/2000 18:41:21:4] info: jsp.APPS.estore.productcategory: init

[02/Jun/2000 18:41:21:4] info: --------------------------------------

com.sun.estore.control.GeneralFailureException at com.sun.estore.catalog.model.CatalogImpl.getDBConnection(CatalogImpl. java:171) at com.sun.estore.catalog.model.CatalogImpl.getCategory(CatalogImpl.java :38) at jsp.APPS.estore.productcategory._jspService(productcategory.java:78) at jsp.APPS.estore.productcategory.service(productcategory.java:39) at javax.servlet.http.HttpServlet.service(HttpServlet.java:865) at com.netscape.server.servlet.servletrunner.ServletInfo.service(Unknown Source) at com.netscape.server.servlet.servletrunner.ServletRunner.callJSP(Unkno

• Probable cause: The JDBC datasources for Pet Store were not registered with the application server. If you start kregedit and look at the following area, you will probably either not see an entry for estore or the entries for estore contain incorrect database login information.

SOFTWARE\iPlanet -> Application Server -> 6.0 -> DataSource

• Solution: Follow the instructions in the Database Setup section to setup the database tables and to register the JDBC datasource with the application server. Restart your browser and try the application again. It is not necessary to restart the application server and web server.

[25/Aug/2000 10:27:14:7] error: BINDER-OS: (LoadLibrary) No such file or directory
[25/Aug/2000 10:27:14:7] error: BINDER-008: GXBindWorker: error loading library libgxorcl2.so
[25/Aug/2000 10:27:14:7] error: DATA-108: failed to create a data connection with any of specified drivers
com.sun.estore.control.GeneralFailureException
at java.lang.Throwable.fillInStackTrace(Native Method)
at java.lang.Throwable.fillInStackTrace(Compiled Code)
at java.lang.Throwable.<init>(Compiled Code)
at java.lang.Exception.<init>(Compiled Code)
at java.lang.RuntimeException.<init>(RuntimeException.java:37)
at javax.ejb.EJBException.<init>(EJBException.java:58)

• Probable cause: Typically applies only to UNIX. The database client driver was not registered with the application server.
• Solution: Follow the Register Database Driver instructions to register the native database client driver.

Modifying the Deployment Descriptor

Since the JPS 1.1.2 sample application that ships with iPlanet is configured to use PointBase, you need to modify the application's deployment descriptor when using a database other than PointBase.

You can modify the deployment descriptor directly using the iPlanet Application Server registry editor or you can change the deployment descriptor file, regenerate and redeploy the petstore.ear file.

Using the Application Server Registry Editor

1.Execute <application server install path>/ias/bin/kregedit to start the Registry Editor GUI.
2.Navigate to the SOFTWARE/Netscape/Application Server/6.0/ portion of the tree.
3.Expand the J2EE-Module/ tree and look for the "customerEjb" module.
4.Expand the "customerEjb" module, expand "ejbs"
5.Note the GUID number associated with the TheOrder EJB.
6.Go up to the "6.0/" folder and expand the "ClassDef/" portion of the tree.
7.Expand the folder that has the same GUID as the TheOrder EJB.
8.Expand the folder that has a version number.
9.Expand the "EntityDescriptor/" folder.
10.Expand the "env-entry/" folder.
11.Expand the folder "ejb/order/OrderDAOClass"
12.Double click on an "env-entry-value" to change its value. For example, if Oracle is the target database, then enter "com.sun.j2ee.blueprints.customer.order.dao.OrderDAOOracle"
13.After you've changed the necessary environment entries, exit the Registry Editor.

Since you have not yet run the PetStore application, there is no need to restart the application
server. The environment property values will be read in as soon as the TheOrder EJB is
loaded into memory.

1. Go to install_dir/ias/ias-samples/jps1.1.2/src/components/customer/src/ejb-jar.xml

1. Edit the env entry "ejb/order/OrderDAOClass" to specify the implementation class for the database of your choice. For example, to use Oracle, the entry should be:

   <env-entry>
<env-entry-name>ejb/order/OrderDAOClass</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>com.sun.j2ee.blueprints.customer.order.dao.OrderDAOOracle</env-entry-value>
</env-entry>

   Valid class names are:

   • com.sun.j2ee.blueprints.customer.order.dao.OrderDAOOracle
   • com.sun.j2ee.blueprints.customer.order.dao.OrderDAOSybase
   • com.sun.j2ee.blueprints.customer.order.dao.OrderDAOCS (Cloudscape - not tested with iPlanet)
   • com.sun.j2ee.blueprints.customer.order.dao.OrderDAOPointbase
     
     
2. Recompile and reassemble the application using the Ant-based command line utilities:

cd install_dir/ias/ias-samples/jps1.1.2/src/petstore/src
build clean
build core

These steps will clean out the existing build directory and rebuild the entire application from scratch. The rebuilt EAR file will be placed in:

install_dir/ias/ias-samples/jps1.1.2/src/petstore/build/petstore.ear

At this stage, you are ready to deploy the EAR file.

Now proceed with deploying the application.

Recompiling and Assembling the Application

Depending on the types of changes you've made to the Pet Store application, you can use different combinations of build targets to reassemble and redploy the application. In order to generate a base set of compiled classes, you should follow the Building From Scratch instructions first and then experiment with the other scenarios.

Building from Scratch
Only Deployment Descriptors Have Changed
Only Helper Classes or Web Components Have Changed

Building from Scratch

1. Compile and Assemble EJB JAR Components and Web Application

Execute "build" under jps1.1.2/src/petstore/src/

The default target core will be executed to rebuild the component EJBs JAR files and the petstore web application's EJB JAR and WAR files as well as the web application's EAR file.

Execute "build deploy" under jps1.1.2/src/petstore/src/

An application server restart will be necessary if you've modified either deployment descriptors or EJBs.

Only Deployment Descriptors Have Changed

Then redeploy application using "build deploy" and restart the application server to pick up the descriptor changes. After the server restarts, test the application.

Only Helper Classes or Web Components Have Changed

Execute "build compile" if you've changed either servlet or helper classes.

Then execute "build ear" to recreate the EAR file.

Finally, execute "build update_ear" to copy the necessary files to the runtime environment without performing a formal registration of the application.

Test the application.

Note that the update_ear target is a relatively complex target in that it entails knowledge of the exact layout of the runtime application deployment directory structure. If you build a similar target for your own application, pay close attention to exactly where the files are being copied.

These steps assume that the classes and EJB JAR files for the EJBs already exist.

Clustering the Application

To demonstrate the true power of the application server's session replication and failover capabilities, see the Cluster sample applications. Once you've setup and exercised the simple HaServlet sample, you can cluster the Bank application and take full advantage of iPlanet's combined load balancing, session replication and failover features.

Although Pet Store as an application does not support replication of its HttpSession data, you can configure Pet Store to leverage the load balancing capabilities of the application server and to make use of multiple JVMs across multiple application server instances in a cluster. To do this, one must ensure that the application is configured with these key settings:

• MainServlet (also known as "webTierEntryPoint") is configured as "sticky" in the ias-web.xml file so as to ensure that all web requests associated with the same user session get directed to the exact same JVM (kjs). The webTierEntryPoint servlet is the only servlet/JSP that is accessed directly by web clients, it is sufficient to set sticky for only this servlet/JSP. Since "sticky" is the default setting for MainServlet as it is packaged with iPlanet Application Server, you should not need to change this setting.

<servlet>
<servlet-name>webTierEntryPoint</servlet-name>
<guid>{A1E703EE-EA6E-18A9-EEAF-080020877B69}</guid>
<validation-required>false</validation-required>
<servlet-info>
<sticky>true</sticky>
<encrypt>false</encrypt>
<number-of-singles>10</number-of-singles>
<disable-reload>false</disable-reload>
</servlet-info>
</servlet>

• Also in the ias-web.xml file, session implementation for the web application is set to "lite" so as to limit availability of session data to only that JVM on which a session is instantiated. (This limitation is due to the design of the Pet Store application rather than any limitations of the underlying application server).

<session-info>
<impl>lite</impl>
<dsync-type>dsync-local</dsync-local>
<timeout-type>last-access</timeout-type>
<secure>false</secure>
<domain></domain>
<path></path>
<scope></scope>
</session-info>

Multiple Web Server Instances Require Domain Setting in Web App Descriptor

JDBC Data Sources Must be Registered on Each App Server Instance

Application Must be Registered on Each App Server Instance

Next Steps

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

2. Register the JDBC datasources on each application server instance. See the Register Datasources section for details.

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

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

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

Performance Testing the Application

• Migrate Static Web Content to the Web Server Tier
• Consider Using JSP Caching for Shared Pages
• Disable Session Replication if Desired
• Ensure Application Server Environment is Tuned

Migrate Static Web Content to Web Server Tier

• Copy all *.html, *.js and images/ files from the jps1.1.2/src/petstore/src/docroot/ to the web server's docroot. For example, to <webserver docroot>/ias-samples/estore/.
• Modify links to suit new location of static content:
• Modify <webserver docroot>/estore/index.html to point to /NASApp/estore/...
• modify all JSP files to refer to correct image locations.

Consider Using JSP Caching for Shared Pages

Disable Session Replication if Desired

Refer to the chapter entitled "Packaging for Deployment" in the iPlanet Application Server's Java Programmer's Guide on http://docs.iplanet.com for more information on session replication configuration.

Ensure Application Server Environment is Tuned

• Database connection pool size and timeouts
• Thread counts for Executive Server (kxs) and Java Engines (kjs)

Deploying the Administrative Application

Populating the Directory describes how to add an initial set of Pet Store administrators to the LDAP-based Directory Server.

Deploying and Running the Application describes how to deploy and access the PetStore Admin appplication

Populating the Directory

Prepare the LDIF File

1. Edit the file install_dir/ias/ias-samples/jps1.1.2/schema/EstoreUser.ldif
2. Change all "iplanet.com" references to the same domain name as used in your directory server installation. For example, change all "iplanet.com" entries to "mycompany.com". Depending on your domain setting you may have to specify two or three level domain names. For example, "group.mycompany.com" might be necessary in place of "mycompany.com".

GUI-Based Directory Server Administrative Tool

If you don't already have the Directory Server Administrative Tool running, see the Getting Started section for startup instructions.

In the Directory Server Administrative Tool, click on Configuration tab and select the Database node. Then select the menu item Object->Import.

Click on Browse to navigate to the following location:

install_dir/ias/ias-samples/jps1.1.2/schema

To review the new additions, click on the Directory tab and expand the folder containing your domain name. Under Groups, you should see EstoreAdmin. Under People, your should see three estore users.

Now that you've defined and populated the database tables, defined the necessary JDBC driver and datasources and added the Java Pet Store entries to the directory server, proceed to either the Command Line Deployment section or the GUI-Based Deployment section to deploy the application.
 

ldapmodify Command Line Interface

• ldapmodify on UNIX
• ldampmodify on Windows

UNIX: ldapmodify

ps -ef | grep slapd

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

export LD_LIBRARY_PATH=install_dir/ias/gxlib:$LD_LIBRARY_PATH

For example,

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

This setting will enable ldapmodify to find the necessary libraries.

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

For example,

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

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

adding new entry cn=EstoreAdmin, ou=Groups, o=iplanet.com

Where:

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

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

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

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

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

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

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

ldap_add: No such object

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

Windows: ldapmodify

Start->Settings-Control Panel and start Services.

Verify that Netscape Directory Server is running.

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

Where:

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

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

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

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

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

ldapmodify -D"cn=Directory Mana...

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

ldap_add: No such object

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

Deploying and Running the Application

1. Go to the root of the Pet Store sample directory:

install_dir/ias/ias-samples/jps1.1.2/

iasdeploy deployapp petstoreadmin.ear

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

http://<hostname>/NASApp/estoreadmin/index.html

As the main page is displayed, click on the link and login as the user "jps_admin" with password "admin". On the Manage Orders screen, you can modify the status of all pending orders.

As an experiment, you can bring up two browsers: one to interact with the mainstream Java Pet Store web application and another to run the administrative application. As orders are placed, you will see updates in the administrative application.

Deploying the Mailer Mini Application

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

1. Go to the install_dir/ias/ias-samples/jps1.1.2/schema/ directory and edit the mail-resource.xml file. Change the host, mail server user name and reply to address fields to suit your environment.

<ias-resource>



   <resource>



   <jndi-name>mail/estore/MailSession</jndi-name>



   <mail>



   <host>mailserver.iplanet.com</host>



   <name>juser</name>



   <address>juser@iplanet.com</address>



   </mail>



   </resource>



</ias-resource>

iasdeploy regdatasource mail-resource.xml

install_dir/ias/ias-samples/jps1.1.2/

iasdeploy deployapp mailerapp.ear

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

http://<hostname>/NASApp/mailerapp/index.jsp

As the main page is displayed, click on the link "Try the Blueprints Mailer". On the Blueprints Mailer screen, you can fill in the fields to send a mail.

Enabling Order Confirmation via E-mail

1. Under the Java Pet Store web application source directory, modify the ejb-jar.xml file so that the env-entry-value of sendConfirmationMail is true:

     <env-entry-name>sendConfirmationMail</env-entry-name>



     <env-entry-type>java.lang.Boolean</env-entry-type>



    <env-entry-value>true</env-entry-value>

     <resource-ref>

        <res-ref-name>mail/MailSession</res-ref-name>

        <jndi-name>mail/estore/MailSession</jndi-name>

    </resource-ref>

<ias-resource>



   <resource>



   <jndi-name>mail/estore/MailSession</jndi-name>



   <mail>



   <host>mailserver.iplanet.com</host>



   <name>juser</name>



   <address>juser@iplanet.com</address>



   </mail>



   </resource>



</ias-resource>

iasdeploy regdatasource mail-resource.xml

6. After modifying the sendConfirmationMail environment entry (either in the XML file or directly in the Registry), restart the application server to pick up the environment setting change.

7. To exercise the configuration, enter the Pet Store application and sign in as the "j2ee" user. Select "MyAccount" and change the e-mail address to a valid address. Perform a shopping order cycle to trigger generation of a mail message confirming your purchase.

The confirmation e-mail message that is sent to the specified address should resemble the following:

Subject: Your order#4
Date: Tue, 9 Jan 2001 20:53:30 -0800 (PST)
From: root@canteloupe.red.iplanet.com
To: ckamps@iplanet.com

This mail is a confirmation for your order# 4
Please save it for your records.
Your order will be shipped to:
ABC XYX
The total cost of your order is $23.5