[Jifty-commit] r1996 - jifty/trunk/lib/Jifty/Manual

[jifty-commit at lists.jifty.org]

Author: wolfgang
Date: Sat Sep 30 14:28:54 2006
New Revision: 1996

Added:
   jifty/trunk/lib/Jifty/Manual/RequestHandling.pod

Log:
added a pod describing Jifty's request handling process

Added: jifty/trunk/lib/Jifty/Manual/RequestHandling.pod
==============================================================================
--- (empty file)
+++ jifty/trunk/lib/Jifty/Manual/RequestHandling.pod	Sat Sep 30 14:28:54 2006
@@ -0,0 +1,122 @@
+=head1 NAME
+
+Jifty::Manual::RequestHandling
+
+=head1 DESCRIPTION
+
+This document outlines some of Jifty's inside in order to understand
+what happens during the request processing phase.
+
+=head1 THE HANDLER
+
+As soon as a http request (whatever the method might be like GET,
+POST, PUT, ...) arrives at Jifty's border, the request is forwarded to
+a handler. By default, C<Jifty-E<gt>handler> points to a L<Jifty::Handler>
+object that is responsible for handling an incoming request. The
+handler receives a L<CGI> object on which it operates.
+
+=head2 The major steps in the request handling process are:
+
+=over
+
+=item refresh eventually modified modules in develop mode
+
+This allows a perl developer to change perl modules being used in a
+Jifty application without the need to restart the server which would
+otherwise become necessary. This is never done on a live environment.
+
+=item build a stash
+
+The stash is a storage area that can be reached by simply accessing
+C<Jifty-E<gt>handler-E<gt>stash-E<gt>{some_key}>. The stash will start fresh with
+every request and lives for the entire lifetime of a request. Using
+the stash, transporting data between otherwise unconnected modules
+will become possible.
+
+=item construct a request and response object
+
+Using the L<CGI> object, a L<Jifty::Request> object is constructed and
+its data is populated with the CGI's data. The request can be reached
+later using C<Jifty-E<gt>web-E<gt>request>. The request holds information
+about all actions involved, all page fragments, contains state
+variables and arguments (usually GET/POST parameters).
+
+Also, an empty L<Jifty::Response> object is constructed that contains
+one or more L<Jifty::Result> objects, each of which holds one
+L<Jifty::Action>'s result. The response object can be retrieved with C<Jifty-E<gt>web-E<gt>response>
+
+=item setup plugins
+
+For every registered L<Jifty::Plugin>, some kind of per-request
+initialization is performed allowing the actions provided by each
+plugin to run.
+
+=item handle static content
+
+If the requested URI points to some existing static content being
+housed in a C<static> directory, this content is handled.
+
+=item setup the session
+
+Based on a cookie that is sent with every http response, the current
+user is assigned a unique session. The session is stored in a
+L<Jifty::Web::Session> object and can be used with C<Jifty-E<gt>web-E<gt>session>.
+
+=item return from a continuation if requested
+
+If there is an open continuation on the stack (e.g. from a
+C<Jifty-E<gt>web-E<gt>tangent> link) and the return has been requested
+(e.g. by a C<Jifty-E<gt>web-E<gt>return> link), the return will execute at
+this stage.
+
+=item handle dynamic request unless already served
+
+First, the user is given a cookie containing the session-id. Then, the
+request is forwarded to C<Jifty-E<gt>handler-E<gt>dispatcher>, a
+L<Jifty::Dispatcher> object to handle the request. The dispatcher
+works through the following steps:
+
+=over 4
+
+=item setup
+
+In this stage, all rules in the dispatcher that are marked with the
+word C<before> are run.
+
+=item run the actions involved
+
+Every L<Jifty::Action> that is registered in a form or involved in a
+link or button is run in this stage.
+
+=item run dispatching rules
+
+This stage is responsible for working through all rules marked by
+words like C<under>, C<on>, C<when> and so on. This is a point where
+based on the URI or parameters the template to get displayed may still
+be modified, data retrieved, additional actions run or the template's
+parameters get adjusted.
+
+=item show the page
+
+Here, the template displaying the page is run.
+
+=item cleanup
+
+This final stage of the dispatcher will run all rules marked with the
+word C<after>.
+
+=back
+
+=item cleanup several things
+
+Finally, the eventually modified session-record is flushed and some
+internally allocated structures deallocated.
+
+=back
+
+=head1 SEE ALSO
+
+L<Jifty::Handler>, L<Jifty::Dispatcher>, L<Jifty::Request>, L<Jifty::Response>
+
+=cut
+