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 (> 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><= 0.8.1: Must implement <code>InstallInWebKit</code> function<br /> 161 > 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>
