ACE/apps/JAWS/server/README

   1 # -*- text -*-
   2 # Hey, Emacs!  This is a TEXT file.
   3
   4 --------------------------
   5 README for the JAWS server
   6 --------------------------
   7
   8 This is the README file for the JAWS server.
   9
  10 CONTENTS
  11
  12 1. Compiling
  13   a. UNIX
  14   b. Windows NT 4.0
  15
  16 2. Executing
  17   a. svc.conf parameters
  18   b. General Info
  19
  20 3. Limitations
  21
  22 4. Acknowledgements
  23
  24 5. New additions
  25
  26 ------------
  27 1. Compiling
  28 ------------
  29
  30 1a. Compiling under UNIX.
  31
  32         Assuming that the environment variable ACE_ROOT is set
  33 correctly, and that you are using GNU make, compiling should simply
  34 involve:
  35
  36         $ cd $ACE_ROOT/apps/JAWS/server
  37         $ make clean
  38         $ make depend
  39         $ make
  40
  41 This will produce an executable named ``main''.
  42
  43 1b. Compiling under Windows NT 4.0.
  44
  45         Assuming you are using a recent version of Microsoft
  46 Visual C++, you can use the jaws.mdp file located in
  47 $ACE_ROOT/apps/JAWS/server to build JAWS.
  48
  49
  50 ------------
  51 2. Executing
  52 ------------
  53
  54 2a. svc.conf parameters.
  55
  56         To run JAWS, simply execute "main".  It loads the HTTP server
  57 from the file named in the ``svc.conf'' file.  The ``svc.conf'' file
  58 itself contains documentation about the load line.  It supports the
  59 following command-line arguments:
  60
  61         -p port         Start JAWS on the specified port.
  62         -n num_threads  Use num_threads as the maximum number of threads.
  63         -f thr_flag     Can be used multiple times to set thread
  64                         creation flags:
  65                         THR_BOUND       -> bound threads
  66                         THR_DAEMON      -> daemonized threads
  67                         THR_DETACHED    -> detached threads
  68                         THR_NEW_LWP     -> increase concurrency level
  69         -t thr_strategy Use one of the following strategies:
  70                         POOL        -> thread pool
  71                         PER_REQUEST -> thread-per-request
  72                         THROTTLE    -> thread-per-request with throttling
  73         -i io_strategy  Use one of the following strategies:
  74                         SYNCH   -> synchronous I/O
  75                         ASYNCH  -> asynchronous I/O
  76         -b backlog      Backlog value for listen ().
  77
  78 2b. General Information
  79
  80         By default, JAWS will used port 5432 with 5 threads and apply
  81 the synchronous thread pool strategy.  Unless set, the default backlog
  82 value is equal the value of the maximum number of threads.
  83
  84         JAWS also responds to several environment variables.  This is
  85 a temporary feature which will be replaced by a more general
  86 configuration file similar to NCSA httpd's.  The environment variables
  87 are:
  88         JAWS_DOCUMENT_ROOT
  89           This is the starting point the server will use to look
  90           for files.
  91           Default value: the current directory of the server.
  92
  93         JAWS_CGI_PATH
  94           This is intended to be a ``:'' delimited list of paths
  95           (similar to your regular PATH environment variable) which
  96           describes the possible locations for CGI binaries.
  97           Default value: Any directory named ``cgi-bin''.
  98
  99         JAWS_USER_DIR
 100           This is the name of the subdirectory in a users home
 101           directory which contains publicly available WWW documents.
 102           Default value: ``.www''.
 103
 104         JAWS_DIR_INDEX
 105           The name of the file which is sent, if present, when the URL
 106           leads to a directory.
 107           Default value: ``index.html''.
 108
 109         You may test the server by executing telnet, opening a
 110 connection to the server machine on the server port.  For instance:
 111
 112         $ telnet machinename 5432
 113         Trying ###.###.###.###...
 114         Connected to machinename.your.domain
 115         Escape character is '^]'.
 116         GET /main.cpp
 117         // main.cpp
 118         //...
 119
 120         Note that if you use an HTTP/1.0 get request, then you have
 121 to hit return twice before the file will be sent.  E.g.,
 122
 123         $ telnet machinename 5432
 124         Trying ###.###.###.###...
 125         Connected to machinename.your.domain
 126         Escape character is '^]'.
 127         GET /main.cpp HTTP/1.0
 128
 129         // main.cpp
 130         //...
 131
 132         Where applicable, JAWS will perform ``~'' expansion for home
 133 directories of usernames.
 134
 135
 136 -----------
 137 3. Features
 138 -----------
 139
 140 (a) JAWS supports full HTTP/1.0 responses.
 141
 142 (b) JAWS support CGI scripts on UNIX.
 143
 144 (c) JAWS parses request headers.  The mechanism can be used to parse
 145     headers from a variety of text based protocols (e.g., SNMP and
 146     NNTP).
 147
 148 (d) Optimized filecaching.
 149
 150 --------------
 151 4. Limitations
 152 --------------
 153
 154 The following are TODO items for JAWS:
 155
 156 status|task
 157 ------+-----------------------
 158       | (a) JAWS will support HTTP/1.1 eventually, including
 159       |     persistent connections.
 160       |
 161       | (b) JAWS can be more aggressive with its threading strategies,
 162       |     such as:
 163       |     (*) parallelize HTTP protocol processing, similar to
 164       |         PHTTPD.
 165       |     (*) prioritize threads to give more important requests
 166       |         more execution time.
 167       |     (*) apply throttling, similar to THTTPD.
 168       |
 169       | (c) JAWS will support a general protocol content filtering
 170       |     mechanism which will be used to replace the existing CGI
 171       |     support implementation.
 172       |
 173
 174 Questions, comments, corrections, suggestions are welcome.  Please
 175 feel free to send me any such correspondence.
 176
 177 James Hu <jxh@cs.wustl.edu>
 178
 179 -------------------
 180 4. Acknowledgements
 181 -------------------
 182
 183         My partners in crime for this endeavor include:
 184
 185         Eastman-Kodak, Rochester N.Y.
 186     and Object Technologies, Inc.       For providing funding for this
 187                                         research.
 188
 189         Dr. Douglas Schmidt             For being my advisor, and
 190                                         convincing my sponsors to fund
 191                                         me.
 192
 193         Irfan Pyarali                   For porting JAWS to NT, and
 194                                         for designing and implementing
 195                                         the JAWS IO mechanism.
 196
 197         Sumedh Mungee                   For writing the benchmark
 198                                         client, and performing the
 199                                         UNIX benchmarks.
 200
 201         Tim Harrison                    For his comments, advice, and
 202                                         help in designing the IO
 203                                         mechanism used by JAWS.
 204
 205 -----------------------
 206 5. Additions
 207 -----------------------
 208
 209 The need arose to have JAWS not perform any file caching. We added this
 210 functionality and provided a new cmd line option -c with params NO_CACHE/CACHE.
 211
 212 This capability is to be used with the RepositoryManager in CIAO.
 213
 214 In its current design the RepositoryManager (RM) need a collocated HTTP server.
 215 When RM istalls packages, it unpacks them so that the separate files are accessible to
 216 ZIP unaware entities like JAWS. JAWS is used to serve the libraries in the package to the
 217 various deamons that might be interested in them, e.g. the NodeApplicationManager.
 218
 219 The problem with using file caching reveals itself during the deletePackage operation of
 220 the RM. When the RM attempts to delete a file which was previously accessed via JAWS a
 221 is currently in the file cache the call fails and the file remains on the filesystem
 222 indefinitely. If the file is cached with a ACE_NOMAP option is is not stored in a file
 223 map and it is deleted upon server termination. The OS handles that. Althoguh this might
 224 or might not be OK (depending on how it scales) there is an additional problem because
 225 JAWS and the ACE_Filecache_Handle class used do not provide enough functionality to deal
 226 with the ACE_NOMAP case. I believe that ACE_NOMAP option was probably never used.
 227
 228 To overcome the above problems we added the no caching functionality in JAWS.