2.1 --- a/docs/deploying.html Sat Oct 13 23:43:05 2007 +0000
2.2 +++ b/docs/deploying.html Sat Oct 13 23:43:21 2007 +0000
2.3 @@ -1,8 +1,10 @@
2.4 <?xml version="1.0" encoding="iso-8859-1"?>
2.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.6 -<html xmlns="http://www.w3.org/1999/xhtml"><head>
2.7 +<html xmlns="http://www.w3.org/1999/xhtml">
2.8 +<head>
2.9 <title>Deploying a WebStack Application</title>
2.10 - <link href="styles.css" rel="stylesheet" type="text/css" /></head>
2.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
2.12 +</head>
2.13 <body>
2.14 <h1>Deploying a WebStack Application</h1>
2.15 <p>The process of deploying a WebStack application should be as
2.16 @@ -11,6 +13,7 @@
2.17 or using the deployment processes of the server environment or
2.18 framework in
2.19 which the application will be living.</p>
2.20 +
2.21 <h2>The Adapter Code</h2>
2.22 <p>What adapter or "glue" code does is to set up your applications main
2.23 resource object and to hook that object up with the underlying server
2.24 @@ -22,7 +25,9 @@
2.25 Python standard library, you can just run this code, making sure that
2.26 the <code>MyApplication</code> module or package is on your <code>PYTHONPATH</code>.
2.27 Then, you can visit <code>http://localhost:8080</code> in your
2.28 -browser and see the result.</p><h3>Root Resources and Site Maps</h3><p>The
2.29 +browser and see the result.</p>
2.30 +
2.31 +<h3>Root Resources and Site Maps</h3><p>The
2.32 above example suggested the direct deployment of a specific resource,
2.33 and this was quickly achieved by instantiating the resource within the
2.34 call to the <code>deploy</code> function. However, it may be more
2.35 @@ -33,6 +38,7 @@
2.36 this appears to be trading one name for another, the intent is really
2.37 to provide a layer of abstraction which hides the details of resource
2.38 classes from the deployment code, even if the <code>get_site_map</code> function is only as simple as the following:</p><pre>def get_site_map():<br /> return MyResource()</pre><p>Of course, this function may be made more complicated as the need arises.</p>
2.39 +
2.40 <h3>More Demanding Adapter Code</h3>
2.41 <p>Unfortunately, not all server environments can be connected up with
2.42 applications this easily. Some environments require special classes and
2.43 @@ -40,6 +46,7 @@
2.44 applications to
2.45 be properly integrated into those environments. A summary of the
2.46 requirements of each environment can be found in <a href="writing-adapters.html">"Writing Adapters"</a>.</p>
2.47 +
2.48 <h2>The Deployment Process</h2>
2.49 <ul>
2.50 <li><a href="writing-adapters.html">Writing Adapters</a></li>
3.1 --- a/docs/writing-adapters.html Sat Oct 13 23:43:05 2007 +0000
3.2 +++ b/docs/writing-adapters.html Sat Oct 13 23:43:21 2007 +0000
3.3 @@ -5,6 +5,7 @@
3.4 <link href="styles.css" rel="stylesheet" type="text/css" /></head>
3.5 <body>
3.6 <h1>Writing Adapters</h1>
3.7 +
3.8 <p>Depending on how "simple" the
3.9 adapter code is allowed to be for a
3.10 given
3.11 @@ -14,46 +15,93 @@
3.12 initialises and deploys your application, or to produce a more
3.13 complicated
3.14 piece of code which satisfies some more demanding server requirements.</p>
3.15 -<h2>Simple Adapters - Using the
3.16 -deploy Function</h2>
3.17 -<p>When deploying an application,
3.18 -it is possible to use a one-shot
3.19 -deployment
3.20 -function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The
3.21 -<code>deploy</code>
3.22 -function is called as follows:</p>
3.23 -<pre>deploy(resource)<br />deploy(resource, authenticator) # where authenticators are used</pre>
3.24 -<p>For some frameworks, an address
3.25 -may be specified:</p>
3.26 -<pre>deploy(resource, address=(host_string, port_integer))<br />deploy(resource, authenticator, address=(host_string, port_integer))</pre>
3.27 -<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
3.28 +
3.29 +<h2>Simple Adapters - Using the deploy Function</h2>
3.30 +
3.31 +<p>When deploying an application, it is possible to use a one-shot deployment
3.32 +function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python,
3.33 +Twisted and WSGI configurations. The <code>deploy</code> function is called as
3.34 +follows:</p>
3.35 +
3.36 +<pre>deploy(resource)
3.37 +deploy(resource, authenticator) # where authenticators are used
3.38 +</pre>
3.39 +
3.40 +<p><strong>Note</strong> that for WSGI, the functions <code>deploy_as_cgi</code>
3.41 +and <code>deploy_with_wsgiref</code> are provided instead, and the appropriate
3.42 +function could be imported like this:</p>
3.43 +
3.44 +<pre>from WebStack.Adapters.WSGI import deploy_as_cgi as deploy</pre>
3.45 +
3.46 +<p>For some frameworks, an address may be specified:</p>
3.47 +
3.48 +<pre>deploy(resource, address=(host_string, port_integer))
3.49 +deploy(resource, authenticator, address=(host_string, port_integer))
3.50 +</pre>
3.51 +
3.52 +<p>And for some frameworks, the return value of the function is important:</p>
3.53 +
3.54 +<pre>something = deploy(resource)
3.55 +something, something_else = deploy(resource, authenticator)
3.56 +</pre>
3.57 +
3.58 +<p>Here is a summary of which
3.59 frameworks require address information and which produce important return values from the <code>deploy</code> function:</p>
3.60 +
3.61 <table border="1" cellpadding="5" cellspacing="0">
3.62 <tbody>
3.63 <tr>
3.64 <th>Framework</th>
3.65 - <th>Address Information</th><th>Return Values</th>
3.66 + <th>Address Information</th>
3.67 + <th>Return Values</th>
3.68 </tr>
3.69 <tr>
3.70 <td>BaseHTTPRequestHandler</td>
3.71 - <td>Supported</td><td align="undefined" valign="undefined"></td>
3.72 + <td>Supported</td>
3.73 + <td></td>
3.74 </tr>
3.75 <tr>
3.76 <td>CGI</td>
3.77 - <td>Ignored</td><td align="undefined" valign="undefined"></td>
3.78 + <td>Ignored</td>
3.79 + <td></td>
3.80 + </tr>
3.81 + <tr>
3.82 + <td>Django</td>
3.83 + <td>Ignored</td>
3.84 + <td>Handler function</td>
3.85 </tr>
3.86 - <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>
3.87 + <tr>
3.88 + <td>Java Servlet</td>
3.89 + <td>Ignored</td>
3.90 + <td>Servlet class</td>
3.91 + </tr>
3.92 + <tr>
3.93 + <td>mod_python</td>
3.94 + <td>Ignored</td>
3.95 + <td>Handler function and authenticator function (a 2-tuple)</td>
3.96 + </tr>
3.97 + <tr>
3.98 <td>Twisted</td>
3.99 - <td>Supported (<code>host_string</code>
3.100 -is ignored)</td><td align="undefined" valign="undefined"></td>
3.101 + <td>Supported (<code>host_string</code> is ignored)</td>
3.102 + <td></td>
3.103 </tr>
3.104 - <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>
3.105 + <tr>
3.106 + <td>Webware (> 0.8.1)</td>
3.107 + <td>Ignored</td>
3.108 + <td>URL context object</td>
3.109 + </tr>
3.110 + <tr>
3.111 <td>WSGI</td>
3.112 - <td>Ignored</td><td align="undefined" valign="undefined"></td>
3.113 + <td>Supported for <code>deploy_with_wsgiref</code><br />
3.114 + Ignored for <code>deploy_as_cgi</code>
3.115 + </td>
3.116 + <td></td>
3.117 </tr>
3.118 </tbody>
3.119 </table>
3.120 +
3.121 <h3>Debugging Applications</h3>
3.122 +
3.123 <p>Sometimes, when resources throw unhandled exceptions when processing
3.124 requests, it is desirable to see the details of the exceptions either
3.125 in the Web browser or in the console from which the application was
3.126 @@ -64,23 +112,16 @@
3.127 false value, will not supress unhandled exceptions with an "internal
3.128 server error" response, but will instead provide the underlying server
3.129 environment's report of such exceptions.</p>
3.130 -<h2><a name="table">Complicated Adapters -
3.131 -Providing
3.132 -Framework-Specific Objects</a></h2>
3.133 -<p>The remaining frameworks (Java
3.134 -Servlet,
3.135 -mod_python, Webware and
3.136 -Zope) do
3.137 -not support the <code>deploy</code>
3.138 -function due to the way
3.139 -applications are
3.140 -typically integrated into the various server mechanisms. In these
3.141 -cases, it
3.142 -may be worth investigating the examples provided and using their
3.143 -adapter code
3.144 -as a template for the code for your own applications. Here is a summary
3.145 -which
3.146 +
3.147 +<h2><a name="table">Complicated Adapters - Providing Framework-Specific Objects</a></h2>
3.148 +
3.149 +<p>The remaining frameworks (Java Servlet, mod_python, Webware and Zope) do
3.150 +not support the <code>deploy</code> function due to the way applications are
3.151 +typically integrated into the various server mechanisms. In these cases, it
3.152 +may be worth investigating the examples provided and using their adapter code
3.153 +as a template for the code for your own applications. Here is a summary which
3.154 indicates the server environments or frameworks which need most work:</p>
3.155 +
3.156 <table border="1" cellpadding="5" cellspacing="0">
3.157 <tbody>
3.158 <tr>
3.159 @@ -91,16 +132,14 @@
3.160 <tr>
3.161 <td>BaseHTTPRequestHandler</td>
3.162 <td>Simple - see above</td>
3.163 - <td>Run the adapter code
3.164 -directly</td>
3.165 + <td>Run the adapter code directly</td>
3.166 </tr>
3.167 <tr>
3.168 <td>CGI</td>
3.169 <td>Simple - see above</td>
3.170 - <td>Web server runs the
3.171 -adapter code</td>
3.172 + <td>Web server runs the adapter code</td>
3.173 </tr>
3.174 - <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>
3.175 + <tr><td>Django</td><td>Simple - see above</td><td>The adapter prepares the handler function</td></tr><tr>
3.176 <td>Java Servlet</td>
3.177 <td><span style="font-family: monospace;"></span><code></code>Simple - see above</td>
3.178 <td>The adapter prepares the servlet class</td>
3.179 @@ -118,25 +157,21 @@
3.180 </tr>
3.181 <tr>
3.182 <td>Webware</td>
3.183 - <td><= 0.8.1: Must
3.184 -implement <code>InstallInWebKit</code>
3.185 -function<br />
3.186 + <td><= 0.8.1: Must implement <code>InstallInWebKit</code> function<br />
3.187 > 0.8.1: Simple - see above</td>
3.188 - <td>Application must be
3.189 -deployed within WebKit</td>
3.190 + <td>Application must be deployed within WebKit</td>
3.191 </tr>
3.192 <tr>
3.193 <td>WSGI</td>
3.194 <td>Simple - see above</td>
3.195 - <td>Web server runs the
3.196 -adapter code</td>
3.197 + <td>Either the adapter code is run directly (<code>deploy_with_wsgiref</code>)<br />
3.198 + Or the Web server runs the adapter code (<code>deploy_as_cgi</code>)
3.199 + </td>
3.200 </tr>
3.201 <tr>
3.202 <td>Zope</td>
3.203 - <td>Must provide lots of
3.204 -Zope administative classes and functions</td>
3.205 - <td>Application must be
3.206 -deployed within Zope</td>
3.207 + <td>Must provide lots of Zope administative classes and functions</td>
3.208 + <td>Application must be deployed within Zope</td>
3.209 </tr>
3.210 </tbody>
3.211 </table>