Copyright (c) 2004, Daniel J. Popowich.  All rights reserved.
	
Mod_python Servlets

============
0. Preamble
============

It is my intention to donate this handler to mod_python and by
extension, the Apache Foundation.  To this end, I have put together
the handler, along with API reference documentation and a tutorial in
the hopes that developers will use it and, finding it a simple, yet
powerfully productive tool, use it in their projects, offer feedback
and, eventually, promote its acceptance in the mainstream
distribution.


============
1. Overview
============

If mod_python's publisher handler is a functional view of the web, the
servlet handler is an object oriented view of the web.  It is inspired
by WebWare (http://webware.sourceforge.net).

I programmed with Webware for many projects.  I loved the object
oriented view of the web it promoted and found it to be a very
productive tool to quickly prototype web applications.  However, I
found it lacking in a number of ways: 1) it has its own server process
that needs to be started and managed, this is in addition to apache or
another web server; 2) its class hierarchy is rather deep: there are
five classes, inclusive, in the hierarchy between the base class and
the class that represents an HTML page (there are only two in
Mod_python Servlets); 3) even though a web server like apache manages
processes and/or threads, WebWare has its own extensive thread
management system which adds complexity to an overall web application;
4) WebWare promotes a comprehensive buy-in to their framework that,
personally, I found unwieldy.

In short, I found WebWare too "big" for my needs and started looking
for something more streamlined.  I couldn't find it.

Since I never intended on using a web server other than apache, it
made sense to give mod_python a closer look than I had before.  It was
immediately clear that process/thread management came "free" by using
an apache handler.  The publisher handler is clearly a powerful tool,
but I missed the OO view of WebWare.  I looked at mod_python handlers
that are available in the opensource community, but found most
required a buy-in to their framework and/or content management system.

At some point I realized it would be VERY easy to implement the best
features of WebWare as a mod_python handler without the bloat and
management burdens of other systems.  Best of all, it would be easy to
reuse many features of mod_python without re-inventing the wheel
(Session, Cookie, FieldStorage, etc.)


==================================================
1.5. Goals (which turns out to be a feature list)
==================================================

  1. Using mod_python, write a handler that operates in much the same
     way as WebWare: for any given request, create (or reuse) an
     instance of a well-defined base class to process the request,
     calling, in order, a set of methods on the instance.

  2. Offer tools to manage much of the tedium of web programming:
     processing query arguments and form variables.  Mod_python
     Servlets, building on mod_python.utils.FieldStorage, will
     automatically create instance variables for query arguments and
     form variables, allowing the developer to specify default values
     if they don't appear in the request as well as conversion methods
     to convert the strings to arbitrary python objects.  In addition,
     there is built-in support to accept python lists and dicts as
     form variables.  E.g., you can give HTML FORM elements names,
     such as, "foo[a]", "foo[b]", "foo[c]", ... and have returned to
     your servlet an instance variable named "foo", a dict, with keys
     "a", "b", "c", ... and their values being whatever was specified
     in the FORM.  Likewise, naming FORM elements with the same name
     (as with a CHECKBOX or SELECT with multiple set) Mod_python
     Servlets can return a python list.

  3. Allow for arbitrary methods of servlets to be called when forms
     are submitted.  With Mod_python Servlets you can name FORM BUTTON
     and/or INPUT SUBMIT/BUTTON elements with a special syntax such
     that when the form is submitted, a method the developer specifies
     will be called.  Security features are built-in to prevent *any*
     method to be called, just those the developer specifies.

  4. Remove the tedium of generating HTML documents.  I HATE writing
     HTML.  Mod_python Servlets generates well-defined HTML documents
     and through the setting of instance variables and/or overriding
     base methods, offer the developer much flexibility in customizing
     their HTML.  When used with a tool like HyperText or HTMLgen, you
     can write web applications without EVER having to write HTML.

  5. Support basic HTTP authentication.  Mod_python Servlets has tools
     to manage HTTP authentication including a simple method that
     accepts any mapping (that supports the standard get() method)
     where keys are usernames and values are passwords.
  
  6. Promote no framework that requires buy-in other than the servlets
     themselves.  Mod_python Servlets does not insist your content be
     in a certain format or that you use any other third-party
     packages.  This is not a religious movement!

  7. Make the management footprint small.  The handler function and
     one supporting class are less than 150 lines of code (after
     stripping doc strings).  The bulk of the functionality is in the
     class hierarchy that represents a servlet.
     
  8. Most importantly, separate processing from content.  I loathe
     PHP.  By extension, mod_python PSP.  If you, like me, have an
     inbred need to separate code from content AND you thrive in an OO
     view of the web, Mod_python Servlets are for you.


============
2. Contents
============

This package contains:

     README	  This file.

     servlet.py   The mod_python handler with supporting classes.

     Doc          API Reference in HTML and PDF.  This documentation is
		  generated using epydoc
		  (http://epydoc.sourceforge.net) which uses simple,
		  special markup in python doc strings, so the source
		  code is well documented as well.

     tutorial     This directory contains a tutorial on developing web
		  applications using servlets.  After installing
		  servlet.py and configuring apache, I strongly
		  recommend going through the tutorial, ideally, with
		  a copy of the API reference at your side.


============================
3. Prerequisites (software)
============================

Mod_python Servlets requires mod_python 3.1.x (which requires Apache
2.x) built with python 2.3.x.  This file does not cover how to install
these prerequisite packages and assumes they are already installed and
operating properly.


=============================
4. Prerequisites (knowledge)
=============================

Prerequisite knowledge to use Mod_python Servlets and to follow along
with the tutorial:

o Python is a must, including a solid understanding of python classes,
  methods, instance variables and class/instance hierarchies.

o Mod_python fundamentals.  You should minimally have played with the
  tutorial examples that come with mod_python.  You do NOT need to
  understand the publisher handler, but familiarity with the main
  request handler (PythonHandler) and the request object are assumed.
  
o A basic understanding of HTTP and HTML, particularly the
  fundamentals of form processing and understanding the difference
  between HTTP GET and POST methods.


================
5. Installation
================

Installation is simple, either:

 1. This package comes with a distutils setup.py file.  You can ignore
    warnings that __init__.py doesn't exist (this happens since you
    are installing a module in a package that already exists):

      python setup.py install

or

 2. Copy servlet.py to your mod_python directory.  For example,
    assuming mod_python python code is installed in
    /usr/local/lib/python2.3/site-packages/mod_python, then:

      cp servlet.py /usr/local/lib/python2.3/site-packages/mod_python


======================
6. Configuring Apache
======================

In your httpd.conf place the following in a Directory directive:

   <Directory /some/directory>
      SetHandler mod_python
      PythonHandler mod_python.servlet
      PythonDebug on
   </Directory>

So, to configure the tutorial, assuming /var/www/html is your
DocumentRoot:

  cp -a tutorial /var/www/html/mps_tutorial

and in your httpd.conf file:     

   <Directory /var/www/html/mps_tutorial>
      SetHandler mod_python
      PythonHandler mod_python.servlet
      PythonDebug on
   </Directory>

Restart apache.  Then, in a browser, go to

   http://yourserver/mps_tutorial


============   
7. Feedback
============   

I'm a reader of the mod_python discussion list: mod_python@modpython.org
