view release on metacpan or  search on metacpan

lib/Apache/HeavyCGI.pm  view on Meta::CPAN

that the model for stacking handlers often is too primitive. The model
supposes that the final form of a document can be found by running
several passes over a single entity, each pass refining the entity,
manipulating some headers, maybe even passing some notes to the next
handler, and in the most advanced form passing pnotes between
handlers. A lot of Web pages may fit into that model, even complex
ones, but it doesn't scale well for pages that result out of a
structure that's more complicated than adjacent items. The more
complexity you add to a page, the more overhead is generated by the
model, because for every handler you push onto the stack, the whole
document has to be parsed and recomposed again and headers have to be
re-examined and possibly changed.

=head2 Why not subclass Apache

Inheritance provokes namespace conflicts. Besides this, I see little
reason why one should favor inheritance over a B<using> relationship.
The current implementation of Apache::HeavyCGI is very closely coupled
with the Apache class anyway, so we could do inheritance too. No big
deal I suppose. The downside of the current way of doing it is that we
have to write

    my $r = $obj->{R};

very often, but that's about it. The upside is, that we know which
manpage to read for the different methods provided by C<$obj->{R}>,
C<$obj->{CGI}>, and C<$obj> itself.

=head2 Composing applications

Apache::HeavyCGI takes an approach that is more ambitious for handling
complex tasks. The underlying model for the production of a document
is that of a puzzle. An HTML (or XML or SGML or whatever) page is
regarded as a sequence of static and dynamic parts, each of which has
some influence on the final output. Typically, in today's Webpages,
the dynamic parts are filled into table cells, i.e. contents between
some C<< <TD></TD> >> tokens. But this is not necessarily so. The
static parts in between typically are some HTML markup, but this also
isn't forced by the model. The model simply expects a sequence of
static and dynamic parts. Static and dynamic parts can appear in
random order. In the extreme case of a picture you would only have one
part, either static or dynamic. HeavyCGI could handle this, but I
don't see a particular advantage of HeavyCGI over a simple single
handler.

In addition to the task of generating the contents of the page, there
is the other task of producing correct headers. Header composition is
an often neglected task in the CGI world. Because pages are generated
dynamically, people believe that pages without a Last-Modified header
are fine, and that an If-Modified-Since header in the browser's
request can go by unnoticed. This laissez-faire principle gets in the
way when you try to establish a server that is entirely driven by
dynamic components and the number of hits is significant.

=head2 Header Composition, Parameter Processing, and Content Creation

The three big tasks a CGI script has to master are Headers, Parameters
and the Content. In general one can say, content creation SHOULD not
start before all parameters are processed. In complex scenarios you
MUST expect that the whole layout may depend on one parameter.
Additionally we can say that some header related data SHOULD be
processed very early because they might result in a shortcut that
saves us a lot of processing.

Consequently, Apache::HeavyCGI divides the tasks to be done for a
request into four phases and distributes the four phases among an
arbitrary number of modules. Which modules are participating in the
creation of a page is the design decision of the programmer.

The perl model that maps (at least IMHO) ideally to this task
description is an object oriented approach that identifies a couple of
phases by method names and a couple of components by class names. To
create an application with Apache::HeavyCGI, the programmer specifies
the names of all classes that are involved. All classes are singleton
classes, i.e. they have no identity of their own but can be used to do
something useful by working on an object that is passed to them.
Singletons have an @ISA relation to L<Class::Singleton> which can be
found on CPAN. As such, the classes can only have a single instance
which can be found by calling the C<< CLASS->instance >> method. We'll
call these objects after the mod_perl convention I<handlers>.

Every request maps to exactly one Apache::HeavyCGI object. The
programmer uses the methods of this object by subclassing. The
HeavyCGI constructor creates objects of the AVHV type (pseudo-hashes).

*** Note: after 0.0133 this was changed to an ordinary hash. ***

If the inheriting class needs its own constructor, this needs to be an
AVHV compatible constructor. A description of AVHV can be found in
L<fields>.

*** Note: after 0.0133 this was changed to be an ordinary hash. ***

An Apache::HeavyCGI object usually is constructed with the
C<new> method and after that the programmer calls the C<dispatch>
method on this object. HeavyCGI will then perform various
initializations and then ask all nominated handlers in turn to perform
the I<header> method and in a second round to perform the I<parameter>
method. In most cases it will be the case that the availability of a
method can be determined at compile time of the handler. If this is
true, it is possible to create an execution plan at compile time that
determines the sequence of calls such that no runtime is lost to check
method availability. Such an execution plan can be created with the
L<Apache::HeavyCGI::ExePlan> module. All of the called methods will
get the HeavyCGI request object passed as the second parameter.

There are no fixed rules as to what has to happen within the C<header>
and C<parameter> method. As a rule of thumb it is recommended to
determine and set the object attributes LAST_MODIFIED and EXPIRES (see
below) within the header() method. It is also recommended to inject
the L<Apache::HeavyCGI::IfModified> module as the last header handler,
so that the application can abort early with an Not Modified header. I
would recommend that in the header phase you do as little as possible
parameter processing except for those parameters that are related to
the last modification date of the generated page.

=head2 Terminating the handler calls or triggering errors.

Sometimes you want to stop calling the handlers, because you think
that processing the request is already done. In that case you can do a