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