# -*- text -*-
# Hey, Emacs!  This is a TEXT file.

--------------------------
README for the JAWS server
--------------------------

This is the README file for the JAWS server. 

CONTENTS

1. Compiling
  a. UNIX
  b. Windows NT 4.0

2. Executing
  a. svc.conf parameters
  b. General Info

3. Limitations

4. Acknowledgements

------------
1. Compiling
------------

1a. Compiling under UNIX.

	Assuming that the environment variable ACE_ROOT is set
correctly, and that you are using GNU make, compiling should simply
involve:

	$ cd $ACE_ROOT/apps/JAWS/server
	$ make clean
	$ make depend
	$ make

This will produce an executable named ``main''.

1b. Compiling under Windows NT 4.0.

	Assuming you are using a recent version of Microsoft
Visual C++, you can use the jaws.mdp file located in
$ACE_ROOT/apps/JAWS/server to build JAWS.


------------
2. Executing
------------

2a. svc.conf parameters.

	To run JAWS, simply execute "main".  It loads the HTTP server
from the file named in the ``svc.conf'' file.  The ``svc.conf'' file
itself contains documentation about the load line.  It supports the
following command-line arguments:

        -p port         Start JAWS on the specified port.
        -n num_threads  Use num_threads as the maximum number of threads.
        -f thr_flag     Can be used multiple times to set thread
                        creation flags:
                        THR_BOUND       -> bound threads
                        THR_DAEMON      -> daemonized threads
                        THR_DETACHED    -> detached threads
                        THR_NEW_LWP     -> increase concurrency level
        -t thr_strategy Use one of the following strategies:
                        POOL        -> thread pool
                        PER_REQUEST -> thread-per-request
                        THROTTLE    -> thread-per-request with throttling
        -i io_strategy  Use one of the following strategies:
                        SYNCH   -> synchronous I/O
                        ASYNCH  -> asynchronous I/O
        -b backlog      Backlog value for listen ().

2b. General Information

	By default, JAWS will used port 5432 with 5 threads and apply
the synchronous thread pool strategy.  Unless set, the default backlog
value is equal the value of the maximum number of threads.

	JAWS also responds to several environment variables.  This is
a temporary feature which will be replaced by a more general
configuration file similar to NCSA httpd's.  The environment variables
are:
	JAWS_DOCUMENT_ROOT
	  This is the starting point the server will use to look
	  for files.
	  Default value: the current directory of the server.

	JAWS_CGI_PATH
	  This is intended to be a ``:'' delimited list of paths
	  (similar to your regular PATH environment variable) which
	  describes the possible locations for CGI binaries.
	  Default value: Any directory named ``cgi-bin''.

	JAWS_USER_DIR
	  This is the name of the subdirectory in a users home
	  directory which contains publicly available WWW documents.
	  Default value: ``.www''.

	JAWS_DIR_INDEX
	  The name of the file which is sent, if present, when the URL
	  leads to a directory.
	  Default value: ``index.html''.

	You may test the server by executing telnet, opening a
connection to the server machine on the server port.  For instance:

	$ telnet machinename 5432
	Trying ###.###.###.###...
	Connected to machinename.your.domain
	Escape character is '^]'.
	GET /main.cpp
	// main.cpp
	//...

	Note that if you use an HTTP/1.0 get request, then you have
to hit return twice before the file will be sent.  E.g.,

	$ telnet machinename 5432
	Trying ###.###.###.###...
	Connected to machinename.your.domain
	Escape character is '^]'.
	GET /main.cpp HTTP/1.0

	// main.cpp
	//...

	Where applicable, JAWS will perform ``~'' expansion for home
directories of usernames.


-----------
3. Features
-----------

(a) JAWS supports full HTTP/1.0 responses.

(b) JAWS support CGI scripts on UNIX.

(c) JAWS parses request headers.  The mechanism can be used to parse
    headers from a variety of text based protocols (e.g., SNMP and
    NNTP).

(d) Optimized filecaching.

--------------
4. Limitations
--------------

The following are TODO items for JAWS:

status|task
------+-----------------------
      |	(a) JAWS will support HTTP/1.1 eventually, including
      |	    persistent connections.
      |
      |	(b) JAWS can be more aggressive with its threading strategies,
      |	    such as:
      |	    (*) parallelize HTTP protocol processing, similar to
      |	        PHTTPD.
      |	    (*) prioritize threads to give more important requests
      |	        more execution time.
      |	    (*) apply throttling, similar to THTTPD.
      |
      | (c) JAWS will support a general protocol content filtering
      |     mechanism which will be used to replace the existing CGI
      |     support implementation. 
      |

Questions, comments, corrections, suggestions are welcome.  Please
feel free to send me any such correspondence.

James Hu <jxh@cs.wustl.edu>

-------------------
4. Acknowledgements
-------------------

	My partners in crime for this endeavor include:

	Eastman-Kodak, Rochester N.Y.
    and Object Technologies, Inc.	For providing funding for this
					research.

	Dr. Douglas Schmidt		For being my advisor, and
					convincing my sponsors to fund
					me.

	Irfan Pyarali			For porting JAWS to NT, and
					for designing and implementing
					the JAWS IO mechanism.

	Sumedh Mungee			For writing the benchmark
					client, and performing the
					UNIX benchmarks.

	Tim Harrison			For his comments, advice, and
					help in designing the IO
					mechanism used by JAWS.