Deploying Websydian Web Server Component on Tomcat for Windows

Introduction

This document describes how to deploy and troubleshoot the Websydian Web Server Component on Tomcat for Windows.

This document does not describe the steps to be performed in order to install and setup the Tomcat servlet engine, please consult the documentation for Tomcat.

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

Prerequisites

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

Tomcat for Windows installed

• Make sure that the Tomcat for Windows has been installed and is started.

Package the Websydian Web Server Component

Follow the guide on how to package the servlet based Websydian Web Server Component. This will provide you with the WAR file used for deploying the Websydian Web Server Component.

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.

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

Deploy the Web Server Component WAR file

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 Tomcat Servlet engine has been started and is responding.

Open the internet browser and enter the URL for the Tomcat Servlet engine.

E.g. http://localhost:8080

If the response is a page from the Tomcat Servlet engine stating that Tomcat has been configured successfully you are ready to proceed, otherwise make sure the Tomcat Servlet engine is started.

Press the menu item "Tomcat Manager" and enter the correct administration user and password.

The page returned looks something like this:

In the field "Select WAR file to upload" insert the WAR file to be deployed. The name of the WAR file will become the context path (first left part of the URL).

The Web Server Component is now ready to service requests.

Verify that the Web Server Component is working

The Web Server Component is now ready to receive the first request. As the Web Server Component 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 Web Server Component is functioning correctly perform the following step:

• Open the internet browser and enter the URL referring to the Web Server Component servlet

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

  At this point you should receive an error message 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 Web Server Component

Troubleshooting the Web Server Component

Deployment of the WAR file

• If the Web Server Component WAR file is not accepted by the Tomcat 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 Tomcat Administration Console is unable to start the Web Server Component 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 Tomcat Servlet engine look into the directory logs located in the installation directory of the Tomcat Servlet engine.

Error messages of the Web Server Component

Troubleshooting the Websydian Web Server Component is primarily based on the log file of the Websydian Web Server Component, 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 Websydian Web Server Component property file is not correct.

1. Verify that the Websydian Server is running.
2. Open the Websydian Web Server Component 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 Websydian Web Server Component 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 Websydian Web Server Component 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 Websydian Web Server Component 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 Websydian Web Server Component 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 Websydian Web Server Component 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 Websydian Web Server Component 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 Websydian Web Server Component

The following list describes a number of issues that can help to provide better performance of the Websydian Web Server Component.

• In a production environment always make sure that the log level of the Websydian Web Server Component is set to ERROR. Check the log.level parameter of the Websydian Web Server Component property file to set the correct log level.
• Running the Pro or Enterprise Websydian Server a buffering mechanism is available specified in the Websydian Web Server Component 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.