WebStack

Annotated docs/writing-adapters.html

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