1.1 --- a/docs/writing-adapters.html Sat Apr 30 20:31:51 2005 +0000
1.2 +++ b/docs/writing-adapters.html Sat Apr 30 20:44:03 2005 +0000
1.3 @@ -8,22 +8,29 @@
1.4 </head>
1.5 <body>
1.6 <h1>Writing Adapters</h1>
1.7 -<p>Depending on how "simple" the adapter code is allowed to be for a
1.8 +<p>Depending on how "simple" the
1.9 +adapter code is allowed to be for a
1.10 given
1.11 -server environment (see the <a href="#table">table</a> for a
1.12 +server environment (see the <a href="#table">table</a>
1.13 +for a
1.14 summary), you will either need to write a small piece of code which
1.15 initialises and deploys your application, or to produce a more
1.16 complicated
1.17 piece of code which satisfies some more demanding server requirements.</p>
1.18 -<h2>Simple Adapters - Using the deploy Function</h2>
1.19 -<p>When deploying an application, it is possible to use a one-shot
1.20 +<h2>Simple Adapters - Using the
1.21 +deploy Function</h2>
1.22 +<p>When deploying an application,
1.23 +it is possible to use a one-shot
1.24 deployment
1.25 function for BaseHTTPRequestServer, CGI, Twisted and WSGI. The
1.26 -<code>deploy</code> function is called as follows:</p>
1.27 +<code>deploy</code>
1.28 +function is called as follows:</p>
1.29 <pre>deploy(resource)<br />deploy(resource, authenticator) # where authenticators are used</pre>
1.30 -<p>For some frameworks, an address may be specified:</p>
1.31 +<p>For some frameworks, an address
1.32 +may be specified:</p>
1.33 <pre>deploy(resource, address=(host_string, port_integer))<br />deploy(resource, authenticator, address=(host_string, port_integer))</pre>
1.34 -<p>Here is a summary of which frameworks require address information:</p>
1.35 +<p>Here is a summary of which
1.36 +frameworks require address information:</p>
1.37 <table border="1" cellpadding="5" cellspacing="0">
1.38 <tbody>
1.39 <tr>
1.40 @@ -40,7 +47,8 @@
1.41 </tr>
1.42 <tr>
1.43 <td>Twisted</td>
1.44 - <td>Supported (<code>host_string</code> is ignored)</td>
1.45 + <td>Supported (<code>host_string</code>
1.46 +is ignored)</td>
1.47 </tr>
1.48 <tr>
1.49 <td>WSGI</td>
1.50 @@ -48,11 +56,26 @@
1.51 </tr>
1.52 </tbody>
1.53 </table>
1.54 -<h2><a name="table" />Complicated Adapters - Providing
1.55 -Framework-Specific Objects</h2>
1.56 -<p>The remaining frameworks (Java Servlet, mod_python, Webware and
1.57 +<h3>Debugging Applications</h3>
1.58 +<p>Sometimes, when resources throw unhandled exceptions when processing
1.59 +requests, it is desirable to see the details of the exceptions either
1.60 +in the Web browser or in the console from which the application was
1.61 +started. For such purposes, a parameter to the <code>deploy</code>
1.62 +function can be used:</p>
1.63 +<pre>deploy(resource, handle_errors=0)</pre>
1.64 +<p>The <code>handle_errors</code> parameter, if specified with a
1.65 +false value, will not supress unhandled exceptions with an "internal
1.66 +server error" response, but will instead provide the underlying server
1.67 +environment's report of such exceptions.</p>
1.68 +<h2><a name="table">Complicated Adapters -
1.69 +Providing
1.70 +Framework-Specific Objects</a></h2>
1.71 +<p>The remaining frameworks (Java
1.72 +Servlet,
1.73 +mod_python, Webware and
1.74 Zope) do
1.75 -not support the <code>deploy</code> function due to the way
1.76 +not support the <code>deploy</code>
1.77 +function due to the way
1.78 applications are
1.79 typically integrated into the various server mechanisms. In these
1.80 cases, it
1.81 @@ -71,49 +94,62 @@
1.82 <tr>
1.83 <td>BaseHTTPRequestHandler</td>
1.84 <td>Simple - see above</td>
1.85 - <td>Run the adapter code directly</td>
1.86 + <td>Run the adapter code
1.87 +directly</td>
1.88 </tr>
1.89 <tr>
1.90 <td>CGI</td>
1.91 <td>Simple - see above</td>
1.92 - <td>Web server runs the adapter code</td>
1.93 + <td>Web server runs the
1.94 +adapter code</td>
1.95 </tr>
1.96 <tr>
1.97 <td>Java Servlet</td>
1.98 <td>Must subclass <code>HttpServlet</code></td>
1.99 - <td>Application must be deployed using supplied tools</td>
1.100 + <td>Application must be
1.101 +deployed using supplied tools</td>
1.102 </tr>
1.103 <tr>
1.104 <td>mod_python</td>
1.105 - <td>Must implement <code>handler</code> function</td>
1.106 - <td>Web server runs the adapter code (which must be declared
1.107 + <td>Must implement <code>handler</code>
1.108 +function</td>
1.109 + <td>Web server runs the
1.110 +adapter code (which must be declared
1.111 within Apache)</td>
1.112 </tr>
1.113 <tr>
1.114 <td>Twisted</td>
1.115 <td>Simple - see above</td>
1.116 - <td>Run the adapter code directly</td>
1.117 + <td>Run the adapter code
1.118 +directly</td>
1.119 </tr>
1.120 <tr>
1.121 <td>Webware</td>
1.122 - <td><= 0.8.1: Must implement <code>InstallInWebKit</code>
1.123 + <td><= 0.8.1: Must
1.124 +implement <code>InstallInWebKit</code>
1.125 function<br />
1.126 -> 0.8.1: Simple, but must provide a <code>urlParser</code> object</td>
1.127 - <td>Application must be deployed within WebKit</td>
1.128 +> 0.8.1: Simple, but must provide a <code>urlParser</code>
1.129 +object</td>
1.130 + <td>Application must be
1.131 +deployed within WebKit</td>
1.132 </tr>
1.133 <tr>
1.134 <td>WSGI</td>
1.135 <td>Simple - see above</td>
1.136 - <td>Web server runs the adapter code</td>
1.137 + <td>Web server runs the
1.138 +adapter code</td>
1.139 </tr>
1.140 <tr>
1.141 <td>Zope</td>
1.142 - <td>Must provide lots of Zope administative classes and functions</td>
1.143 - <td>Application must be deployed within Zope</td>
1.144 + <td>Must provide lots of
1.145 +Zope administative classes and functions</td>
1.146 + <td>Application must be
1.147 +deployed within Zope</td>
1.148 </tr>
1.149 </tbody>
1.150 </table>
1.151 -<p>See <a href="deploying-applications.html">"Deploying an Application"</a>
1.152 +<p>See <a href="deploying-applications.html">"Deploying an
1.153 +Application"</a>
1.154 for more details of the deployment process for each environment.</p>
1.155 </body>
1.156 </html>