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 <p>Depending on how "simple" the 9 adapter code is allowed to be for a 10 given 11 server environment (see the <a href="#table">table</a> 12 for a 13 summary), you will either need to write a small piece of code which 14 initialises and deploys your application, or to produce a more 15 complicated 16 piece of code which satisfies some more demanding server requirements.</p> 17 <h2>Simple Adapters - Using the 18 deploy Function</h2> 19 <p>When deploying an application, 20 it is possible to use a one-shot 21 deployment 22 function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The 23 <code>deploy</code> 24 function is called as follows:</p> 25 <pre>deploy(resource)<br />deploy(resource, authenticator) # where authenticators are used</pre> 26 <p>For some frameworks, an address 27 may be specified:</p> 28 <pre>deploy(resource, address=(host_string, port_integer))<br />deploy(resource, authenticator, address=(host_string, port_integer))</pre> 29 <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 30 frameworks require address information and which produce important return values from the <code>deploy</code> function:</p> 31 <table border="1" cellpadding="5" cellspacing="0"> 32 <tbody> 33 <tr> 34 <th>Framework</th> 35 <th>Address Information</th><th>Return Values</th> 36 </tr> 37 <tr> 38 <td>BaseHTTPRequestHandler</td> 39 <td>Supported</td><td align="undefined" valign="undefined"></td> 40 </tr> 41 <tr> 42 <td>CGI</td> 43 <td>Ignored</td><td align="undefined" valign="undefined"></td> 44 </tr> 45 <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> 46 <td>Twisted</td> 47 <td>Supported (<code>host_string</code> 48 is ignored)</td><td align="undefined" valign="undefined"></td> 49 </tr> 50 <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> 51 <td>WSGI</td> 52 <td>Ignored</td><td align="undefined" valign="undefined"></td> 53 </tr> 54 </tbody> 55 </table> 56 <h3>Debugging Applications</h3> 57 <p>Sometimes, when resources throw unhandled exceptions when processing 58 requests, it is desirable to see the details of the exceptions either 59 in the Web browser or in the console from which the application was 60 started. For such purposes, a parameter to the <code>deploy</code> 61 function can be used:</p> 62 <pre>deploy(resource, handle_errors=0)</pre> 63 <p>The <code>handle_errors</code> parameter, if specified with a 64 false value, will not supress unhandled exceptions with an "internal 65 server error" response, but will instead provide the underlying server 66 environment's report of such exceptions.</p> 67 <h2><a name="table">Complicated Adapters - 68 Providing 69 Framework-Specific Objects</a></h2> 70 <p>The remaining frameworks (Java 71 Servlet, 72 mod_python, Webware and 73 Zope) do 74 not support the <code>deploy</code> 75 function due to the way 76 applications are 77 typically integrated into the various server mechanisms. In these 78 cases, it 79 may be worth investigating the examples provided and using their 80 adapter code 81 as a template for the code for your own applications. Here is a summary 82 which 83 indicates the server environments or frameworks which need most work:</p> 84 <table border="1" cellpadding="5" cellspacing="0"> 85 <tbody> 86 <tr> 87 <th>Framework</th> 88 <th>Adapter Code Requirements</th> 89 <th>Deployment Process</th> 90 </tr> 91 <tr> 92 <td>BaseHTTPRequestHandler</td> 93 <td>Simple - see above</td> 94 <td>Run the adapter code 95 directly</td> 96 </tr> 97 <tr> 98 <td>CGI</td> 99 <td>Simple - see above</td> 100 <td>Web server runs the 101 adapter code</td> 102 </tr> 103 <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> 104 <td>Java Servlet</td> 105 <td><span style="font-family: monospace;"></span><code></code>Simple - see above</td> 106 <td>The adapter prepares the servlet class</td> 107 </tr> 108 <tr> 109 <td>mod_python</td> 110 <td><span style="font-family: monospace;"></span><code></code>Simple - see above</td> 111 <td>The adapter prepares the handler function</td> 112 </tr> 113 <tr> 114 <td>Twisted</td> 115 <td>Simple - see above</td> 116 <td>Run the adapter code 117 directly</td> 118 </tr> 119 <tr> 120 <td>Webware</td> 121 <td><= 0.8.1: Must 122 implement <code>InstallInWebKit</code> 123 function<br /> 124 > 0.8.1: Simple - see above</td> 125 <td>Application must be 126 deployed within WebKit</td> 127 </tr> 128 <tr> 129 <td>WSGI</td> 130 <td>Simple - see above</td> 131 <td>Web server runs the 132 adapter code</td> 133 </tr> 134 <tr> 135 <td>Zope</td> 136 <td>Must provide lots of 137 Zope administative classes and functions</td> 138 <td>Application must be 139 deployed within Zope</td> 140 </tr> 141 </tbody> 142 </table> 143 <p>See <a href="deploying-applications.html">"Deploying an 144 Application"</a> 145 for more details of the deployment process for each environment.</p> 146 </body></html>