SAWeb Software Administrators's Guide

Ulysses/SWICS Archive Web Software (SAWeb) Requirements

The instructions within this Administrators's Guide are intended to help a Web administrator to install and configure the SAWeb application. Normal Ulysses/SWICS Archive users do not need to use this guide!
The SAWeb archive software allows for the online SWICS data query and calibration. As such, the software needs to run on a Internet/Intranet accessible server. The following requirements must be meet to install the SAWeb archive software:

  • You need to have a Java Runtime Environment (JRE or J2SE JDK) installed on your server. The JRE 1.5 for Windows and Unix can be found on the archive DVD-ROM in the 'install' directory.

  • As the SWICS Archive Web Application is implemented with Java Servlet Technology, it requires to have a Servlet container running, such as the Tomcat Open Source Project Software or any other application server capable to host Servlets.
    For instructions to install the Tomcat Servlet Engine please consult the information contained in the Tomcat distribution. For convenience the compressed Tomcat distribution is also included on the Ulysses/SWICS Archive DVD-ROM in the 'install/tomcat55.zip' file.

  • Tomcat can run as simple standalone web server or in collaboration with the Apache web server. The SWICS Archive Web Software (SAWeb) runs in both configurations.

  • The hardware and OS supported by the SWICS Archive software can be one of the following:
    - Intel PC running Windows NT/2000/XP
    - Intel PC running Linux
    - Alpha machine running DEC/Compaq UNIX
    - Sun Sparc running Solaris

SAWeb Application Versions

For Internet/Intranet online queries of the data archive the SAWeb application needs to be installed on the server where Tomcat or any other servlet engine is running. Although it is recommended to use the latest version of the SAWeb application (i.e. saweb5x.zip) older version of SAWeb are also included in case you are required to operate an old version of Tomcat or JRE. The following table provides an overview of the different software versions and their interdependency:

 

SAWeb Version Tomcat Servlet/JSP Java JRE/JDK and J2EE
saweb3x.zip Ver. 3.3.2 Spec. 2.2/1.1 JRE 1.3.1 / J2EE 1.2.1 (May 2000)
saweb4x.zip Ver. 4.1.27 Spec. 2.3/1.2 JRE 1.4.2 / J2EE 1.3.1 (Jan. 2002)
saweb5x.zip Ver. 5.5.17 + CP(*) Spec. 2.4/2.0 JRE 1.4.2 / J2EE 1.4.0 (Nov 2003)
saweb5x.zip Ver. 5.5.17 Spec. 2.5/2.0 JRE 1.5.0 / Java EE 5.0 (May 2006)
(*) Tomcat 5.5 can be used with the JRE / J2EE 1.4 but requires to additionally install the Tomcat 5.5 JDK 1.4 Compatibility Package, which is included in the DVD-ROM file 'install/tomcatCP.zip'.

SAWeb Application Server Installation

To run the SAWeb application on a Tomcat server you need to decide which software version to install. Version 'saweb5x.zip' is recommended and offers the most features, but depending on your software environment an older version my be chosen (see SAWeb Application Versions). The following steps are necessary to install the SAWeb software on a Tomcat server:

  • Step 1: Make a new 'saweb' web application sub-directory in the '[tomcat home]/webapps/' path.

  • Step 2: Copy and unzip the '/download/sa22.zip' file of the DVD-ROM into the 'saweb' directory.

  • Step 3: Move the 'webapps/saweb/sa22.zip' file to the 'webapps/saweb/download' directory.

  • Step 4: Copy the 'webapps/saweb/saweb/saweb5x.zip' file into the 'webapps/saweb' directory.

  • Step 5: Unzip the 'saweb5x.zip' file, which creates an a 'WEB-INF' directory.

  • Step 6: Make sure the newly created directory 'webapps/saweb/WEB-INF' is uppercase.

  • Step 7: The SAWeb class file should now be found in 'WEB-INF/classes/QueryServlet.class'.

  • Step 8: The 'webapps/saweb/saweb5x.zip' file can now be deleted.

The procedure for an SAWeb update is very much the same as in the installation description above. Just make sure you make a backup copy of your 'WEB-INF/web.xml' file as it will be overwritten by the unzip operation of the 'saweb5x.zip' file. The 'WEB-INF/web.xml' file may serve as a reference when you re-configure the SAWeb application for your specific environment (see next section).
If you are running the Tomcat server with an Apache Web-Server, the following additional installation steps are necessary for Apache Web-Server integration:

  • Step 9: Copy the '[tomcat home]/webapps/saweb/WEB-INF/lib/*.jar' files into '[tomcat home]/lib'.

  • Step 10: Add the following context entry into the '[tomcat home]/conf/server.xml' file:
                  <Context path="/saweb" docBase="webapps/saweb" debug="0" reloadable="true"></Context>

For detailed instructions how to run specific Tomcat versions with the Apache Web-Server please consult the documentation contained in the Tomcat and Apache distribution.

SAWeb Application Configuration

To configure the SAWeb application you can edit the parameters in the '[tomcat home]/webapps/saweb/WEB-INF/web.xml' configuration file. Most parameters usually need not be changed except the 'MailServer' and 'MailFrom' parameters which must be configured according to your mail server setup in order to support the email notification output option.

 

Parameter Description
BaseDir Base directory where the Ulysses/SWICS Archive files can be found. This is the absolute file system directory path where the archive initial 'index.htm' file is found. The servlet normally should be able to determine the path automatically (Default).
BaseURL Base URL where the Ulysses/SWICS Archive files can be found. This URL consists of 'protocol', 'server name', 'server port' and 'context path', where the archive initial 'index.htm' file is found. The servlet normally should be able to determine the path automatically (Default).
MailServerName Address of SMTP mail server through which the servlet application can send email notifications. This value needs to be entered to support the output option 'email notification' for data download. If no mail server name is configured and the email notification output option is selected, an ASCII output table is displayed instead. (Default)
MailServerPort Port of SMTP mail server through which the servlet application can send email notifications. (Default: 25)
MailServerSSL For an SMTP mail server requiring SSL/TLS connection encryption, this parameter must be set to "true". (Default: false)
MailServerAuth For an SMTP mail server requiring login authentication, this parameter must be set to "true". This additionally requires the specification of the mail account user and password (see below). (Default: false)
MailAccountUser For an SMTP mail server requiring login authentication, this parameter allows you to specify the mail account login user name. (Default: none)
MailAccountPwd For an SMTP mail server requiring login authentication, this parameter allows you to specify the mail account login password. (Default: none)
MailFrom Enter a valid 'from' email address field used for the SWICS Archive sent email notification. Depending on your mail server configuration, this email needs to be identical with the mail account user email address. If the value is empty, the application default is used. (Default: saweb@{MailServer})
MailURL Base URL path of download server and directory for data file download through email notification. The URL address must include the access protocol (i.e. http: or ftp:). If value is empty, the servlet uses the HTTP protocol for download from the BaseURL specification server (Default).
MailKeep The time (in days) the data file will be available for download through email notification. (Default: 2 days)

Running the SAWeb Application

Once the SAWeb Application is properly installed and configured for the Tomcat server, it can be run with any Web browser by entering the following URL:
http://[tomcat server name:port]/saweb/index.htm


(Do not use 'localhost' in the Tomcat server URL, as this will direct you to the SASWS archive query form, which does not support the email notification option.)