"""Document the history and influences of Aquarium.
In The Beginning
================
In the beginning, there was FreeTrade_. FreeTrade is an ecommerce package
which was written in PHP_ at ClearInk_ by Leon Atkinson (the project lead) and
myself. The "soul" of FreeTrade was a methodology called FreeEnergy_.
FreeEnergy stated:
* Web applications should be broken down to (primarily) a set of screen
modules, layout modules, navigation modules, action modules, and database
modules (although these were added later).
* All state changes should be constrained to action modules.
* There should be only one entry point to the application so that screens
don't have to explicitly do server-side includes to get their headers and
footers. (Implicitly, this requires a dynamic include mechanism, so not
every Web technology is appropriate for implementing FreeEnergy.)
FreeTrade did very well and is in active development and usage today. Inspired
by the success of FreeTrade, FreeEnergy was ported to other languages:
* Turbine_ is a Java implementation that became an Apache sponsored project.
* JPublish_ is another Java implementation that is fairly popular.
* There were also implementations in Cold Fusion, Perl's Mason_, and other
environments.
Aquarium, written in Python, was the third implementation of FreeEnergy.
Originally, the Cheetah templating engine did not exist, so the author made due
with a far less advanced string interpolation function called evalstr.
Furthermore, Aquarium sat relatively idle for two years while the author
pursued non-Web-related programming activities. However, thanks to Cheetah,
Aquarium's development has been invigorated.
The Action War
==============
In PHP (which FreeTrade is written in) it is very natural for a screen module
to call a database module in order to get data to be displayed. Hence, the
screen "pulls" data. However, this implies that the screen is not entirely
"stupid", an idea which frustrates many Java programmers. Java programmers
state that views should never contain application logic. FreeTrade programmers
instead require the much smaller requirement that screens should not invoke a
change in state. Hence, in FreeTrade, changes in state are constrained to
action modules. An URL such as::
http://foo.com/index.php?screen=show_basket&action=ADD_ITEM&item=1
says "add item number 1 to my basket, and if that goes okay, show me my
basket". The ``ADD_ITEM`` action module is executed first, and if it decides
that it's okay, it'll show you the ``show_basket`` screen.
In JPublish action modules have a much broader usage. Because of this broader
usage, which action module gets executed when is configured using an XML file,
not requested via the URL. The action modules are implemented using any
language supported by Jakarta's `Bean Scripting Framework`_. As is typical of
the "Java" approach, all application logic is constrained to action modules,
and screens are "dumb". Furthermore, almost every screen involves the use of
an action module to prepare data for it, and action modules need not result in
a change in state. Apache's Struts_ shares JPublish's approach to actions
modules as does Clearsilver_ (although Clearsilver doesn't call them
action modules). I refer to this approach as the "Java" approach. I call such
action modules "Struts actions". The action module is said to "push" the data
into the screen. In slightly different ways for each of the various
technologies, this maps cleanly onto the model view controller paradigm.
For many years, Aquarium used the FreeTrade approach to actions. Having been a
PHP programmer, this was very natural for me. However, when Aquarium switched
to Cheetah, I found out that doing any real work in a template was painful.
Furthermore, the other projects lended credibility to the "Java" approach.
Hence, Aquarium today uses "Struts actions". In fact, there is no longer a
separate action module type; actions have been relegated to separate methods in
controllers (see aquarium.screen.Controller.executeAction_). Some screens act
as controllers and some act as views (see aquarium.screen.ScreenAPI_). Hence,
the distinction is more implicit than explicit, and it is not enforced by the
directory hierarchy. (This is because I wanted the controllers and views to be
side by side, and I also wanted a simple view to be able to exist without a
null controller.)
Less Holy Wars
==============
FreeTrade's approach to layouts was rather one dimensional. One layout could
not inherit from another layout. In the "bad old days" Aquarium's approach to
layouts involved another type of module called a "page" module. Hence, there
were two levels (layouts extended page modules), but this is still less
attractive than an arbitrary number of levels. Fortunately, those days are
gone. Perl's Mason has a rather rich approach to layouts.
aquarium.util.InternalLibrary.inverseExtend_ is an implementation of this
technique, and it is an integral part of Aquarium today.
The various implementations of FreeEnergy have various approaches to database
usage. Turbine (like Mason) has a library where you can create SQL statements
dynamically using an API that hides the various flavors of SQL. In FreeTrade
the SQL statements were originally scattered all over the place, but eventually
they were constrained to database modules where they were accessible via an
application-specific, but RDBMS agnostic, API. Proclaiming the futility of
trying to "abstract" SQL, Aquarium chooses the FreeTrade approach.
Furthermore, Aquarium provides an autoloading_ feature that makes working with
database modules even more syntactically convenient.
FreeTrade has a principal that states that a bare piece of HTML must be
suitable for use as a screen module. I.e. it requires zero overhead. Hence,
supplemental data such as the title, the desired layout, meta tags, etc. are
stored in a large, shared file named ``ScreenInfo``. In a similar vein, Struts
has a single XML file that maps URL's to JSP's and controls all flow in
general. JPublish has a single XML file that states which action should be
executed when. In general, Aquarium shuns such approaches. Whenever possible,
the data associated with a screen belongs with that screen. This is
appropriate since screens are classes, but it sacrifices the zero overhead
requirement (at the very least, a template must have at least two lines).
.. _FreeTrade: http://share.whichever.com/index.php?SCREEN=freetrade
.. _PHP: http://www.php.net
.. _ClearInk: http://clearink.com
.. _FreeEnergy: http://www.zend.com/zend/art/free-energy.php
.. _Turbine: http://jakarta.apache.org/turbine
.. _JPublish: http://www.jpublish.org
.. _Mason: http://masonhq.com
.. _Bean Scripting Framework: http://jakarta.apache.org/bsf
.. _Struts: http://jakarta.apache.org/struts
.. _Clearsilver: http://www.clearsilver.net
.. _aquarium.screen.Controller.executeAction:
aquarium.screen.Controller.Controller-class.html#executeAction
.. _aquarium.screen.ScreenAPI: aquarium.screen.ScreenAPI-module.html
.. _aquarium.util.InternalLibrary.inverseExtend:
aquarium.util.InternalLibrary.InternalLibrary-class.html#inverseExtend
.. _autoloading:
aquarium.database.DatabaseAssistant.DatabaseAssistant-class.html
"""
__docformat__ = "restructuredtext"
# Created: Tue Mar 30 14:52:01 PST 2004
# Author: Shannon -jj Behrens
# Email: jjinux@users.sourceforge.net
#
# Copyright (c) Shannon -jj Behrens. All rights reserved.
|