Clustered Stateful Session Beans
iPlanet^TM Application Server Samples

If you have already configured the Stateful Session Bean clustering samples, then you can run the application by clicking here.

Clustering can provide failure and high availability. This example application demonstrates how a stateful session bean may be shared or load balanced between all machines in a cluster, with the stateful session information  or "shopping cart" information surviving an abnormal condition in any server in the cluster.

Setting Up the Environment

Getting Started includes a checklist of prerequisites for deploying sample applications to iPlanet.

Prior to running this sample, read the overall instructions for setting up a simple cluster using iPlanet Application Server.

Deploying and Running the Application

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

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the sample application. It also addresses assembling the application from scratch using the Deployment Tool.

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

Known Issues describes the known problems in the sample and suggested workarounds.

Further Exploration

Exercising the Cluster describes how to explore clustering capabilities and simulate failures.

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

Modifying Domain Setting via iPlanet Registry describes how to change a key clustering value in the runtime environment.

Command Line-based Deployment

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

There are two steps to deploying the application:

1. Modify Session Domain Setting
2. Deploy Application

Modify Session Domain Setting

Since the cluster application contains a domain setting that is unique to your network environment, you cannot exercise a multi-machine cluster without first modifying a domain name setting in the application. 

The application server automatically inserts the domain parameter into cookies when the application is accessed by a browser. With no domain set, the browser will return the cookie to only the host of the web server that sent the cookie to the browser. Since in this HA example we are using multiple web servers, each with a different host name, we must ensure that the browser can send application web requests and the embedded session tracking cookies to either web server host associated with the cluster.

For example, server1.central.sun.com and server2.sun.central.sun.com. The domain string argument must contain at least 2 or 3 periods (3 period-domains apply to domains like acme.co.uk). If the domain is set to acme.com, then the session cookies can be returned from the browser to any web server hosts in the acme.com domain.

To modify the domain name, you have two choices:

1. Modify the domain setting in the ias-web.xml deployment descriptor, rebuild the WAR and EAR files and register the application.
2. Manually register the supplied EAR file and then modify domain setting in the iPlanet Application Server Registry.

Modifying this setting in the ias-web.xml file is preferred because the change will be present each time you deploy the application to the application server. See the following instructions for modifying the ias-web.xml file.

To modify the domain setting in the ias-web.xml file:

1. Edit cluster/sfsb/src/ias-web.xml
2. Change the <domain> field to match the overall domain of your network environment.

   <session-info>
   <impl>distributed</impl>
   <dsync-type>dsync-distributed</dsync-type>
   <timeout-type>last-access</timeout-type>
   <secure>false</secure>
   <domain>iplanet.com</domain>
   <path>/</path>
   <scope></scope>
   </session-info>

3. Rebuild the application by executing the build command:

   build

On UNIX, prior to executing the build command, you need to ensure that install_dir/ias/bin is in your PATH.

Executing the build command will compile the application source files and reassembles the WAR, EJB JAR and EAR files. The EAR file will be placed in:

cluster/sfsb/assemble/ear/

See  the Compiling and Assembling the Application section for more details on rebuilding the application.

Deploy the Application

Deploy to Local Instance First

Deploying either the pre-existing or newly assembled cluster-sfsb.ear file is simple.

1. Go to the assembly location under the sample directory:

nstall_dir/ias/ias-samples/cluster/sfsb/assemble/ear/

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

iasdeploy deployapp cluster-sfsb.ear

Refer to the Getting Started section for more information on using the iasdeploy command.

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 file
  • registers the J2EE application "cluster-sfsb" in the iPlanet Registry within the directory server
  • registers the embedded WAR and EJB JAR modules in the iPlanet Registry within the directory server
  • extracts the WAR and EJB JAR modules to the JAR/ directory.
  • expands the content of the WAR and EJB JAR modules to the APPS/cluster-sfsb/ directory.

Deploy to Remaining Instances

Since you are setting up a cluster, you will need to deploy the application to each application server in the cluster. The iasdeploy command has the ability to perform remote deployments to application server instances. Assuming that you've already registered the application server instances in the application server administrative tool, you can simply execute the following command to deploy the application to a remote instance:

iasdeploy deployapp -instance iAS2 cluster-sfsb.ear

Where iAS2 represents the logical name assigned to the second instance in the cluster. Start the application server administrative tool to determine the name of the second instance.

Refer to the Getting Started section for more information on using the iasdeploy command.

Now you're ready to exercise the sample by Running the Application.

GUI-Based Deployment

Two approaches to using the Deployment Tool are described:

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

or

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

Import Pre-existing EAR File

Open the Pre-existing Cluster-SFSB EAR File

1. Launch the Deployment Tool on one of the two machines in the cluster.

UNIX:

Execute nstall_dir/ias/bin/deploytool

Windows:

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

2. Open the cluster-sfsb.ear file

• In the startup dialog, select "Browse for more applications" to find the cluster-sfsb.ear file.
• Navigate to ias/ias-samples/cluster/sfsb/ and open the cluster-sfsb.ear file.
• Click on the file name to expand the EAR file.
• Click on Component View to see the components of the web application and EJB JAR file.
• Proceed to Deploying the Application

• Select the HA SFSB JSP WAR module, right click and select Edit Descriptor so that you can modify the domain setting of the web application.
• Select the IAS tab.
• In the Domain text box, enter the domain name associated with network in which the web server machines are located.

The application server automatically inserts the domain parameter into cookies when the application is accessed by a browser. With no domain set, the browser will return the cookie to only the host of the web server that sent the cookie to the browser. Since in this HA example we are using multiple web servers, each with a different host name, we must ensure that the browser can send application web requests and the embedded session tracking cookies to either web server host associated with the cluster.

For example, server1.central.sun.com and server2.sun.central.sun.com. The domain string argument must contain at least 2 or 3 periods (3 period-domains apply to domains like acme.co.uk). If the domain is set to acme.com, then the session cookies can be returned from the browser to any web server hosts in the acme.com domain.

• Click on the X of the upper right hand corner of the web application descriptor to save and close the descriptor.
• Select the cluster-sfsb J2EE application. Select File->Save to save the WAR level changes to the EAR file.

Assemble the Application

• Compile Application Sources
• Create cluster-sfsb.war Module

Create cluster-sfsbEjb.jar Module
• Assemble cluster-sfsb.ear
• Deploy Application

Compile Application Sources

To compile the application sources, simply execute "build compile" under the application's src/ directory. See the section Compiling and Assembling the Application for more information on recompiling the application using the supplied build facility.

Create WAR Module

Identify the Content for WAR File

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

• Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
• Choose the path install_dir\ias\ias-samples\cluster\sfsb\build\lib\classes
• Click on the double arrows (>>) to move the ControllerServlet.class file into right side of the dialog window.
• Add the HostInfo.class and the BeanInfo.class files in install_dir\ias\ias-samples\cluster\sfsb\build\lib\classes\samples\cluster\sfsb\beans into the WAR module.
• Click on Resolve to determine if the class depends on classes that are not part of the WAR module.
• Click on Insert to add the class to the WAR module.
• Add the file install_dir\ias\ias-samples\cluster\sfsb\src\docroot\HaSfsb.jsp to the WAR (Set "Update destination path to "/")
• Click on File View to see the complete list of files added to the module.

Modify Web Application Descriptor

For each tab listed below, set the name fields to the associated values.

1. General Tab

Name	HA SFSB JSP
Distributable	checked/enabled
Session Timeout (seconds):	-1 (take server default of 500 seconds)

 

Distributed Session	checked/enabled
Timeout (seconds):	-1 (take server default of 500 seconds)
Timeout Type	Since last access
Domain	Domain name of the network in which your web servers are located. For example "iplanet.com". The domain parameter is used in the session cookie for this application. With no domain set, the browser will return the cookie to only the host of the web server that sent the cookie to the browser.  This setting is especially important when multiple web servers are in front of one or more app servers. If multiple web servers are used, the domain allows the browser to return the cookie to any web server in that domain. For example, server1.central.sun.com and server2.sun.central.sun.com. The domain string argument must contain at least 2 or 3 periods (3 period-domains apply to domains like acme.co.uk). If the domain is set to acme.com, then the session is visible to foo.acme.com, bar.acme.com, etc.
Data Synchronization	Distributed

Save and close cluster-sfsb.war

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

Create cluster-sfsbEjb.jar Module

Identify the Content for JAR File

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

• Select the JAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert Files...)
• Choose the path install_dir\ias\ias-samples\cluster\sfsb\build\lib\classes

Move all the classes in the directory install_dir\ias\ias-samples\cluster\sfsb\build\lib\classes\samples\cluster\ejb\ into the EJB JAR file.
• Click on Resolve to determine if the class depends on classes that are not part of the WAR module.
• Click on Insert to add the classes to the JAR module.
• Click on File View to see the complete list of files added to the module.

Modify EJB JAR Application Descriptor

For each tab listed below, set the name fields to the associated values.

1. General Tab

Bean Name	Ha
Failover	checked/enabled

Save and close cluster-sfsbEjb.jar

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

Assemble cluster-sfsb.ear

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

• Select the cluster-sfsb EAR entry.
• Right click, select Insert Files.
• Navigate to the install_dir\ias\ias-samples\cluster\sfsb\assemble\ directory.
• Select cluster-sfsb.war WAR file.
• Click on the double arrows (>>) to move this file into right side of the dialog window.
• Click on Resolve to modify the location of this file relative to the root of the EAR file.
• Select the file.
• Set the Update Destination Path to blank since the J2EE module should appear at the root of the EAR file. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
• Click on Insert to close the insert dialog window and to add the file to the EAR.

• Select the cluster-sfsb EAR entry.
• Right click, select Insert Files.
• Navigate to the install_dir\ias\ias-samples\cluster\sfsb\assemble\ directory.
• Select cluster-sfsbEjb.jar JAR file.
• Click on the double arrows (>>) to move this file into right side of the dialog window.
• Click on Resolve to modify the location of this file relative to the root of the EAR file.
• Select the file.
• Set the Update Destination Path to blank since the J2EE module should appear at the root of the EAR file. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
• Click on Insert to close the insert dialog window and to add the file to the EAR.

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/cluster-sfsb/HaSfsbJsp the "cluster-sfsb" value is the context root of the web application.

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

Next, we have to add an EJB reference from the WAR file to the bean in the JAR file

• Double click on cluster-sfsb EAR in the Component View of the deployment tool.
• Right click on "Ha SFSB JSP" and choose Edit Descriptor
• Choose the References tab.
• Click Add on the "References to EJBs defined elsewhere" section. Add the following:
• Reference: HaEJB
• Linked to: Ha
• Bean Type: Session
• Bean Home Interface: samples.cluster.sfsb.HaHome
• Bean Remote Interface: samples.cluster.sfsb.HaEJB

4. Save cluster-sfsb.ear:

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

Deploy the Application

Since we are exercising a two machine, two application server instance cluster, we need to deploy the application to each instance in the cluster. Deployment Tool support one button deployment to multiple server instances.

Although you could perform the deployment steps manually by transferring the EAR file to the remote application servers and executing iasdeploy to register the EAR file, Deployment Tool provides a point and click means of deploying applications to remote iPlanet Application Servers.

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

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

1. Select the cluster-sfsb.ear file under the J2EE Application window.

2. Select File -> Deploy

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

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

5. Click on Deploy to start the deployment process to both servers concurrently.

6. Now the file transfer and application registration begins. See the Deploy tab for the status of the deployment. The deployment may take a minute or so to complete. Once the status of each deployment changes to Success, go back to step 4. and repeat the process for the second server.

Verifying Registration

1. Start the application server's Admin Tool

UNIX:

install_dir/ias/bin/ksvradmin

Windows:

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

2. 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 iAS.
3. You should see several folders for the "cluster-sfsb" J2EE application. The "cluster-sfsb" folder with the world icon represents the web application module.
4. Click on the world icon and the list of servlet for that module will appear on the right.
5. Highlight the cluster-sfsb_HaSfsb entry and click Servlet Component Properties below.
6. A dialog box with a list of server IP addresses that the servlet is registered on will appear.
7. Verify that the IP addresses listed are the IP addresses of the servers in the cluster. The port numbers represent the KXS engines which represent each application server instance.

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

Running the Application

Steps Before Running the Application

1. In the application server's Admin Tool, select one of the two application server instances and under the Load Balancing section, select Round Robin (Web Connector Driven) as the load balancing option. Click on Apply to save the change to the Registry.

2. Select View->Refresh List. This action will reload Registry settings into the Admin Tool.

3. Select the other app server instance and select the Load Balancing button to verify that the Round Robin setting matches the setting for the first server.

4. Restart the web server instances to ensure that the web server plugins reload the modified Registry settings.

Run the Application

1. Select one of the two web server hosts as a target web server and open your browser and go to the following URL:

http://yourwebserver:portnumber/NASApp/cluster-sfsb/Controller

2. Note the host name in the title of the web page.  This host name denotes the application server that processed the request as well as the names of the app servers that created and served the beans.  Since the application is not initially configured as "sticky", the host name will vary as you resubmit the page. If you have caching activated in your browser, you might need to press SHIFT when clicking on RELOAD to ensure web requests are sent to the web server.
3. Note that although the host name on which the servlet executes varies, the Session ID is the same across web requests.
4. Insert session data by adding information to the Name and Value data entry areas and selecting ADD SESSION DATA insert the information into the application's HttpSession object.  As the form is redisplayed, the current set of session data is listed. The host name will continue to change.
5. Add more session data.
6. Select the RELOAD PAGE link at the bottom of the page to redisplay the session data.
7. Select CLEAR SESSION to force the JSP to invalidate the current session.

Monitor kjs and kxs Log Output

Known Issues

1. "ClassNotFound" errors thrown when clearing session

When "CLEAR SESSION" is invoked, ClassNotFound errors are thrown in the KJS log for the classes HostInfo and Info2Bean. To work around the problem, add the paths <iplanet install>/ias6/ias/APPS/cluster-sfsb/cluster-sfsb/WEB-INF/classes and <iplanet install>/ias6/ias/APPS/cluster-sfsb/cluster-sfsbEjb to the server classpath. For instructions on modifying the server classpath, see the Getting Started documentation.

2. NullPointerException is thrown during first invocation of "CLEAR SESSION"

After the server CLASSPATH has been modified (to workaround issue (1)), the first invocation of "CLEAR SESSION" throws a NullPointerException. This is a known bug

Exercising the Server Clustering Capabilities

Three things need to be true for the state in the session bean to failover:

1. The web servlet (that represents the JSP) should be distributable. The handle to the stateful session bean is serialized and stored in the HttpSession.
2. The stateful EJB bean should be set to failover. This is done in the ias-ejb-jar.xml DD by setting the <failover-required> attribute to true
3. The EJB stubs and skeletons must be compiled in the "smart" mode. This requires the use of the "-fo" ("failover") attribute of ejbc. See the build.xml file of the cluster-sfsb sample for the use of the attribute.

Load Balancing

Sticky Versus Non-sticky

In production environments, customers typically configure applications as "sticky".  In these cases, only the first web request to an application will be load balanced by the web connector.  Subsequent requests for the same user session will be routed to the JVM (kjs) that processed the initial request for the HTTP session - unless the JVM is not available.  This configuration enhances performance by not relying on cross machine access to session data.  Under normal operating conditions, the JVM in which the session data was originally created accesses the session data throughout the user's session.

The web connector detects unavailable JVMs and will redirect the web requests to application server instances that are still available.  As long as the application is configured as "clustered" , the surviving JVMs are capable of retrieving the application session data.

Experimenting with Load Balancing, Sticky and Distributed Settings

Session Tracking and Timeout

Cookies versus URL Rewriting

Session Timeout

Scalability

Enable Multiple kjs Engines Per Application Server Instance

High Availability

1. Stop one of the iPlanet Application Server instances on one of the machines in the cluster. You can stop an instance via either the application server's Admin Console or using the following approaches:

Windows

1. Open the Windows Control Panel and double-click Services.
2. Select the iPlanet Application server and select Stop.


UNIX
 

1. As the app server user, cd to install_dir/ias/bin.
2. Execute the command ./iascontrol stop

3. Demonstrate that the downed server will rejoin the cluster by restarting the downed server.

Windows

1. Open the Windows Control Panel and double-click Services.
2. Select the iPlanet Application server and select Start.


UNIX
 

1. As the app server user, cd to install_dir/ias/bin.
2. Execute the command ./iascontrol start

5. Demonstrate that the session information is will survive JVM (kjs engine) crashes by stopping one or all of the kjs engines across both servers. Since the kxs engines manage replication of session information and hold the session data in their memory space, the session data will survive and will remain accessible as long as at least a single JVM/kjs is still alive within at least one of the app server instances. If all of the JVMs across all of the server instances are killed, then session data will be preserved and will become accessible as soon as the JVMs are automatically restarted by the application server watchdog processes. This is applicable to both HTTP session (i.e. the session maintained by the web components) as well as the stateful sessions.

6. Demonstrate network outages by pulling the network cable from one of the servers between web requests.

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 Web Application

Execute "build" under cluster/sfsb/src/

The default target core will be executed to rebuild the WAR and EAR files.

2. Redeploy Application

Execute "build deploy" under cluster/sfsb/src/

3. Restart Application Server

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

To clean the web application project area, execute "build clean".

Modifying Domain via Registry Editor

1. Start the iPlanet Registry Editor using the kregedit command.
2. Navigate to the SOFTWARE\iPlanet\Application Server\6.0\J2EE-Module\cluster-sfsb\ folder.
3. Double click on session-domain and modify the domain name based on your network environment.
4. Restart the application server to pick up the change.

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