Revert "Use a variable on the stack to not have a temporary in the call"
[ACE_TAO.git] / ACE / apps / JAWS / server / README
bloba7363d3adfa77c746d9370d8110f76aba7520769
1 # -*- text -*-
2 # Hey, Emacs!  This is a TEXT file.
4 --------------------------
5 README for the JAWS server
6 --------------------------
8 This is the README file for the JAWS server.
10 CONTENTS
12 1. Compiling
13   a. UNIX
14   b. Windows NT 4.0
16 2. Executing
17   a. svc.conf parameters
18   b. General Info
20 3. Limitations
22 4. Acknowledgements
24 5. New additions
26 ------------
27 1. Compiling
28 ------------
30 1a. Compiling under UNIX.
32         Assuming that the environment variable ACE_ROOT is set
33 correctly, and that you are using GNU make, compiling should simply
34 involve:
36         $ cd $ACE_ROOT/apps/JAWS/server
37         $ make clean
38         $ make depend
39         $ make
41 This will produce an executable named ``main''.
43 1b. Compiling under Windows NT 4.0.
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.
50 ------------
51 2. Executing
52 ------------
54 2a. svc.conf parameters.
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:
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 ().
78 2b. General Information
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.
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.
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''.
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''.
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''.
109         You may test the server by executing telnet, opening a
110 connection to the server machine on the server port.  For instance:
112         $ telnet machinename 5432
113         Trying ###.###.###.###...
114         Connected to machinename.your.domain
115         Escape character is '^]'.
116         GET /main.cpp
117         // main.cpp
118         //...
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.,
123         $ telnet machinename 5432
124         Trying ###.###.###.###...
125         Connected to machinename.your.domain
126         Escape character is '^]'.
127         GET /main.cpp HTTP/1.0
129         // main.cpp
130         //...
132         Where applicable, JAWS will perform ``~'' expansion for home
133 directories of usernames.
136 -----------
137 3. Features
138 -----------
140 (a) JAWS supports full HTTP/1.0 responses.
142 (b) JAWS support CGI scripts on UNIX.
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).
148 (d) Optimized filecaching.
150 --------------
151 4. Limitations
152 --------------
154 The following are TODO items for JAWS:
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       |
174 Questions, comments, corrections, suggestions are welcome.  Please
175 feel free to send me any such correspondence.
177 James Hu <jxh@cs.wustl.edu>
179 -------------------
180 4. Acknowledgements
181 -------------------
183         My partners in crime for this endeavor include:
185         Eastman-Kodak, Rochester N.Y.
186     and Object Technologies, Inc.       For providing funding for this
187                                         research.
189         Dr. Douglas Schmidt             For being my advisor, and
190                                         convincing my sponsors to fund
191                                         me.
193         Irfan Pyarali                   For porting JAWS to NT, and
194                                         for designing and implementing
195                                         the JAWS IO mechanism.
197         Sumedh Mungee                   For writing the benchmark
198                                         client, and performing the
199                                         UNIX benchmarks.
201         Tim Harrison                    For his comments, advice, and
202                                         help in designing the IO
203                                         mechanism used by JAWS.
205 -----------------------
206 5. Additions
207 -----------------------
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.
212 This capability is to be used with the RepositoryManager in CIAO.
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.
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.
228 To overcome the above problems we added the no caching functionality in JAWS.