Apache::ASP
<% Web Applications with Apache & mod_perl %>
  INTRO
  INSTALL
  CONFIG
  SYNTAX
% EVENTS
  OBJECTS
  SSI
  SESSIONS
  XML/XSLT
  CGI
  PERLSCRIPT
  STYLE GUIDE
  FAQ
  TUNING
  CREDITS
  SUPPORT
  SITES USING
  TESTIMONIALS
  RESOURCES
  TODO
  CHANGES
  LICENSE

  EXAMPLES

Powered by Apache::ASP
Powered by ModPerl and Apache
Powered by Perl
EVENTS
Overview Script_OnParse
Script_OnStart & Script_OnEnd Application_OnStart
Session_OnStart Application_OnEnd
Session_OnEnd Server_OnStart ( pseudo-event )
Script_OnFlush mod_perl handlers

Overview

The ASP platform allows developers to create Web Applications.
In fulfillment of real software requirements, ASP allows 
event-triggered actions to be taken, which are defined in
a global.asa file.  The global.asa file resides in the 
Global directory, defined as a config option, and may
define the following actions:
	Action			Event
	------			------
        Script_OnStart *	Beginning of Script execution
        Script_OnEnd *		End of Script execution
        Script_OnFlush *	Before $Response being flushed to client.
        Script_OnParse *        Before script compilation
	Application_OnStart	Beginning of Application
	Application_OnEnd	End of Application
	Session_OnStart		Beginning of user Session.
	Session_OnEnd		End of user Session.

  * These are API extensions that are not portable, but were
    added because they are incredibly useful
These actions must be defined in the $Global/global.asa file as subroutines, for example:
  sub Session_OnStart {
      $Application->{$Session->SessionID()} = started;
  }
Sessions are easy to understand. When visiting a page in a web application, each user has one unique $Session. This session expires, after which the user will have a new $Session upon revisiting.
A web application starts when the user visits a page in that application, and has a new $Session created. Right before the first $Session is created, the $Application is created. When the last user $Session expires, that $Application expires also. For some web applications that are always busy, the Application_OnEnd event may never occur.

Script_OnStart & Script_OnEnd

The script events are used to run any code for all scripts
in an application defined by a global.asa.  Often, you would
like to run the same code for every script, which you would
otherwise have to add by hand, or add with a file include,
but with these events, just add your code to the global.asa,
and it will be run.  
There is one caveat. Code in Script_OnEnd is not guaranteed to be run when $Response->End() is called, since the program execution ends immediately at this event. To always run critical code, use the API extension:
	$Server->RegisterCleanup()

Session_OnStart

Triggered by the beginning of a user's session, Session_OnStart
gets run before the user's executing script, and if the same
session recently timed out, after the session's triggered Session_OnEnd.
The Session_OnStart is particularly useful for caching database data, and avoids having the caching handled by clumsy code inserted into each script being executed.

Session_OnEnd

Triggered by a user session ending, Session_OnEnd can be useful
for cleaning up and analyzing user data accumulated during a session.
Sessions end when the session timeout expires, and the StateManager performs session cleanup. The timing of the Session_OnEnd does not occur immediately after the session times out, but when the first script runs after the session expires, and the StateManager allows for that session to be cleaned up.
So on a busy site with default SessionTimeout (20 minutes) and StateManager (10 times) settings, the Session_OnEnd for a particular session should be run near 22 minutes past the last activity that Session saw. A site infrequently visited will only have the Session_OnEnd run when a subsequent visit occurs, and theoretically the last session of an application ever run will never have its Session_OnEnd run.
Thus I would not put anything mission-critical in the Session_OnEnd, just stuff that would be nice to run whenever it gets run.

Script_OnFlush

API extension. This event will be called prior to flushing
the $Response buffer to the web client.  At this time,
the $Response->{BinaryRef} buffer reference may be used to modify 
the buffered output at runtime to apply global changes to scripts 
output without having to modify all the scripts.
 sub Script_OnFlush {
   my $ref = $Response->{BinaryRef};
   $$ref =~ s/\s+/ /sg; # to strip extra white space
 }
Check out the ./site/eg/global.asa for an example of its use.

Script_OnParse

This event allows one to set up a source filter on the script text,
allowing one to change the script on the fly before the compilation
stage occurs.  The script text is available in the $Server->{ScriptRef}
scalar reference, and can be accessed like so:
 sub Script_OnParse {
   my $code = $Server->{ScriptRef}
   $$code .= " ADDED SOMETHING ";
 }

Application_OnStart

This event marks the beginning of an ASP application, and 
is run just before the Session_OnStart of the first Session
of an application.  This event is useful to load up
$Application with data that will be used in all user sessions.
	
	

Application_OnEnd

The end of the application is marked by this event, which
is run after the last user session has timed out for a 
given ASP application.
	
	

Server_OnStart ( pseudo-event )

Some might want something like a Server_OnStart event, where
some code gets runs when the web server starts.  In mod_perl,
this is easy to achieve outside of the scope of an ASP
application, by putting some initialization code into
a <Perl> section in the httpd.conf file.  Initializations
that you would like to be shared with the child httpds are
particularly useful, one such being the Apache::ASP->Loader() 
routine which you can read more about in the TUNING section -
Precompile Scripts subsection. It is could be called like:
  # httpd.conf
  <Perl>
     Apache::ASP->Loader($path, $pattern, %config)
  </Perl>
So a <Perl> section is your Server_OnStart routine!

mod_perl handlers

If one wants to extend one's environment with mod_perl
handlers, Apache::ASP does not stop this.  Basic
use of Apache::ASP in fact only involves the content
handler phase of mod_perl's PerlHandler, like
  SetHandler perl-script
  PerlModule Apache::ASP
  PerlHandler Apache::ASP 
But mod_perl allows for direct access to many more Apache event stages, for full list try "perldoc mod_perl" or buy the mod_perl Eagle book. Some commonly used ones are:
  PerlInitHandler
  PerlTransHandler
  PerlFixupHandler
  PerlHandler
  PerlLogHandler
  PerlCleanupHandler
For straight Apache::ASP programming, there are some equivalents, say Script_OnStart event instead of Init/Fixup stages, or $Server->RegisterCleanup() for Log/Cleanup stages, but you can do things in the mod_perl handlers that you cannot do in Apache::ASP, especially if you want to handle all files globally, and not just ASP scripts.
For many Apache::* modules for use with mod_perl, of which Apache::ASP is just one, check out
  http://perl.apache.org/products/apache-modules.html
To gain access to the ASP objects like $Session outside in a non-PerlHandler mod_perl handler, you may use this API:
  
  my $ASP = Apache::ASP->new($r); # $r is Apache->request object
as in this possible Authen handler:
  <Perl>
    use Apache::ASP;
    sub My::Auth::handler {
      my $r = shift;
      my $ASP = Apache::ASP->new($r) 
      my $Session = $ASP->Session;
    }
  </Perl>
Here are some examples of do-it-yourself mod_perl handler programming...
 === Forbid Bad HSlide User Agent ===

 # httpd.conf
 PerlAccessHandler My::Access
 <Perl>
   sub My::Access::handler {
     my $r = shift;
     if($r->headers_in->{'USER_AGENT'} =~ /HSlide/) {
	 403;
     } else {
	 200;
     }
   }
 </Perl>

 === Runtime Path Parsing ===
This example shows how one might take an arbitrary URL path /$path/$file.asp, and turn that into a runtime config for your site, so your scripts get executed always in your sites DocumentRoot.
 INPUT URL /SomeCategory/
 OUTPUT
  Script: index.asp
  $Server->Config('PATH') eq '/SomeCategory'

 INPUT URL /SomeCategory/index.asp
 OUTPUT
  Script: index.asp
  $Server->Config('PATH') eq '/SomeCategory'

 INPUT URI /index.asp
 OUTPUT
  Script: index.asp
  $Server->Config('PATH') eq ''

 # httpd.conf
 PerlTransHandler My::Init
 use lib qw( $custom_perllib );

 # $custom_perllib/My/Init.pm
 package My::Init;
 use strict;
 use Apache::Constants qw(:common);
 sub handler {
    my $r = shift;

    my $uri = $r->uri || '/';
    unless($uri =~ m|^(.*)(/([^/.]+\.[\w]+)?)$|i) {
	warn("can't parse uri $uri");
	return DECLINED;
    }
    $uri = $2;
    my $PATH = $1 || '';
    $r->dir_config('PATH', $PATH);

    if($uri eq '/') {
	$uri = '/index.asp';
    }

    $r->uri($uri);
    $r->filename($r->document_root.$uri);

    DECLINED;
 }

 1;