← Back to branch summary

~ubuntu-branches/ubuntu/trusty/ocamlnet/trusty

« back to all changes in this revision

Viewing changes to examples/cgi/netcgi1/jserv/README.jserv

  • Committer: Bazaar Package Importer
  • Author(s): Stéphane Glondu
  • Date: 2011-09-02 14:12:33 UTC
  • mfrom: (18.2.3 sid)
  • Revision ID: james.westby@ubuntu.com-20110902141233-zbj0ygxb92u6gy4z
Tags: 3.4-1
http://bugs.debian.org/637147
* New upstream release
  - add a new NetcgiRequire directive to ease dependency management
    (Closes: #637147)
  - remove patches that were applied upstream:
    + Added-missing-shebang-lines-in-example-shell-scripts
    + Try-also-ocamlc-for-POSIX-threads

Show diffs side-by-side

added added

removed removed

Lines of Context:
examples/cgi/netcgi1/jserv/README.jserv
1
 
**********************************************************************
2
 
***                    Experimental JSERV support                  ***
3
 
**********************************************************************
4
 
 
5
 
The jserv protocol is very similar to CGI, but it does not start a new
6
 
process for every HTTP request. The request is encoded and forwarded
7
 
to a server process that handles it. The server process can be started
8
 
manually or on demand by the web server.  As a picture:
9
 
 
10
 
          BROWSER    <----HTTP---->  WEBSERVER   <----JSERV---->   JSERVD
11
 
 
12
 
There is a relatively old module for Apache (mod_jserv) implementing
13
 
the jserv client.  You can get it from
14
 
http://java.apache.org/jserv. Note that the Java Apache project is
15
 
dead, but the jserv protocol is also used by Jakarta: Tomcat contains
16
 
the module mod_jk that supports the same jserv protocol version (1.2)
17
 
as the original implementation but with a different configuration
18
 
file. However, I am currently using mod_jserv for my experiments; it
19
 
is smaller and easier to extract from the whole distribution. The
20
 
Jakarta version will surely become important in the future.
21
 
 
22
 
I have written a server for jserv in O'Caml that uses the existing
23
 
netcgi infrastructure. This means that it is simple to convert an
24
 
existing CGI script into a jserv server, it is only necessary to
25
 
change the main program. 
26
 
 
27
 
Currently, the following server architectures are supported:
28
 
 
29
 
- Sequential servers: One request is processed after the other
30
 
 
31
 
- Forking servers: For every request a new subprocess is started. 
32
 
  (This looks like CGI, but has still advantages, as the main process
33
 
  can do expensive initializations.)
34
 
 
35
 
There is also a working experiment with a multi-threaded server,
36
 
but the code is not yet ready to be released (look into the CVS tree
37
 
under src/cgi/tests).
38
 
 
39
 
A typical CGI script is:
40
 
 
41
 
let cgi = new std_activation() in
42
 
... (* analyze request *)
43
 
cgi # set_header ... ();
44
 
cgi # output # output_string ...;
45
 
cgi # output # commit_work()
46
 
 
47
 
The corresponding jserv program is:
48
 
 
49
 
let process cgi =
50
 
  ... (* analyze request *)
51
 
  cgi # set_header ... ();
52
 
  cgi # output # output_string ...;
53
 
  cgi # output # commit_work()
54
 
 
55
 
let srvtype =
56
 
  `Sequential  (* or `Forking *)
57
 
      [ "add", { req_activate = process;
58
 
                 req_processing = (fun _ _ -> `Memory);
59
 
                 req_operating_type = buffered_transactional_optype;
60
 
               }
61
 
      ]
62
 
 
63
 
jvm_emu_main
64
 
  (run srvtype `Ajp_1_2)
65
 
 
66
 
 
67
 
As you can see, the request handler (once the cgi object is available) is the
68
 
same. Some explanations:
69
 
 
70
 
- jvm_emu_main: This is the main program. It emulates the JVM command
71
 
  signature which is necessary because the jservd is started from
72
 
  mod_jserv, and mod_jserv assumes it starts a JVM. The important
73
 
  thing is that the second command argument is the name of the
74
 
  property file to read in ( ==> props).  
75
 
 
76
 
  Apache starts the jserv server by executing a command like
77
 
 
78
 
  /where/it/is/jservd -classpath XXX jserv.properties
79
 
 
80
 
  jvm_emu_main ignores the classpath, but extracts the name of the
81
 
  jserv.properties file from the command, and parses it to get more 
82
 
  information.
83
 
 
84
 
- In the property file the address and port of the server socket is
85
 
  configured, and optionally the authentication method (the connection
86
 
  betweem the web server and jservd can be secured).
87
 
 
88
 
  See README.properties for a minimal properties file. (You have to 
89
 
  write one.)
90
 
 
91
 
- The function Netcgi_jserv_app.run starts the server. It gets two
92
 
  arguments: The server type and the protocol type. The latter is
93
 
  currently always `Ajp_1_2 (Apache Jserv Protocol 1.2). The server
94
 
  type determines the architecture (sequential or forking), and the
95
 
  mapping of the servlet names to the request handlers.
96
 
 
97
 
  In this example, "add" is the name of the servlet, and the 
98
 
  record specifies how to handle requests arriving for this servlet.
99
 
  
100
 
  The httpd.conf file defines the root URL for the servlets, e.g.
101
 
  /servlets, and the servlet names are simply appended. In the example,
102
 
  the servlet has the URL /servlets/add.
103
 
 
104
 
  (Note: Alternatively, it is also possible to start several jservd
105
 
  servers, for every servlet a new one.)
106
 
 
107
 
In this directory, you find two examples:
108
 
 
109
 
- add_sequential.ml: Same as ../cgi/add.cgi, but uses a sequential
110
 
  jservd
111
 
 
112
 
- add_forking.ml: Same as ../cgi/add.cgi, but uses a forking jservd
113
 
 
114
 
Once you have compiled them, there are two executables: add_sequential
115
 
and add_forking. These are already the daemons. Try
116
 
 
117
 
./add_sequential -help
118
 
 
119
 
- you will see that the daemon accepts JVM-compatible arguments. The
120
 
daemon can be started manually, or by the web server. Which method is
121
 
better depends on:
122
 
 
123
 
- As which user the daemons run. If the user is the same as the web
124
 
  server, it is preferrable to let the web server start the jserv server.
125
 
 
126
 
- Whether the web server acts as "watch dog" for the jserv server.
127
 
  If the jservd crashes, the web server can automatically restart it.
128
 
 
129
 
The way the jservd is started is configured in httpd.conf. See
130
 
README.httpd.conf for details.
131
 
 
132
 
So the next steps to get the examples running are:
133
 
 
134
 
- Modify your httpd.conf
135
 
 
136
 
- Write jserv.properties and put the file at the right place
137
 
 
138
 
- Restart your web server
139
 
 
140
 
 
141
 
*** Notes on installing mod_jserv ***************************************
142
 
 
143
 
If you don't have already mod_jserv.so for your Apache: You need
144
 
http://java.apache.org/jserv/dist/ApacheJServ-1.1.2.tar.gz. You don't need
145
 
the JSDK classes (but a Java compiler; only to satisfy the configure script).
146
 
Do:
147
 
  mkdir -p jsdk/javax/servlet
148
 
  touch jsdk/javax/servlet/Servlet.class
149
 
This way the configure script thinks you have the JSDK classes.
150
 
  ./configure --with-apxs=/usr/sbin/apxs --prefix=/tmp/jserv --with-JSDK=jsdk
151
 
(Maybe you need --enable-EAPI, too)
152
 
Then do 
153
 
  cd src/c
154
 
  make
155
 
The resulting mod_jserv.so was in src/c/.libs (i.e. where libtool stores
156
 
libraries before installation).
157
 
 
158
 
If you have already mod_jk.so for your Apache: I don't know if it works.
159
 
Eventually it is necessary to change the names of the properties in
160
 
jvm_emu_main. httpd.conf is probably different, too. Furthermore, mod_jk
161
 
seems to pass fewer variables (e.g. SCRIPT_NAME is omitted). I had a 
162
 
quick look at the source code, so I know that things are slightly different.