S-PLUS Server 7.0 for Unix Servlet Example: gtDemo

This readme file describes how to run gtDemo, which uses
S-PLUS Server for Unix to generate Graphlets on 
demand and distribute them over the Web.  For more information
on using Servlets with S+Server, see the Example Web Applications 
chapter in the S-PLUS Server User's Guide.

The gtDemo program uses a servlet -- a bit of Java code running
in a Web server -- as a client program to the S-PLUS 
Server.  The servlet is designed to run in any Web server that
supports Version 2.3 of the Java Servlet Specification from Sun
Microsystems.  One such server is Tomcat (4.x or 5.0), 
which is available for free from Apache's Jakarta 
project (http://jakarta.apache.org/).  Tomcat can run as a 
standalone Web server or as a servlet container in a 
full-featured Web server (such as Apache).  These
directions explain how to set up gtDemo with Tomcat running in
standalone mode.  

For a list of other web servers that support servlets, see:

http://java.sun.com/products/servlet/industry.html 

Using gtDemo with these other web servers will likely require
a similar setup procedure.

The setup for gtDemo consists of two parts:

1) Configuring S-PLUS Server.

2) Configuring the Web server 

The Web server and the S-PLUS Server can be on the same 
computer or on different computers on a network.  S-PLUS 
Server will run on a Linux or Solaris or AIX system.  Tomcat 
can run under any operating system that supports Java, including
Windows, Unix, and Macintosh.  (If you use a different Web 
server, check with the manufacturer to see what operating 
systems it will run under.)

The gtDemo servlet can use S-PLUS Server to manage more than 
one S-PLUS session.  If gtDemo is running multiple sessions and 
several people hit the Web site at once, gtDemo will run their 
requests simultaneously on different copies of S-PLUS.  For this
example, multiple S-PLUS sessions on the same computer can share
a working directory, as the S-PLUS functions involved do not 
save any information.


Configuring S-PLUS Server
----------------------------------

After installing S-PLUS Server:

1. Copy the gtDemo directory and its contents to the computer 
   running S-PLUS Server, and change to this directory.

2. Create an S-PLUS Chapter in the gtDemo directory and
   read in the functions and data by typing the commands
	SplusAS CHAPTER
	SplusAS make install.funs

3. Start the S-PLUS Server factory:
	SplusAS SERVER -factory [options]

Note:  If you want gtDemo to use more than server to run its
S-PLUS sessions, repeat the above instructions for each server
on which you'll be running these sessions.  On each server, if 
you want gtDemo to run multiple S-PLUS sessions with their own 
working directories, repeat Steps 1 and 2 above for each 
directory.


Configuring the Web server
--------------------------

1. On your Web server machine, install a Java Runtime 
   Environment conformant to JRE 1.2 or later, if one is not 
   installed there already.  Java Runtime Environments for
   Solaris, Linux and Windows operating systems are available
   from http://java.sun.com.

2. Download Tomcat from http://jakarta.apache.org/ and install
   it according to the instructions that come with it.

   In the instructions that follow, TOMCAT_HOME refers to the
   top-level Tomcat directory.

3. Copy the file gtDemo.war to TOMCAT_HOME/webapps.

4. Launch Tomcat.  For Windows or Unix, the appropriate batch
   file or script is in TOMCAT_HOME/bin.  Tomcat will
   automatically unpack the file gtDemo.war and set up the Web
   site.

5. Edit the file TOMCAT_HOME/webapps/gtDemo/connections.xml to
   describe the S-PLUS session(s) you want to run.  The XML code
   for one session will look something like this:

	<connection name="Friendly Name">
		<host>computer</host>
		<username>account</username>
		<password>yourpassword</password>
		<cwd>path/gtDemo</cwd>
	</connection>

   Here Friendly Name is any name you want to use for the
   session, computer is the name or IP address of the computer
   running S-PLUS Server, account is the name of your account
   on the host computer, yourpassword is your password, and
   path/gtDemo is the path on the host computer to the directory
   you created in step 1 under "Configuring S-PLUS
   Server".  If you want gtDemo to run multiple S-PLUS sessions, 
   include a section of XML code like that above for each such 
   session.  The multiple sessions can be on the same computer
   or on different computers; sessions on the same computer can
   share a working directory or have their own working
   directories.


Viewing the demo
----------------

To see the demo, point your browser to 

	http://<host>:8080/gtDemo/

where <host> is the name of the computer running the Web server. 
The "8080" in this URL is the port that Tomcat uses by default 
when it runs in standalone mode.  If you reconfigure Tomcat or 
use another Web server, adjust the URL appropriately.
