<!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>
