WebStack

docs/writing-adapters.html

733:26865b172666
2007-11-12 paulb [project @ 2007-11-12 00:51:34 by paulb] Added a StringResource class for simple static resources. Introduced base classes for common authentication activities. Merged "app", "path" and "qs" fields into a single "app" field for login and redirection. Added support for OpenID authentication.
     1 <?xml version="1.0" encoding="iso-8859-1"?>     2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">     3 <html xmlns="http://www.w3.org/1999/xhtml"><head>     4   <title>Writing Adapters</title>     5   <link href="styles.css" rel="stylesheet" type="text/css" /></head>     6 <body>     7 <h1>Writing Adapters</h1>     8      9 <p>Depending on how "simple" the    10 adapter code is allowed to be for a    11 given    12 server environment (see the <a href="#table">table</a>    13 for a    14 summary), you will either need to write a small piece of code which    15 initialises and deploys your application, or to produce a more    16 complicated    17 piece of code which satisfies some more demanding server requirements.</p>    18     19 <h2>Simple Adapters - Using the deploy Function</h2>    20     21 <p>When deploying an application, it is possible to use a one-shot deployment    22 function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python,    23 Twisted and WSGI configurations. The <code>deploy</code> function is called as    24 follows:</p>    25     26 <pre>deploy(resource)    27 deploy(resource, authenticator) # where authenticators are used    28 </pre>    29     30 <p><strong>Note</strong> that for WSGI, the functions <code>deploy_as_cgi</code>    31 and <code>deploy_with_wsgiref</code> are provided instead, and the appropriate    32 function could be imported like this:</p>    33     34 <pre>from WebStack.Adapters.WSGI import deploy_as_cgi as deploy</pre>    35     36 <p>For some frameworks, an address may be specified:</p>    37     38 <pre>deploy(resource, address=(host_string, port_integer))    39 deploy(resource, authenticator, address=(host_string, port_integer))    40 </pre>    41     42 <p>And for some frameworks, the return value of the function is important:</p>    43     44 <pre>something = deploy(resource)    45 something, something_else = deploy(resource, authenticator)    46 </pre>    47     48 <p>Here is a summary of which    49 frameworks require address information and which produce important return values from the <code>deploy</code> function:</p>    50     51 <table border="1" cellpadding="5" cellspacing="0">    52   <tbody>    53     <tr>    54       <th>Framework</th>    55       <th>Address Information</th>    56       <th>Return Values</th>    57     </tr>    58     <tr>    59       <td>BaseHTTPRequestHandler</td>    60       <td>Supported</td>    61       <td></td>    62     </tr>    63     <tr>    64       <td>CGI</td>    65       <td>Ignored</td>    66       <td></td>    67     </tr>    68     <tr>    69       <td>Django</td>    70       <td>Ignored</td>    71       <td>Handler function</td>    72     </tr>    73     <tr>    74       <td>Java Servlet</td>    75       <td>Ignored</td>    76       <td>Servlet class</td>    77     </tr>    78     <tr>    79       <td>mod_python</td>    80       <td>Ignored</td>    81       <td>Handler function and authenticator function (a 2-tuple)</td>    82     </tr>    83     <tr>    84       <td>Twisted</td>    85       <td>Supported (<code>host_string</code> is ignored)</td>    86       <td></td>    87     </tr>    88     <tr>    89       <td>Webware (&gt; 0.8.1)</td>    90       <td>Ignored</td>    91       <td>URL context object</td>    92     </tr>    93     <tr>    94       <td>WSGI</td>    95       <td>Supported for <code>deploy_with_wsgiref</code><br />    96         Ignored for <code>deploy_as_cgi</code>    97       </td>    98       <td></td>    99     </tr>   100   </tbody>   101 </table>   102    103 <h3>Debugging Applications</h3>   104    105 <p>Sometimes, when resources throw unhandled exceptions when processing   106 requests, it is desirable to see the details of the exceptions either   107 in the Web browser or in the console from which the application was   108 started. For such purposes, a parameter to the <code>deploy</code>   109 function can be used:</p>   110 <pre>deploy(resource, handle_errors=0)</pre>   111 <p>The <code>handle_errors</code> parameter, if specified with a   112 false value, will not supress unhandled exceptions with an "internal   113 server error" response, but will instead provide the underlying server   114 environment's report of such exceptions.</p>   115    116 <h2><a name="table">Complicated Adapters - Providing Framework-Specific Objects</a></h2>   117    118 <p>The remaining frameworks (Java Servlet, mod_python, Webware and Zope) do   119 not support the <code>deploy</code> function due to the way applications are   120 typically integrated into the various server mechanisms. In these cases, it   121 may be worth investigating the examples provided and using their adapter code   122 as a template for the code for your own applications. Here is a summary which   123 indicates the server environments or frameworks which need most work:</p>   124    125 <table border="1" cellpadding="5" cellspacing="0">   126   <tbody>   127     <tr>   128       <th>Framework</th>   129       <th>Adapter Code Requirements</th>   130       <th>Deployment Process</th>   131     </tr>   132     <tr>   133       <td>BaseHTTPRequestHandler</td>   134       <td>Simple - see above</td>   135       <td>Run the adapter code directly</td>   136     </tr>   137     <tr>   138       <td>CGI</td>   139       <td>Simple - see above</td>   140       <td>Web server runs the adapter code</td>   141     </tr>   142     <tr><td>Django</td><td>Simple - see above</td><td>The adapter prepares the handler function</td></tr><tr>   143       <td>Java Servlet</td>   144       <td><span style="font-family: monospace;"></span><code></code>Simple - see above</td>   145       <td>The adapter prepares the servlet class</td>   146     </tr>   147     <tr>   148       <td>mod_python</td>   149       <td><span style="font-family: monospace;"></span><code></code>Simple - see above</td>   150       <td>The adapter prepares the handler function</td>   151     </tr>   152     <tr>   153       <td>Twisted</td>   154       <td>Simple - see above</td>   155       <td>Run the adapter code   156 directly</td>   157     </tr>   158     <tr>   159       <td>Webware</td>   160       <td>&lt;= 0.8.1: Must implement <code>InstallInWebKit</code> function<br />   161 &gt; 0.8.1: Simple - see above</td>   162       <td>Application must be deployed within WebKit</td>   163     </tr>   164     <tr>   165       <td>WSGI</td>   166       <td>Simple - see above</td>   167       <td>Either the adapter code is run directly (<code>deploy_with_wsgiref</code>)<br />   168         Or the Web server runs the adapter code (<code>deploy_as_cgi</code>)   169       </td>   170     </tr>   171     <tr>   172       <td>Zope</td>   173       <td>Must provide lots of Zope administative classes and functions</td>   174       <td>Application must be deployed within Zope</td>   175     </tr>   176   </tbody>   177 </table>   178 <p>See <a href="deploying-applications.html">"Deploying an   179 Application"</a>   180 for more details of the deployment process for each environment.</p>   181 </body></html>