Writing Adapters

Depending on how "simple" the adapter code is allowed to be for a given server environment (see the table for a summary), you will either need to write a small piece of code which initialises and deploys your application, or to produce a more complicated piece of code which satisfies some more demanding server requirements.

Simple Adapters - Using the deploy Function

When deploying an application, it is possible to use a one-shot deployment function for BaseHTTPRequestServer, CGI, Django, Java Servlet, mod_python, Twisted and WSGI configurations. The deploy function is called as follows:

deploy(resource)
deploy(resource, authenticator) # where authenticators are used

Note that for WSGI, the functions deploy_as_cgi and deploy_with_wsgiref are provided instead, and the appropriate function could be imported like this:

from WebStack.Adapters.WSGI import deploy_as_cgi as deploy

For some frameworks, an address may be specified:

deploy(resource, address=(host_string, port_integer))
deploy(resource, authenticator, address=(host_string, port_integer))

And for some frameworks, the return value of the function is important:

something = deploy(resource)
something, something_else = deploy(resource, authenticator)

Here is a summary of which frameworks require address information and which produce important return values from the deploy function:

Framework Address Information Return Values
BaseHTTPRequestHandler Supported
CGI Ignored
Django Ignored Handler function
Java Servlet Ignored Servlet class
mod_python Ignored Handler function and authenticator function (a 2-tuple)
Twisted Supported (host_string is ignored)
Webware (> 0.8.1) Ignored URL context object
WSGI Supported for deploy_with_wsgiref
Ignored for deploy_as_cgi

Debugging Applications

Sometimes, when resources throw unhandled exceptions when processing requests, it is desirable to see the details of the exceptions either in the Web browser or in the console from which the application was started. For such purposes, a parameter to the deploy function can be used:

deploy(resource, handle_errors=0)

The handle_errors parameter, if specified with a false value, will not supress unhandled exceptions with an "internal server error" response, but will instead provide the underlying server environment's report of such exceptions.

Complicated Adapters - Providing Framework-Specific Objects

The remaining frameworks (Java Servlet, mod_python, Webware and Zope) do not support the deploy function due to the way applications are typically integrated into the various server mechanisms. In these cases, it may be worth investigating the examples provided and using their adapter code as a template for the code for your own applications. Here is a summary which indicates the server environments or frameworks which need most work:

Framework Adapter Code Requirements Deployment Process
BaseHTTPRequestHandler Simple - see above Run the adapter code directly
CGI Simple - see above Web server runs the adapter code
DjangoSimple - see aboveThe adapter prepares the handler function
Java Servlet Simple - see above The adapter prepares the servlet class
mod_python Simple - see above The adapter prepares the handler function
Twisted Simple - see above Run the adapter code directly
Webware <= 0.8.1: Must implement InstallInWebKit function
> 0.8.1: Simple - see above
Application must be deployed within WebKit
WSGI Simple - see above Either the adapter code is run directly (deploy_with_wsgiref)
Or the Web server runs the adapter code (deploy_as_cgi)
Zope Must provide lots of Zope administative classes and functions Application must be deployed within Zope

See "Deploying an Application" for more details of the deployment process for each environment.