Apache-ASP
view release on metacpan or search on metacpan
of Data::Dumper and MLDBM, which are the modules used to write the
state files.
=head2 Sessions
=item How can I use $Session to store complex data structures.
Very carefully. Please read the $Session documentation in
the OBJECTS section. You can store very complex objects
in $Session, but you have to understand the limits, and
the syntax that must be used to make this happen.
In particular, stay away from statements that that have
more than one level of indirection on the left side of
an assignment like:
BAD: $Session->{complex}{object} = $data;
=item How can I keep search engine spiders from killing the session manager?
If you want to disallow session creation for certain non web
browser user agents, like search engine spiders, you can use a mod_perl
PerlInitHandler like this to set configuration variables at runtime:
# put the following code into httpd.conf and stop/start apache server
PerlInitHandler My::InitHandler
<Perl>
package My::InitHandler;
use Apache;
sub handler {
my $r = shift; # get the Apache request object
# if not a Mozilla User Agent, then disable sessions explicitly
unless($r->headers_in('User-Agent') =~ /^Mozilla/) {
$r->dir_config('AllowSessionState', 'Off');
}
return 200; # return OK mod_perl status code
}
1;
</Perl>
This will configure your environment before Apache::ASP executes
and sees the configuration settings. You can use the mod_perl
API in this way to configure Apache::ASP at runtime.
Note that the Session Manager is very robust on its own, and denial
of service attacks of the types that spiders and other web bots
normally execute are not likely to affect the Session Manager significantly.
=item How can I use $Session to store a $dbh database handle ?
You cannot use $Session to store a $dbh handle. This can
be awkward for those coming from the IIS/NT world, where
you could store just about anything in $Session, but this
boils down to a difference between threads vs. processes.
Database handles often have per process file handles open,
which cannot be shared between requests, so though you
have stored the $dbh data in $Session, all the other
initializations are not relevant in another httpd process.
All is not lost! Apache::DBI can be used to cache
database connections on a per process basis, and will
work for most cases.
=head2 Development
=item VBScript or JScript supported?
Only Perl scripting is supported with this module.
=item How is database connectivity handled?
Database connectivity is handled through perl's DBI & DBD interfaces.
In the UNIX world, it seems most databases have cross platform support in perl.
You can find the book on DBI programming at http://www.oreilly.com/catalog/perldbi/
DBD::ODBC is often your ticket on Win32. On UNIX, commercial vendors
like OpenLink Software (http://www.openlinksw.com/) provide the nuts and
bolts for ODBC.
Database connections can be cached per process with Apache::DBI.
=item What is the best way to debug an ASP application ?
There are lots of perl-ish tricks to make your life developing
and debugging an ASP application easier. For starters,
you will find some helpful hints by reading the
$Response->Debug() API extension, and the Debug
configuration directive.
=item How are file uploads handled?
Please see the CGI section. File uploads are implemented
through CGI.pm which is loaded at runtime only for this purpose.
This is the only time that CGI.pm will be loaded by Apache::ASP,
which implements all other cgi-ish functionality natively. The
rationale for not implementing file uploads natively is that
the extra 100K in memory for CGI.pm shouldn't be a big deal if you
are working with bulky file uploads.
=item How do I access the ASP Objects in general?
All the ASP objects can be referenced through the main package with
the following notation:
$main::Response->Write("html output");
This notation can be used from anywhere in perl, including routines
registered with $Server->RegisterCleanup().
You use the normal notation in your scripts, includes, and global.asa:
$Response->Write("html output");
=head2 Online Resources
For more tips & tricks on tuning Apache and mod_perl, please see the tuning
documents at:
Stas Bekman's mod_perl guide
http://perl.apache.org/guide/
Written in late 1999 this article provides an early look at
how to tune your Apache::ASP web site. It has since been
updated to remain current with Apache::ASP v2.29+
Apache::ASP Site Tuning
http://www.apache-asp.org/articles/perlmonth3_tune.html
=head2 Tuning & Benchmarking
When performance tuning, it is important to have a tool to
measure the impact of your tuning change by change.
The program ab, or Apache Bench, provides this functionality
well, and is freely included in the apache distribution.
Because performance tuning can be a neverending affair,
it is a good idea to establish a threshold where performance
is "good enough", that once reached, tuning stops.
=head2 $Application & $Session State
Use NoState 1 setting if you don't need the $Application or $Session
objects. State objects such as these tie to files on disk and will incur a
performance penalty.
If you need the state objects $Application and $Session, and if
running an OS that caches files in memory, set your "StateDir"
directory to a cached file system. On WinNT, all files
may be cached, and you have no control of this. On Solaris, /tmp is
a RAM disk and would be a good place to set the "StateDir" config
setting to. When cached file systems are used there is little
performance penalty for using state files. Linux tends to do a good job
caching its file systems, so pick a StateDir for ease of system
administration.
On Win32 systems, where mod_perl requests are serialized, you
can freely use SessionSerialize to make your $Session requests
faster, and you can achieve similar performance benefits for
$Application if you call $Application->Lock() in your
global.asa's Script_OnStart.
=head2 Low MaxClients
Set your MaxClients low, such that if you have that
many httpd servers running, which will happen on busy site,
your system will not start swapping to disk because of
excessive RAM usage. Typical settings are less than 100
even with 1 gig RAM! To handle more client connections,
look into a dual server, mod_proxy front end.
=head2 High MaxRequestsPerChild
Set your max requests per child thread or process (in httpd.conf) high,
so that ASP scripts have a better chance being cached, which happens after
they are first compiled. You will also avoid the process fork penalty on
UNIX systems. Somewhere between 50 - 500 is probably pretty good.
You do not want to set this too high though or you will risk having
your web processes use too much RAM. One may use Apache::SizeLimit
or Apache::GTopLimit to optimally tune MaxRequestsPerChild at runtime.
=head2 Precompile Modules
For those modules that your Apache::ASP application uses,
make sure that they are loaded in your sites startup.pl
file, or loaded with PerlModule in your httpd.conf, so
that your modules are compiled pre-fork in the parent httpd.
=head2 Precompile Scripts
Precompile your scripts by using the Apache::ASP->Loader() routine
documented below. This will at least save the first user hitting
a script from suffering compile time lag. On UNIX, precompiling scripts
upon server startup allows this code to be shared with forked child
www servers, so you reduce overall memory usage, and use less CPU
compiling scripts for each separate www server process. These
savings could be significant. On a PII300 Solaris x86, it takes a couple seconds
to compile 28 scripts upon server startup, with an average of 50K RAM
per compiled script, and this savings is passed on to the ALL child httpd
servers, so total savings would be 50Kx28x20(MaxClients)=28M!
Apache::ASP->Loader() can be called to precompile scripts and
even entire ASP applications at server startup. Note
also that in modperl, you can precompile modules with the
PerlModule config directive, which is highly recommended.
Apache::ASP->Loader($path, $pattern, %config)
This routine takes a file or directory as its first argument. If
a file, that file will be compiled. If a directory, that directory
will be recursed, and all files in it whose file name matches $pattern
will be compiled. $pattern defaults to .*, which says that all scripts
in a directory will be compiled by default.
The %config args, are the config options that you may want set that affect
compilation. These options include: Debug, Global, GlobalPackage,
DynamicIncludes, IncludesDir, InodeNames, PodComments, StatINC, StatINCMatch, UseStrict,
XMLSubsPerlArgs, XMLSubsMatch, and XMLSubsStrict. If your scripts are later run
with different config options, your scripts may have to be recompiled.
Here is an example of use in a *.conf file:
<Perl>
Apache::ASP->Loader(
'/usr/local/proj/site', "(asp|htm)\$",
'Global' => '/proj/perllib',
'Debug' => -3, # see system output when starting apache
# OPTIONAL configs if you use them in your apache configuration
# these settings affect how the scripts are compiled and loaded
'GlobalPackage' => 'SomePackageName',
'DynamicIncludes' => 1,
'StatINC' => 1,
'StatINCMatch' => 'My',
By default, even when SessionQuery* options are used, cookies will
be used if available with SessionQuery* functionality acting only
as a backup, so this makes it so that cookies will never be used.
+Escape ' with HTMLEncode() to '
-Trying to fix t/server_mail.t to work better for platforms
that it should skip testing on. Updated t/server.t test case.
+Remove exit() from Makefile.PL so CPAN.pm's automatic
follow prereq mechanism works correctly. Thanks to Slaven Rezic
for pointing this out.
+Added Apache::compat loading in mod_perl environment for better
mod_perl 2.0 support.
=item $VERSION = 2.35; $DATE="05/30/2002"
+Destroy better $Server & $Response objects so that my
closure references to these to not attempt to work in the future
against invalid internal data. There was enough data left in these
old objects to make debugging the my closure problem confusing, where
it looked like the ASP object state became invalid.
+Added system debug diagnostics to inspect StateManager group cleanup
(d) Documentation update about flock() work around for
Win95/Win98/WinMe systems, confirmed by Rex Arul
(d) Documentation/site build bug found by Mitsunobu Ozato,
where <% %> not being escaped correctly with $Server->HTMLEncode().
New japanese documentation project started by him
at http://sourceforge.jp/projects/apache-asp-jp/
-InitPackageGlobals() called after new Apache::ASP object created so
core system templates can be compiled even when there was a runtime
compilation error of user templates. Bug fix needed pointed out by
Eamon Daly
=item $VERSION = 2.33; $DATE="04/29/2002"
- fixed up t/server_mail.t test to skip if a sendmail server
is not available on localhost. We only want the test to run
if there is a server to test against.
+ removed cgi/asp script, just a symlink now to the ./asp-perl script
which in this way deprecates it. I had it hard linked, but the
distribution did not untar very well on win32 platform.
+ Reordered the modules in Bundle::Apache::ASP for a cleaner install.
- Fixed bug where XMLSubs where removing <?xml version ... ?> tag
when it was needed in XSLT mode.
+ $Server->Mail({ CC => '...', BCC => '...' }), now works to send
CC & BCC headers/recipients.
+ Removed $Apache::ASP::Register definition which defined the current
executing Apache::ASP object. Only one part of the application was
using it, and this has been fixed. This would have been an unsafe
use of globals for a threaded environment.
+ Decreased latency when doing Application_OnStart, used to sleep(1)
for CleanupMaster sync, but this is not necessary for Application_OnStart
scenario
+ Restructure code / core templates for MailErrorsTo funcationality.
Wrote test mail_error.t to cover this. $ENV{REMOTE_USER} will now
be displayed in the MailErrorsTo message when defined from 401 basic auth.
+ $Server->RegisterCleanup should be thread safe now, as it no longer relies
on access to @Apache::ASP::Cleanup for storing the CODE ref stack.
+ test t/inode_names.t for InodeNames and other file tests covering case
of long file names.
- Fixed long file name sub identifier bug. Added test t/long_names.t.
+ CacheDir may now be set independently of StateDir. It used to default
to StateDir if it was set.
++ Decomposition of modules like Apache::ASP::Session & Apache::ASP::Application
out of ASP.pm file. This should make the source more developer friendly.
This selective code compilation also speeds up CGI requests that do not
need to load unneeded modules like Apache::ASP::Session, by about 50%,
so where CGI mode ran at about 2.1 hits/sec before, now for
light requests that do not load $Session & $Application, requests
run at 3.4 hits/sec, this is on a dual PIII-450 linux 2.4.x
- Caching like for XSLTCache now works in CGI mode.
This was a bug that it did not before.
+ $Server->File() API added, acts as a wrapper around
Apache->request->filename Added test in t/server.t
++ *** EXPERIMENTAL / ALPHA FEATURE NOTE BEGIN ***
New $PERLLIB/Apache/ASP/Share/ directory created to
hold system & user contributed components, which will be found
on the $Server->MapInclude() path, which helps $Response->Include
search '.',Global,IncludesDir, and now Apache::ASP::Share for
includes to load at runtime.
The syntax for loading a shared include is to prefix the file
name with Share:: as in:
$Response->TrapInclude('Share::CORE/MailError.inc');
New test to cover this at t/share.t
This feature is experimental. The naming convention may change
and the feature may disappear altogether, so only use if you
are interesting in experimenting with this feature & will
provide feedback about how it works.
*** EXPERIMENTAL / ALPHA FEATURE NOTE END ***
+ asp-perl script now uses ./asp.conf instead of ./asp.config
for runtime configuration via %Config defined there. Update docs
for running in standalone CGI mode
+ Make use of MANFEST.SKIP to not publish the dev/* files anymore.
- Script_OnEnd guaranteed to run after $Response->End, but
it will not run if there was an error earlier in the request.
+ lots of new test cases covering behaviour of $Response->End
and $Response->Redirect under various conditions like XMLSubs
and SoftRedirect and global.asa Script_OnStart
( run in 0.992 second using v1.01-cache-2.11-cpan-e1769b4cff6 )