1.1 --- a/docs/writing-adapters.html Sat Oct 13 23:43:05 2007 +0000
1.2 +++ b/docs/writing-adapters.html Sat Oct 13 23:43:21 2007 +0000
1.3 @@ -5,6 +5,7 @@
1.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
1.5 <body>
1.6 <h1>Writing Adapters</h1>
1.7 +
1.8 <p>Depending on how "simple" the
1.9 adapter code is allowed to be for a
1.10 given
1.11 @@ -14,46 +15,93 @@
1.12 initialises and deploys your application, or to produce a more
1.13 complicated
1.14 piece of code which satisfies some more demanding server requirements.</p>
1.15 -<h2>Simple Adapters - Using the
1.16 -deploy Function</h2>
1.17 -<p>When deploying an application,
1.18 -it is possible to use a one-shot
1.19 -deployment
1.20 -function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The
1.21 -<code>deploy</code>
1.22 -function is called as follows:</p>
1.23 -<pre>deploy(resource)<br />deploy(resource, authenticator) # where authenticators are used</pre>
1.24 -<p>For some frameworks, an address
1.25 -may be specified:</p>
1.26 -<pre>deploy(resource, address=(host_string, port_integer))<br />deploy(resource, authenticator, address=(host_string, port_integer))</pre>
1.27 -<p>And for some frameworks, the return value of the function is important:</p><pre>something = deploy(resource)<br />something, something_else = deploy(resource, authenticator)</pre><p>Here is a summary of which
1.28 +
1.29 +<h2>Simple Adapters - Using the deploy Function</h2>
1.30 +
1.31 +<p>When deploying an application, it is possible to use a one-shot deployment
1.32 +function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python,
1.33 +Twisted and WSGI configurations. The <code>deploy</code> function is called as
1.34 +follows:</p>
1.35 +
1.36 +<pre>deploy(resource)
1.37 +deploy(resource, authenticator) # where authenticators are used
1.38 +</pre>
1.39 +
1.40 +<p><strong>Note</strong> that for WSGI, the functions <code>deploy_as_cgi</code>
1.41 +and <code>deploy_with_wsgiref</code> are provided instead, and the appropriate
1.42 +function could be imported like this:</p>
1.43 +
1.44 +<pre>from WebStack.Adapters.WSGI import deploy_as_cgi as deploy</pre>
1.45 +
1.46 +<p>For some frameworks, an address may be specified:</p>
1.47 +
1.48 +<pre>deploy(resource, address=(host_string, port_integer))
1.49 +deploy(resource, authenticator, address=(host_string, port_integer))
1.50 +</pre>
1.51 +
1.52 +<p>And for some frameworks, the return value of the function is important:</p>
1.53 +
1.54 +<pre>something = deploy(resource)
1.55 +something, something_else = deploy(resource, authenticator)
1.56 +</pre>
1.57 +
1.58 +<p>Here is a summary of which
1.59 frameworks require address information and which produce important return values from the <code>deploy</code> function:</p>
1.60 +
1.61 <table border="1" cellpadding="5" cellspacing="0">
1.62 <tbody>
1.63 <tr>
1.64 <th>Framework</th>
1.65 - <th>Address Information</th><th>Return Values</th>
1.66 + <th>Address Information</th>
1.67 + <th>Return Values</th>
1.68 </tr>
1.69 <tr>
1.70 <td>BaseHTTPRequestHandler</td>
1.71 - <td>Supported</td><td align="undefined" valign="undefined"></td>
1.72 + <td>Supported</td>
1.73 + <td></td>
1.74 </tr>
1.75 <tr>
1.76 <td>CGI</td>
1.77 - <td>Ignored</td><td align="undefined" valign="undefined"></td>
1.78 + <td>Ignored</td>
1.79 + <td></td>
1.80 + </tr>
1.81 + <tr>
1.82 + <td>Django</td>
1.83 + <td>Ignored</td>
1.84 + <td>Handler function</td>
1.85 </tr>
1.86 - <tr><td align="undefined" valign="undefined">Django</td><td align="undefined" valign="undefined">Ignored</td><td align="undefined" valign="undefined">Handler function</td></tr><tr><td align="undefined" valign="undefined">Java Servlet</td><td align="undefined" valign="undefined">Ignored</td><td align="undefined" valign="undefined">Servlet class</td></tr><tr><td align="undefined" valign="undefined">mod_python</td><td align="undefined" valign="undefined">Ignored</td><td align="undefined" valign="undefined">Handler function and authenticator function (a 2-tuple)</td></tr><tr>
1.87 + <tr>
1.88 + <td>Java Servlet</td>
1.89 + <td>Ignored</td>
1.90 + <td>Servlet class</td>
1.91 + </tr>
1.92 + <tr>
1.93 + <td>mod_python</td>
1.94 + <td>Ignored</td>
1.95 + <td>Handler function and authenticator function (a 2-tuple)</td>
1.96 + </tr>
1.97 + <tr>
1.98 <td>Twisted</td>
1.99 - <td>Supported (<code>host_string</code>
1.100 -is ignored)</td><td align="undefined" valign="undefined"></td>
1.101 + <td>Supported (<code>host_string</code> is ignored)</td>
1.102 + <td></td>
1.103 </tr>
1.104 - <tr><td align="undefined" valign="undefined">Webware (> 0.8.1)</td><td align="undefined" valign="undefined">Ignored</td><td align="undefined" valign="undefined">URL context object</td></tr><tr>
1.105 + <tr>
1.106 + <td>Webware (> 0.8.1)</td>
1.107 + <td>Ignored</td>
1.108 + <td>URL context object</td>
1.109 + </tr>
1.110 + <tr>
1.111 <td>WSGI</td>
1.112 - <td>Ignored</td><td align="undefined" valign="undefined"></td>
1.113 + <td>Supported for <code>deploy_with_wsgiref</code><br />
1.114 + Ignored for <code>deploy_as_cgi</code>
1.115 + </td>
1.116 + <td></td>
1.117 </tr>
1.118 </tbody>
1.119 </table>
1.120 +
1.121 <h3>Debugging Applications</h3>
1.122 +
1.123 <p>Sometimes, when resources throw unhandled exceptions when processing
1.124 requests, it is desirable to see the details of the exceptions either
1.125 in the Web browser or in the console from which the application was
1.126 @@ -64,23 +112,16 @@
1.127 false value, will not supress unhandled exceptions with an "internal
1.128 server error" response, but will instead provide the underlying server
1.129 environment's report of such exceptions.</p>
1.130 -<h2><a name="table">Complicated Adapters -
1.131 -Providing
1.132 -Framework-Specific Objects</a></h2>
1.133 -<p>The remaining frameworks (Java
1.134 -Servlet,
1.135 -mod_python, Webware and
1.136 -Zope) do
1.137 -not support the <code>deploy</code>
1.138 -function due to the way
1.139 -applications are
1.140 -typically integrated into the various server mechanisms. In these
1.141 -cases, it
1.142 -may be worth investigating the examples provided and using their
1.143 -adapter code
1.144 -as a template for the code for your own applications. Here is a summary
1.145 -which
1.146 +
1.147 +<h2><a name="table">Complicated Adapters - Providing Framework-Specific Objects</a></h2>
1.148 +
1.149 +<p>The remaining frameworks (Java Servlet, mod_python, Webware and Zope) do
1.150 +not support the <code>deploy</code> function due to the way applications are
1.151 +typically integrated into the various server mechanisms. In these cases, it
1.152 +may be worth investigating the examples provided and using their adapter code
1.153 +as a template for the code for your own applications. Here is a summary which
1.154 indicates the server environments or frameworks which need most work:</p>
1.155 +
1.156 <table border="1" cellpadding="5" cellspacing="0">
1.157 <tbody>
1.158 <tr>
1.159 @@ -91,16 +132,14 @@
1.160 <tr>
1.161 <td>BaseHTTPRequestHandler</td>
1.162 <td>Simple - see above</td>
1.163 - <td>Run the adapter code
1.164 -directly</td>
1.165 + <td>Run the adapter code directly</td>
1.166 </tr>
1.167 <tr>
1.168 <td>CGI</td>
1.169 <td>Simple - see above</td>
1.170 - <td>Web server runs the
1.171 -adapter code</td>
1.172 + <td>Web server runs the adapter code</td>
1.173 </tr>
1.174 - <tr><td align="undefined" valign="undefined">Django</td><td align="undefined" valign="undefined">Simple - see above</td><td align="undefined" valign="undefined">The adapter prepares the handler function</td></tr><tr>
1.175 + <tr><td>Django</td><td>Simple - see above</td><td>The adapter prepares the handler function</td></tr><tr>
1.176 <td>Java Servlet</td>
1.177 <td><span style="font-family: monospace;"></span><code></code>Simple - see above</td>
1.178 <td>The adapter prepares the servlet class</td>
1.179 @@ -118,25 +157,21 @@
1.180 </tr>
1.181 <tr>
1.182 <td>Webware</td>
1.183 - <td><= 0.8.1: Must
1.184 -implement <code>InstallInWebKit</code>
1.185 -function<br />
1.186 + <td><= 0.8.1: Must implement <code>InstallInWebKit</code> function<br />
1.187 > 0.8.1: Simple - see above</td>
1.188 - <td>Application must be
1.189 -deployed within WebKit</td>
1.190 + <td>Application must be deployed within WebKit</td>
1.191 </tr>
1.192 <tr>
1.193 <td>WSGI</td>
1.194 <td>Simple - see above</td>
1.195 - <td>Web server runs the
1.196 -adapter code</td>
1.197 + <td>Either the adapter code is run directly (<code>deploy_with_wsgiref</code>)<br />
1.198 + Or the Web server runs the adapter code (<code>deploy_as_cgi</code>)
1.199 + </td>
1.200 </tr>
1.201 <tr>
1.202 <td>Zope</td>
1.203 - <td>Must provide lots of
1.204 -Zope administative classes and functions</td>
1.205 - <td>Application must be
1.206 -deployed within Zope</td>
1.207 + <td>Must provide lots of Zope administative classes and functions</td>
1.208 + <td>Application must be deployed within Zope</td>
1.209 </tr>
1.210 </tbody>
1.211 </table>