Deploying Relay Service on WebSphere Application Server 5.0 (WAS 5.0)

Version 1.0, November 2003

• Introduction

• Prerequisites

• Introduction to deployment of servlets

• Configure and Package the Relay Service WAR file

• Deploy the Relay Service WAR file to the WAS 5.0

• Verify that the Relay Service is working

• Troubleshooting the Relay Service

• Tuning the Relay Service
   

Introduction

This document describes how to deploy and troubleshoot the Websydian Relay Service on the IBM WebSphere Application Server 5.0 (WAS 5.0).

WebSphere is available for several different platforms and this document have been tested with iSeries as well as the Windows platform. The interface for Linux is the same so this document could also be used to deploy to WebSphere on Linux.

WAS 5.0 comes in an Express and an Advanced edition, and both versions are covered by this document.

This document does not describe the steps to be performed in order to install and setup the WebSphere Application Service. WebSphere Application Server is a product supplied and supported by IBM.

Please note that this document is subject to change.

The Relay Service is the component of the Distributed Websydian Architecture that forwards the requests to the Application Services. For further general information on the Relay Service read this document.

Prerequisites

Before completing this deployment guide a number of issues have to be addressed.

WebSphere Application Server 5.0 installed

• Make sure that WebSphere Application Server 5.0 has been installed and all available PTFs and fix packs have been installed and that the supplied snoop application is working.
• Make sure that the WebSphere Application Server 5.0 Web Administrative Console is installed and functioning.
• Obtain information about the correct URL and port of the WebSphere Web Administration Console. The web administration interface is used to perform the deployment.
• Make sure to obtain information about the HTTP server servicing requests being parsed to the WebSphere if any.

Use this matrix to insert the information required.

WebSphere Hostname or IP address
WebSphere Administrative Console TCP port
WebSphere Application Server TCP port
HTTP Server Hostname or IP address
HTTP Server TCP port

Download latest version of the DWA Deployment Tools

Make sure that the latest version of the DWA Deployment Tool has been downloaded and installed.

Websydian Server deployed and running

Make sure that the Websydian Server has been deployed and is running.

For further information on deployment of the Websydian Server go to the main page of the DWA Deployment Guides.

Distributed Websydian Architecture Configuration Sheet

Make sure to print and fill out the DWA Configuration Sheet before proceeding. The DWA Configuration Sheet is a way to get an overview of all components required in the Distributed Websydian Architecture (DWA) prior to the deployment.

The bullet numbers, e.g. , found in this document refers to the DWA Configuration Sheet.

Introduction to deployment of servlets

When deploying a servlet all information pertaining the particular servlet is required to be packed into a Web Archive (WAR file). The WAR file is a packed file much like the ZIP file with a predefined structure that holds information about the servlet. The information range from information about the servlet name, parameters of the servlet,  URL to be used to the actual jar files containing the code of the servlet.

If you would like to see the contents of a WAR file rename it to a ZIP file and unpack it.

There are a large number of information pertaining the deployment of servlets on the J2EE environment and servlet engines. Often the J2EE server is supplied with a deployment tool for packaging the WAR files. Websydian is providing a small tool to package the Relay Service with the correct information.

This deployment guide uses a WAR file to deploy the Websydian Relay Service.

Configure and Package the Relay Service WAR file

The Distributed Websydian Architecture deployment tools will be used in this document to pack the WAR file and create the Relay Service property file. To deploy the Websydian Relay Service perform these steps.

1. Run the script program DeployRelayService.cmd located in the subdirectory Websydian_4.0x of the deployment tools directory.
    
2. Fill in the required information:
    

   

   Directory to receive output

   The directory to receive the generated deployment files (WAR file and structure of this).

   Websydian Java runtime location

   The directory where the Websydian DWA deployment files are located (wsyddwa*.jar, activation*.jar, log4j*.jar, mail*.jar)

   Include files/subdirectories from this directory (optional)

   If specified all files and subdirectories of this directory are copied to the WAR file's root directory. Especially useful if including images or static html pages with the relay service used by the Websydian application.

   Servlet Name

   Name to identify the servlet when deployed in the servlet engine.

   Servlet Display Name

   Short description of the servlet

   URL (Last part)

   The last part of the URL to be used.

   E.g. http://www.myserver.com/websydian/webshop the last part would be /webshop.

   The /websydian is called context when deploying the servlet with the servlet engine.

   Property file location to be used on the Web Server (Use '/')

   The final location of the relay service property file to be used on the web server. This information together with the Servlet Name will become the final location and name of the relay service property file.

   Note! Use slash ('/') as delimiters to directories.

    

3. Press the Next button to show the parameters of the Relay Service property file and fill in the required parameters:
   
    
4. Press the pack button

   

   The packaging of the WAR file is performed and the property file to be used is created in the output directory specified. The location of the WAR file is specified along with the property file to be used.

Deploy the Relay Service WAR file to the WAS 5.0

The following section describes the steps to be performed in order to deploy the WAR file created in the previous section.

Before continuing make sure that the supplied demo servlet called snoop is running, this is a way of verifying that the WebSphere has been setup correctly and is running.

Open your internet browser and enter the following information http://yourwebsphere:port/snoop replacing yourwebsphere with the correct host name and the port with the correct port number of your WebSphere installation, this can be obtained from the person who installed your WebSphere Application Server..

After verifying the snoop servlet is running start the web administration interface of the WebSphere.

Open your internet browser and enter the following URL http://yourwebsphere:adminport/admin, replacing the yourwebsphere with the correct hostname and the adminport with the administration port specified by the person who setup the WebSphere.

Enter your user id, this information is only to identify yourself to the WebSphere administration console. Press the ok button.

In the left hand menu expand the menu item "Applications" and click the "Install New Application"

In the "Local path" input field enter the full path and name of the WAR file to be deployed.

In the "Context Root" input field specify the first part of the URL to be used. In the following example the context root is /websydian which will result in the Relay Service being deployed will have /websydian as the first part of the URL.

Press the "Next" button to advance to the next display and keep pressing the "Next" button until a "Finish" button is available.

If the WAR file is not accepted please proceed to the section Troubleshooting the Relay Service.

Press the "Finish" button.

Press the link "Save to Master Configuration"

Press the "Save" button to update the Master Configuration.

Expand the left hand menu item "Environment" and press the link "Update Web Server Plugin".

Press the OK button to update the "Web Server Plugin". The web server plugin is used by the http server to forward the URLs maintained by the WebSphere Application Server.

On the left hand menu select the link "Enterprise Applications" scoped under the Applications menu.

Mark the servlet war file that has just been deployed and press the "Start" button.

The RelayService is now ready to process requests. The RelayService is not initiated at this stage but will be when the first request is received.

Verify that the Relay Service is working

The Relay Service is now ready to receive the first request. As the Relay Service receives the first request it will initiate and perform the following tasks:

1. Read the property file specified
2. Contact the Websydian Server information about available tokens and other license related parameters.
3. Initialize the log file
4. Start the command interface

In order to verify that the Relay Service is functioning correctly perform the following step:

• Open the internet browser and enter the URL referring to the Relay Service servlet

  e.g. http://myhostname:myport/websydian/test

  At this point you should receive an error message, in the log file and in the browser stating

  Error message: [PkaError(Unclassified)]:Service name 'xxxxxxxxx' not known by Websydian Server.

  or if you have started the Application Services you should see the first page of the application.

  If this is not the case please proceed to the section Troubleshooting the Relay Service

Troubleshooting the Relay Service

Deployment of the WAR file

• If the Relay Service WAR file is not accepted by the WebSphere Administration Console and you have created the WAR file using the DWA Deployment Tools, please forward the WAR file to Websydian Support for further investigation. Often problems are related to the web.xml file located in the subdirectory web-inf. The web.xml file holds the configuration parameters of the servlets being deployed.
• If the WebSphere Administration Console is unable to start the Relay Service try unpacking the WAR file and verify that the jar files wsyddwaxx.jar, activationxxxxx.jar, mailxxxx.jar, and log4jxxxx.jar is located in the subdirectory lib under the directory web-inf if not try repacking the servlet.
• For general troubleshooting of the WebSphere environment look into the directory logs located in the installation directory of the WebSphere Application Server or contact your WebSphere consultant.

Error messages of the Relay Service

Troubleshooting the Relay Service is primarily based on the log file of the Relay Service, a number of errors are also displayed in the browser window upon the first request.

The following is a list of most common errors:

Error message: [IO error]:Party: Error creating socket (java.net.ConnectException: Connection refused: connect)

The Websydian Server is not running or the parameters of the Relay Service property file is not correct.

1. Verify that the Websydian Server is running.
2. Open the Relay Service property file and identify and verify the parameters of websydianserver.ipaddr and websydianserver.tcpport. If localhost is specified for websydianserver.ipaddr change this to the correct IP address or computer name of the computer running the Websydian Server.

Error message: [Internal error]:PkaLog: File log could not be initialized - xxxxxxxxxxxxxxxxxx (The system cannot find the path specified)

Open the Relay Service property file and identify the parameters of the setting servlet.log.file and verify that the parameter is correct. Also make sure that the user running the Relay Service has the required authorization to create and update files in the specified directory.

Error message: [PkaError(Unclassified)]:Service name 'xxxxxxxxx' not known by Websydian Server

The Relay Service has requested for information about an Application Service with a service name that does not exist in the Websydian Server.

Make sure that the Application Service is started, and that the service name stated in the Relay Service property file and when starting the Application Service is similar, note that the service name is case sensitive.

Unable to get token

The message unable to get token can occur for a number of reasons:

• The application uses frames and each frame has to be processed at the same time. E.g. if the page being loaded consist of 2 frames it is recommended to start at least 3 Application Services to process the requests. One for the frameset page and two for each of the frames.
• The number of concurrent requests have increased on the site requiring further Application Services to be started. The number of Application Services can be used to indicate the number of concurrent requests, this is a rough estimate.
• An error in the application is causing the Application Services to end abnormally. Verify that the number of Application Services does not decrease over time. Using iSeries consider implementing Websydian Agent (formally known as Application Service Controller) to monitor for failing Application Services. For Windows and Java check the deployment guide on these environments.

Error message: [IO error]:ServerFactory(): Error creating stream (java.net.BindException: Cannot assign requested address: JVM_Bind).

This indicates that the parameter servlet.commandipaddr located in the Relay Service property file is pointing to an IP address not located on the computer running the servlet engine. Make sure that the correct IP address or hostname is specified for this parameter.

Error message: [IO error]:ServerFactory(): Error creating stream (java.net.BindException: Address already in use: JVM_Bind)

This indicates that the parameter servlet.commandtcpport located in the Relay Service property file is pointing to a TCP port that is already in use. Change the parameter to a port that is not in use.

Tuning the Relay Service

The following list describes a number of issues that can help to provide better performance of the Relay Service.

• In a production environment always make sure that the log level of the Relay Service is set to ERROR. Check the log.level parameter of the Relay Service property file to set the correct log level.
• Running the Pro or Enterprise Websydian Server a buffering mechanism is available specified in the Relay Service property file by the parameter servlet.service.databuffersize. The default setting is 4096 (4kb) which often is the best setting. Verify the setting of this parameter to check if it is set to a value higher than 0 (zero), zero indicates no buffering.