1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="Netcgi_test.html">
<link rel="next" href="Netcgi_plex.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class attributes" rel=Appendix href="index_attributes.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Uq_gtk" rel="Chapter" href="Uq_gtk.html">
<link title="Equeue" rel="Chapter" href="Equeue.html">
<link title="Unixqueue" rel="Chapter" href="Unixqueue.html">
<link title="Uq_engines" rel="Chapter" href="Uq_engines.html">
<link title="Uq_socks5" rel="Chapter" href="Uq_socks5.html">
<link title="Unixqueue_mt" rel="Chapter" href="Unixqueue_mt.html">
<link title="Equeue_intro" rel="Chapter" href="Equeue_intro.html">
<link title="Uq_ssl" rel="Chapter" href="Uq_ssl.html">
<link title="Uq_tcl" rel="Chapter" href="Uq_tcl.html">
<link title="Netcgi_common" rel="Chapter" href="Netcgi_common.html">
<link title="Netcgi" rel="Chapter" href="Netcgi.html">
<link title="Netcgi_ajp" rel="Chapter" href="Netcgi_ajp.html">
<link title="Netcgi_scgi" rel="Chapter" href="Netcgi_scgi.html">
<link title="Netcgi_cgi" rel="Chapter" href="Netcgi_cgi.html">
<link title="Netcgi_fcgi" rel="Chapter" href="Netcgi_fcgi.html">
<link title="Netcgi_dbi" rel="Chapter" href="Netcgi_dbi.html">
<link title="Netcgi1_compat" rel="Chapter" href="Netcgi1_compat.html">
<link title="Netcgi_test" rel="Chapter" href="Netcgi_test.html">
<link title="Netcgi_porting" rel="Chapter" href="Netcgi_porting.html">
<link title="Netcgi_plex" rel="Chapter" href="Netcgi_plex.html">
<link title="Http_client" rel="Chapter" href="Http_client.html">
<link title="Telnet_client" rel="Chapter" href="Telnet_client.html">
<link title="Ftp_data_endpoint" rel="Chapter" href="Ftp_data_endpoint.html">
<link title="Ftp_client" rel="Chapter" href="Ftp_client.html">
<link title="Nethttpd_types" rel="Chapter" href="Nethttpd_types.html">
<link title="Nethttpd_kernel" rel="Chapter" href="Nethttpd_kernel.html">
<link title="Nethttpd_reactor" rel="Chapter" href="Nethttpd_reactor.html">
<link title="Nethttpd_engine" rel="Chapter" href="Nethttpd_engine.html">
<link title="Nethttpd_services" rel="Chapter" href="Nethttpd_services.html">
<link title="Nethttpd_plex" rel="Chapter" href="Nethttpd_plex.html">
<link title="Nethttpd_intro" rel="Chapter" href="Nethttpd_intro.html">
<link title="Netplex_types" rel="Chapter" href="Netplex_types.html">
<link title="Netplex_mp" rel="Chapter" href="Netplex_mp.html">
<link title="Netplex_mt" rel="Chapter" href="Netplex_mt.html">
<link title="Netplex_log" rel="Chapter" href="Netplex_log.html">
<link title="Netplex_controller" rel="Chapter" href="Netplex_controller.html">
<link title="Netplex_container" rel="Chapter" href="Netplex_container.html">
<link title="Netplex_sockserv" rel="Chapter" href="Netplex_sockserv.html">
<link title="Netplex_workload" rel="Chapter" href="Netplex_workload.html">
<link title="Netplex_main" rel="Chapter" href="Netplex_main.html">
<link title="Netplex_config" rel="Chapter" href="Netplex_config.html">
<link title="Netplex_kit" rel="Chapter" href="Netplex_kit.html">
<link title="Rpc_netplex" rel="Chapter" href="Rpc_netplex.html">
<link title="Netplex_cenv" rel="Chapter" href="Netplex_cenv.html">
<link title="Netplex_intro" rel="Chapter" href="Netplex_intro.html">
<link title="Netshm" rel="Chapter" href="Netshm.html">
<link title="Netshm_data" rel="Chapter" href="Netshm_data.html">
<link title="Netshm_hashtbl" rel="Chapter" href="Netshm_hashtbl.html">
<link title="Netshm_array" rel="Chapter" href="Netshm_array.html">
<link title="Netshm_intro" rel="Chapter" href="Netshm_intro.html">
<link title="Netconversion" rel="Chapter" href="Netconversion.html">
<link title="Netchannels" rel="Chapter" href="Netchannels.html">
<link title="Netstream" rel="Chapter" href="Netstream.html">
<link title="Mimestring" rel="Chapter" href="Mimestring.html">
<link title="Netmime" rel="Chapter" href="Netmime.html">
<link title="Netsendmail" rel="Chapter" href="Netsendmail.html">
<link title="Neturl" rel="Chapter" href="Neturl.html">
<link title="Netaddress" rel="Chapter" href="Netaddress.html">
<link title="Netbuffer" rel="Chapter" href="Netbuffer.html">
<link title="Netdate" rel="Chapter" href="Netdate.html">
<link title="Netencoding" rel="Chapter" href="Netencoding.html">
<link title="Netulex" rel="Chapter" href="Netulex.html">
<link title="Netaccel" rel="Chapter" href="Netaccel.html">
<link title="Netaccel_link" rel="Chapter" href="Netaccel_link.html">
<link title="Nethtml" rel="Chapter" href="Nethtml.html">
<link title="Netstring_str" rel="Chapter" href="Netstring_str.html">
<link title="Netstring_pcre" rel="Chapter" href="Netstring_pcre.html">
<link title="Netstring_mt" rel="Chapter" href="Netstring_mt.html">
<link title="Netmappings" rel="Chapter" href="Netmappings.html">
<link title="Netaux" rel="Chapter" href="Netaux.html">
<link title="Nethttp" rel="Chapter" href="Nethttp.html">
<link title="Netchannels_tut" rel="Chapter" href="Netchannels_tut.html">
<link title="Netmime_tut" rel="Chapter" href="Netmime_tut.html">
<link title="Netsendmail_tut" rel="Chapter" href="Netsendmail_tut.html">
<link title="Netulex_tut" rel="Chapter" href="Netulex_tut.html">
<link title="Neturl_tut" rel="Chapter" href="Neturl_tut.html">
<link title="Netsys" rel="Chapter" href="Netsys.html">
<link title="Netpop" rel="Chapter" href="Netpop.html">
<link title="Rpc_auth_dh" rel="Chapter" href="Rpc_auth_dh.html">
<link title="Rpc_key_service" rel="Chapter" href="Rpc_key_service.html">
<link title="Rpc_time" rel="Chapter" href="Rpc_time.html">
<link title="Rpc_auth_local" rel="Chapter" href="Rpc_auth_local.html">
<link title="Rtypes" rel="Chapter" href="Rtypes.html">
<link title="Xdr" rel="Chapter" href="Xdr.html">
<link title="Rpc" rel="Chapter" href="Rpc.html">
<link title="Rpc_program" rel="Chapter" href="Rpc_program.html">
<link title="Rpc_portmapper_aux" rel="Chapter" href="Rpc_portmapper_aux.html">
<link title="Rpc_packer" rel="Chapter" href="Rpc_packer.html">
<link title="Rpc_transport" rel="Chapter" href="Rpc_transport.html">
<link title="Rpc_client" rel="Chapter" href="Rpc_client.html">
<link title="Rpc_simple_client" rel="Chapter" href="Rpc_simple_client.html">
<link title="Rpc_portmapper_clnt" rel="Chapter" href="Rpc_portmapper_clnt.html">
<link title="Rpc_portmapper" rel="Chapter" href="Rpc_portmapper.html">
<link title="Rpc_server" rel="Chapter" href="Rpc_server.html">
<link title="Rpc_auth_sys" rel="Chapter" href="Rpc_auth_sys.html">
<link title="Rpc_intro" rel="Chapter" href="Rpc_intro.html">
<link title="Rpc_mapping_ref" rel="Chapter" href="Rpc_mapping_ref.html">
<link title="Rpc_ssl" rel="Chapter" href="Rpc_ssl.html">
<link title="Rpc_xti_client" rel="Chapter" href="Rpc_xti_client.html">
<link title="Shell_sys" rel="Chapter" href="Shell_sys.html">
<link title="Shell" rel="Chapter" href="Shell.html">
<link title="Shell_uq" rel="Chapter" href="Shell_uq.html">
<link title="Shell_mt" rel="Chapter" href="Shell_mt.html">
<link title="Shell_intro" rel="Chapter" href="Shell_intro.html">
<link title="Netsmtp" rel="Chapter" href="Netsmtp.html"><link title="Porting netcgi1 programs to netcgi2" rel="Section" href="#1_Portingnetcgi1programstonetcgi2">
<link title="Why porting and when?" rel="Subsection" href="#2_Whyportingandwhen">
<link title="Module Organization" rel="Subsection" href="#2_ModuleOrganization">
<link title="Interface Changes" rel="Subsection" href="#2_InterfaceChanges">
<link title="Porting strategies" rel="Subsection" href="#2_Portingstrategies">
<title>Ocamlnet 2 Reference Manual : Netcgi_porting</title>
</head>
<body>
<div class="navbar"><a href="Netcgi_test.html">Previous</a>
<a href="index.html">Up</a>
<a href="Netcgi_plex.html">Next</a>
</div>
<center><h1>Netcgi_porting</h1></center>
<br>
<br>
<a name="1_Portingnetcgi1programstonetcgi2"></a>
<h1>Porting <code class="code">netcgi1</code> programs to <code class="code">netcgi2</code></h1>
<p>
The library <code class="code">netcgi2</code> is a revised version of the old <code class="code">cgi</code> library
which is now also referred to as <code class="code">netcgi1</code>.
As any software, <code class="code">netcgi1</code> aged, and suffered more and more from
inadequate interfaces. Because of this it became necessary to
improve the interfaces from grounds up. The result is <code class="code">netcgi2</code>,
a new major version that tries to continue the good parts of
<code class="code">netcgi1</code> while replacing its problematic edges.
<p>
When this text is written, <code class="code">netcgi2</code> is still being developed, and
subject of discussion.
<p>
<a name="2_Whyportingandwhen"></a>
<h2>Why porting and when?</h2>
<p>
It is not possible to use <code class="code">netcgi1</code> and <code class="code">netcgi2</code> at the same time in the
same application. This means that one cannot gradually upgrade from
<code class="code">netcgi1</code> to <code class="code">netcgi2</code> by using more and more of the <code class="code">netcgi2</code> features.
Instead of this, it is necessary to <b>switch</b> from <code class="code">netcgi1</code> to <code class="code">netcgi2</code>
at one point in the lifetime of the web application.
<p>
The main benefit is that you have access to the newest <code class="code">netcgi2</code>
features. There are already a number of connectors that are not
present in <code class="code">netcgi1</code> (newer AJP protocol version, SCGI). Furthermore,
new features will only be added to <code class="code">netcgi2</code>.
<p>
However, if your application is already at or near its end of lifetime,
there is no need to port it to <code class="code">netcgi2</code>. The <code class="code">netcgi1</code> library will
remain in Ocamlnet 2, and bugs will be fixed.
<p>
<a name="2_ModuleOrganization"></a>
<h2>Module Organization</h2>
<p>
The new organization is very simple:
<p>
<ul>
<li><a href="Netcgi.html"><code class="code">Netcgi</code></a> defines all basic types. Previously, this was done in the
two modules <code class="code">Netcgi_env</code> and <code class="code">Netcgi_types</code></li>
<li>For every connector c there is one module <code class="code">Netcgi_</code>c implementing
it. Especially the classic CGI connector is now in <code class="code">Netcgi_cgi</code>.
Previously, the CGI connector was defined in <code class="code">Netcgi</code>, and there
used to be several modules per connector.</li>
<li><a href="Netcgi_common.html"><code class="code">Netcgi_common</code></a> defines service functions to define new connectors.</li>
</ul>
There is also a module <a href="Netcgi1_compat.html"><code class="code">Netcgi1_compat</code></a> trying to ease porting. See
below for a discussion.
<p>
<a name="2_InterfaceChanges"></a>
<h2>Interface Changes</h2>
<p>
Most of the types remain the same, or almost the same. A few changes
have been done:
<p>
<ul>
<li><b>Immutability of arguments:</b> A <a href="Netcgi.cgi_argument.html"><code class="code">Netcgi.cgi_argument</code></a> is no longer writable.
Furthermore, the list of arguments in a <a href="Netcgi.cgi_activation.html"><code class="code">Netcgi.cgi_activation</code></a> can no longer
be modified. There are some new service functions to modify lists
of arguments in case one needs such a list.</li>
<li><b>Enhanced cookie API:</b> Cookie formats newer than the old Netscape
format are supported. Old and new cookie types can be transformed
into each other. See the module <a href="Netcgi.Cookie.html"><code class="code">Netcgi.Cookie</code></a>.</li>
<li><b>Exception Handling:</b> The <a href="Netcgi_common.html#EXCEPTIONHTTP"><code class="code">Netcgi_common.HTTP</code></a> exception can be used to exit
from a processor at any time. There is the notion of an exception
handler for web-related exceptions.</li>
<li><b>Simplified Environments:</b> The CGI environments
<a href="Netcgi.cgi_environment.html"><code class="code">Netcgi.cgi_environment</code></a> have been simplified.
It is only distinguished between two states: Output headers have been/
have not been sent. Other processing states are hidden by the
implementation.</li>
<li><b>Improved finalization:</b> All CGI arguments are finalized at the
end of the request ensuring that temporary files are deleted.
It is also possible to register further finalizers using the
<code class="code">Netcgi.cgi_activation.at_exit</code>
method.</li>
</ul>
The connectors, however, are now created in very different ways. This
is mainly driven by uniformity: There should be a method of creating
web connectors that works for every kind of connector. Because of this,
the code instantiating connectors in application must always be changed
so it matches the new, uniform conventions. Fortunately, this code is usually
not very extensive.
<p>
<a name="2_Portingstrategies"></a>
<h2>Porting strategies</h2>
<p>
<a name="3_StrategyUsenewAPI"></a>
<h3>Strategy: Use new API</h3>
<p>
In the long term this is the best strategy. In principle, one has to
distinguish between
<p>
<ul>
<li>program parts that access <code class="code">netcgi</code> values, and</li>
<li>program parts that connect the <code class="code">netcgi</code> application with the web
server.</li>
</ul>
Porting the first parts is fairly simple, because the types of the
<code class="code">netcgi</code> values do not change much. For example, the function
<code class="code">web_page</code> for <code class="code">netcgi1</code>
<p>
<pre><code class="code">
(* This is [netcgi1] code! *)
let web_page (cgi : Netcgi_types.cgi_activation) =
let webarg = cgi # argument_value "webarg" in
cgi # set_header();
cgi # output # output_string ("The argument is: " ^ webarg)
</code></pre>
<p>
would read in the version for <code class="code">netcgi2</code> as follows:
<p>
<pre><code class="code">
(* This is [netcgi2] code! *)
let web_page (cgi : Netcgi.cgi_activation) =
let webarg = cgi # argument_value "webarg" in
cgi # set_header();
cgi # output # output_string ("The argument is: " ^ webarg)
</code></pre>
<p>
The <b>only</b> change is that the type <code class="code">cgi_activation</code> is now defined
in the module <code class="code">Netcgi</code> and no longer in <code class="code">Netcgi_types</code>. It is expected
that this simple way of porting applies to almost all parts of
<code class="code">netcgi</code> applications.
<p>
By the way, the type <code class="code">cgi_activation</code> can now be abbreviated as <code class="code">cgi</code>,
as this is the type name that needs to be written down most
frequently.
<p>
<a name="4_ThenewCGIconnector"></a>
<h4>The new CGI connector</h4>
<p>
In <code class="code">netcgi1</code>, the CGI connector is selected by instantiating the class
<code class="code">Netcgi.std_activation</code>, as in:
<p>
<pre><code class="code">(* This is [netcgi1] code! *)
let cgi = new Netcgi.std_activation() in
process cgi
</code></pre>
<p>
It is assumed that <code class="code">process</code> is a function taking a <code class="code">cgi_activation</code>
as argument, and processing the request.
<p>
The corresponding <code class="code">netcgi2</code> call is:
<p>
<pre><code class="code">(* This is [netcgi2] code! *)
Netcgi_cgi.run process
</code></pre>
<p>
As you see, <a href="Netcgi_cgi.html#VALrun"><code class="code">Netcgi_cgi.run</code></a> is now responsible for calling <code class="code">process</code>.
<p>
<a name="4_ThenewFastCGIconnector"></a>
<h4>The new FastCGI connector</h4>
<p>
In <code class="code">netcgi1</code> there are several ways of using FastCGI. The most common is
to call <code class="code">Netcgi_fcgi.serv</code> as in:
<p>
<pre><code class="code">(* This is [netcgi1] code! *)
Netcgi_fcgi.serv process optype
</code></pre>
<p>
It is assumed that <code class="code">process</code> is a function taking a <code class="code">cgi_activation</code>
as argument, and processing the request. <code class="code">optype</code> is a valid
operating type.
<p>
The corresponding <code class="code">netcgi2</code> call is:
<p>
<pre><code class="code">(* This is [netcgi2] code! *)
let process' cgi = process (cgi :> Netcgi.cgi_activation) in
Netcgi_fcgi.run ~output_type:optype process'
</code></pre>
<p>
Note that the argument of <code class="code">process'</code> is a slightly extended version
of <code class="code">cgi_activation</code>, so you usually need the coercion to cut off the
additional part of the object interface.
<p>
<a name="4_ThenewAJPconnector"></a>
<h4>The new AJP connector</h4>
<p>
The new connector supports now the AJP version 1.3 - this is the default
version used by Jakarta and mod_jk. In <code class="code">netcgi1</code>, only version 1.2 of
the AJP protocol was supported. The new protocol version is no big
improvement, however. It uses a slightly more compact representation
of the data. The biggest plus is better support of SSL.
<p>
In <code class="code">netcgi1</code> there was some special machinery around the AJP connector
to create worker processes. This code has been completely removed
in favor of <code class="code">netplex</code>, the new general-purpose server framework.
Because of that, porting AJP applications is probably a bit of work,
and we cannot give a receipt here how to do that.
<p>
<a name="3_StrategyUseNetcgi1compat"></a>
<h3>Strategy: Use <code class="code">Netcgi1_compat</code></h3>
<p>
If you want to use the new connectors but currently do not have time
to check all your code for changes, there is a special helper module
called <code class="code">Netcgi1_compat</code> that provides a <code class="code">netcgi1</code>-compatible API
on top of either <code class="code">netcgi1</code> or <code class="code">netcgi2</code>.
<p>
Because <code class="code">Netcgi1_compat</code> is available in both <code class="code">netcgi1</code> and <code class="code">netcgi2</code>
you can write code that can be compiled for both versions without
needing to change anything. Note, however, that this module is not
100% identical in both versions - the <code class="code">netcgi2</code> version includes some
additional functions that converts values from their <code class="code">netcgi1</code>
representation to their <code class="code">netcgi2</code> representation and vice versa.
Unfortunately, this makes the two versions of this module
binary-incompatible, so you have to recompile your code for either
<code class="code">netcgi1</code> or <code class="code">netcgi2</code>.
<p>
The <code class="code">Netcgi1_compat</code> module simply contains the relevant parts of
the <code class="code">netcgi1</code> API as submodules. That means you can access
<p>
<ul>
<li>the <code class="code">netcgi1</code> version of the module <code class="code">Netcgi_types</code> as
<code class="code">Netcgi1_compat.Netcgi_types</code></li>
<li>the <code class="code">netcgi1</code> version of the module <code class="code">Netcgi_env</code> as
<code class="code">Netcgi1_compat.Netcgi_env</code></li>
<li>the <code class="code">netcgi1</code> version of the module <code class="code">Netcgi</code> as <code class="code">Netcgi1_compat.Netcgi</code></li>
</ul>
Other modules of <code class="code">netcgi1</code> are not covered by the compatibility API.
In <code class="code">Netcgi</code>, the <code class="code">custom_activation</code> class has been left out.
<p>
You can usually port code to using this API by either
<p>
<ul>
<li>prefixing these module names in source code with <code class="code">Netcgi1.</code>, e.g.
<code class="code">new Netcgi.std_activation()</code> would be turned into
<code class="code">new Netcgi1_compat.Netcgi.std_activation()</code></li>
<li>opening the module <code class="code">Netcgi1</code> at the beginning of each .ml and .mli
file by an <code class="code">open Netcgi1_compat</code>.</li>
</ul>
Except <code class="code">Netcgi.std_activation</code>, the <code class="code">netcgi1</code> way of creating a
connector for classic CGI, there are no connectors in the
compatibility API. If you need one, you must take it directly
from either <code class="code">netcgi1</code> or <code class="code">netcgi2</code>. For example, to connect using
FastCGI:
<p>
<pre><code class="code">(* This is code for both [netcgi1] and [netcgi2]! *)
let process (cgi : Netcgi1_compat.Netcgi.cgi_activation) =
...
(* This is [netcgi2] code! *)
let process_netcgi2 cgi2 =
let cgi1 = Netcgi1_compat.Netcgi_types.to_compat_activation cgi2 in
process cgi1
Netcgi_fcgi.run ~output_type process'
</code></pre>
<br>
</body></html>
|
