Apache-ASP
view release on metacpan or search on metacpan
PerlModule Apache::ASP
The cache arguments are shown here
$Response->Include({
File => 'file.inc',
Cache => 1, # to activate cache layer
Expires => 3600, # to expire in one hour
LastModified => time() - 600, # to expire if cached before 10 minutes ago
Key => $Request->Form, # to cache based on checksum of serialized form data,
Clear => 1, # always executes include & cache output
}, @include_args);
File - include file to execute, can be file name or \$script
script data passed in as a string reference.
Cache - activate caching, will run like normal include without this
Expires - only cache for this long in seconds
LastModified - if cached before this time(), expire
Key - The cache item identity. Can be $data, \$data, \%data, \@data,
this data is serialized and combined with the filename & @include_args
to create a MD5 checksum to fetch from the cache with. If you wanted
to cache the results of a search page from form data POSTed,
then this key could be
{ Key => $Request->Form }
Clear - If set to 1, or boolean true, will always execute the include
and update the cache entry for it.
Motivation: If an include takes 1 second to execute because of complex
SQL to a database, and you can cache the output of this include because
it is not realtime data, and the cache layer runs at .01 seconds, then
you have a 100 fold savings on that part of the script. Site scalability
can be dramatically increased in this way by intelligently caching
bottlenecks in the web application.
Use Sparingly: If you have a fast include, then it may execute faster
than the cache layer runs, in which case you may actually slow your site
down by using this feature. Therefore try to use this sparingly, and
only when sure you really need it. Apache::ASP scripts generally execute
very quickly, so most developers will not need to use this feature at
all.
$Response->Include(\$script_text, @args)
Added in Apache::ASP 2.11, this method allows for executing ASP scripts
that are generated dynamically by passing in a reference to the script
data instead of the file name. This works just like the normal
$Response->Include() API, except a string reference is passed in instead
of a filename. For example:
<%
my $script = "<\% print 'TEST'; %\>";
$Response->Include(\$script);
%>
This include would output TEST. Note that tokens like <% and %> must be
escaped so Apache::ASP does not try to compile those code blocks
directly when compiling the original script. If the $script data were
fetched directly from some external resource like a database, then these
tokens would not need to be escaped at all as in:
<%
my $script = $dbh->selectrow_array(
"select script_text from scripts where script_id = ?",
undef, $script_id
);
$Response->Include(\$script);
%>
This method could also be used to render other types of dynamic scripts,
like XML docs using XMLSubs for example, though for complex runtime XML
rendering, one should use something better suited like XSLT. See the
$Server->XSLT API for more on this topic.
$Response->IsClientConnected()
API Extension. 1 for web client still connected, 0 if disconnected which
might happen if the user hits the stop button. The original API for this
$Response->{IsClientConnected} is only updated after a $Response->Flush
is called, so this method may be called for a refreshed status.
Note $Response->Flush calls $Response->IsClientConnected to update
$Response->{IsClientConnected} so to use this you are going straight to
the source! But if you are doing a loop like:
while(@data) {
$Response->End if ! $Response->{IsClientConnected};
my $row = shift @data;
%> <%= $row %> <%
$Response->Flush;
}
Then its more efficient to use the member instead of the method since
$Response->Flush() has already updated that value for you.
$Response->Redirect($url)
Sends the client a command to go to a different url $url. Script
immediately ends.
$Response->TrapInclude($file, @args)
Calls $Response->Include() with same arguments as passed to it, but
instead traps the include output buffer and returns it as as a perl
string reference. This allows one to postprocess the output buffer
before sending to the client.
my $string_ref = $Response->TrapInclude('file.inc');
$$string_ref =~ s/\s+/ /sg; # squash whitespace like Clean 1
print $$string_ref;
The data is returned as a referenece to save on what might be a large
string copy. You may dereference the data with the $$string_ref
notation.
$Response->Write($data)
Write output to the HTML page. <%=$data%> syntax is shorthand for a
$Response->Write($data). All final output to the client must at some
point go through this method.
$Request Object
The request object manages the input from the client browser, like posts,
query strings, cookies, etc. Normal return results are values if an index is
display all the data in current user sessions.
$Application->SessionCount()
This NON-PORTABLE method returns the current number of active sessions
in the application, and is enabled by the SessionCount configuration
setting. This method is not implemented as part of the original ASP
object model, but is implemented here because it is useful. In
particular, when accessing databases with license requirements, one can
monitor usage effectively through accessing this value.
$Server Object
The server object is that object that handles everything the other objects
do not. The best part of the server object for Win32 users is the
CreateObject method which allows developers to create instances of ActiveX
components, like the ADO component.
$Server->{ScriptTimeout} = $seconds
Not implemented. May never be. Please see the Apache Timeout
configuration option, normally in httpd.conf.
$Server->Config($setting)
API extension. Allows a developer to read the CONFIG settings, like
Global, GlobalPackage, StateDir, etc. Currently implemented as a wrapper
around
Apache->dir_config($setting)
May also be invoked as $Server->Config(), which will return a hash ref
of all the PerlSetVar settings.
$Server->CreateObject($program_id)
Allows use of ActiveX objects on Win32. This routine returns a reference
to an Win32::OLE object upon success, and nothing upon failure. It is
through this mechanism that a developer can utilize ADO. The equivalent
syntax in VBScript is
Set object = Server.CreateObject(program_id)
For further information, try 'perldoc Win32::OLE' from your favorite
command line.
$Server->Execute($file, @args)
New method from ASP 3.0, this does the same thing as
$Response->Include($file, @args)
and internally is just a wrapper for such. Seems like we had this
important functionality before the IIS/ASP camp!
$Server->File()
Returns the absolute file path to current executing script. Same as
Apache->request->filename when running under mod_perl.
ASP API extension.
$Server->GetLastError()
Not implemented, will likely not ever be because this is dependent on
how IIS handles errors and is not relevant in Apache.
$Server->HTMLEncode( $string || \$string )
Returns an HTML escapes version of $string. &, ", >, <, are each escapes
with their HTML equivalents. Strings encoded in this nature should be
raw text displayed to an end user, as HTML tags become escaped with this
method.
As of version 2.23, $Server->HTMLEncode() may take a string reference
for an optmization when encoding a large buffer as an API extension.
Here is how one might use one over the other:
my $buffer = '&' x 100000;
$buffer = $Server->HTMLEncode($buffer);
print $buffer;
- or -
my $buffer = '&' x 100000;
$Server->HTMLEncode(\$buffer);
print $buffer;
Using the reference passing method in benchmarks on 100K of data was 5%
more efficient, but maybe useful for some. It saves on copying the 100K
buffer twice.
$Server->MapInclude($include)
API extension. Given the include $include, as an absolute or relative
file name to the current executing script, this method returns the file
path that the include would be found from the include search path. The
include search path is the current script directory, Global, and
IncludesDir directories.
If the include is not found in the includes search path, then undef, or
bool false, is returned. So one may do something like this:
if($Server->MapInclude('include.inc')) {
$Response->Include('include.inc');
}
This code demonstrates how one might only try to execute an include if
it exists, which is useful since a script will error if it tries to
execute an include that does not exist.
$Server->MapPath($url);
Given the url $url, absolute, or relative to the current executing
script, this method returns the equivalent filename that the server
would translate the request to, regardless or whether the request would
be valid.
Only a $url that is relative to the host is valid. Urls like "." and "/"
are fine arguments to MapPath, but http://localhost would not be.
To see this method call in action, check out the sample
./site/eg/server.htm script.
$Server->Mail(\%mail, %smtp_args);
With the Net::SMTP and Net::Config modules installed, which are part of
the perl libnet package, you may use this API extension to send email.
The \%mail hash reference that you pass in must have values for at least
the To, From, and Subject headers, and the Body of the mail message.
The return value of this routine is 1 for success, 0 for failure. If the
MailHost SMTP server is not available, this will have a return value of
0.
You could send an email like so:
'text/html' in the above example.
If you have MailFrom configured, this will be the default for the From
header in your email. For more configuration options like the MailHost
setting, check out the CONFIG section.
The return value of this method call will be boolean for success of the
mail being sent.
If you would like to specially configure the Net::SMTP object used
internally, you may set %smtp_args and they will be passed on when that
object is initialized. "perldoc Net::SMTP" for more into on this topic.
If you would like to include the output of an ASP page as the body of
the mail message, you might do something like:
my $mail_body = $Response->TrapInclude('mail_body.inc');
$Server->Mail({ %mail, Body => $$mail_body });
$Server->RegisterCleanup($sub)
non-portable extension
Sets a subroutine reference to be executed after the script ends,
whether normally or abnormally, the latter occurring possibly by the
user hitting the STOP button, or the web server being killed. This
subroutine must be a code reference created like:
$Server->RegisterCleanup(sub { $main::Session->{served}++; });
or
sub served { $main::Session->{served}++; }
$Server->RegisterCleanup(\&served);
The reference to the subroutine passed in will be executed. Though the
subroutine will be executed in anonymous context, instead of the script,
all objects will still be defined in main::*, that you would reference
normally in your script. Output written to $main::Response will have no
affect at this stage, as the request to the www client has already
completed.
Check out the ./site/eg/register_cleanup.asp script for an example of
this routine in action.
$Server->Transfer($file, @args)
New method from ASP 3.0. Transfers control to another script. The
Response buffer will not be cleared automatically, so if you want this
to serve as a faster $Response->Redirect(), you will need to call
$Response->Clear() before calling this method.
This new script will take over current execution and the current script
will not continue to be executed afterwards. It differs from Execute()
because the original script will not pick up where it left off.
As of Apache::ASP 2.31, this method now accepts optional arguments like
$Response->Include & $Server->Execute. $Server->Transfer is now just a
wrapper for:
$Response->Include($file, @args);
$Response->End;
$Server->URLEncode($string)
Returns the URL-escaped version of the string $string. +'s are
substituted in for spaces and special characters are escaped to the
ascii equivalents. Strings encoded in this manner are safe to put in
urls... they are especially useful for encoding data used in a query
string as in:
$data = $Server->URLEncode("test data");
$url = "http://localhost?data=$data";
$url evaluates to http://localhost?data=test+data, and is a
valid URL for use in anchor <a> tags and redirects, etc.
$Server->URL($url, \%params)
Will return a URL with %params serialized into a query string like:
$url = $Server->URL('test.asp', { test => value });
which would give you a URL of test.asp?test=value
Used in conjunction with the SessionQuery* settings, the returned URL
will also have the session id inserted into the query string, making
this a critical part of that method of implementing cookieless sessions.
For more information on that topic please read on the setting in the
CONFIG section, and the SESSIONS section too.
$Server->XSLT(\$xsl_data, \$xml_data)
* NON-PORTABLE API EXTENSION *
This method takes string references for XSL and XML data and returns the
XSLT output as a string reference like:
my $xslt_data_ref = $Server->XSLT(\$xsl_data, \$xml_data)
print $$xslt_data_ref;
The XSLT parser defaults to XML::XSLT, and is configured with the
XSLTParser setting, which can also use XML::Sablotron ( support added in
2.11 ), and XML::LibXSLT ( support added in 2.29 ). Please see the
CONFIG section for more information on the XSLT* settings that drive
this API. The XSLT setting itself uses this API internally to do its
rendering.
This API was created to allow developers easy XSLT component rendering
without having to render the entire ASP scripts via XSLT. This will make
an easy plugin architecture for those looking to integrate XML into
their existing ASP application frameworks.
At some point, the API will likely take files as arguments, but not as
of the 2.11 release.
SSI
SSI is great! One of the main features of server side includes is to include
other files in the script being requested. In Apache::ASP, this is
implemented in a couple ways, the most crucial of which is implemented in
the file include. Formatted as
<!--#include file=filename.inc-->
,the .inc being merely a convention, text from the included file will be
inserted directly into the script being executed and the script will be
compiled as a whole. Whenever the script or any of its includes change, the
script will be recompiled.
global.asa when $^W is set will trigger subroutine redefinition
warnings. Reloading global.asa should occur without any problems
under normal usage of the system, thus this work around.
This fix is important to UseStrict functionality because warnings
automatically become thrown as die() errors with UseStrict enabled,
so we have to disable normal soft warnings here.
-$Response->Include() runtime errors now throw a die() that
can be trapped. This was old functionality that has been restored.
Other compile time errors should still trigger a hard error
like script compilation, global.asa, or $Response->Include()
without an eval()
+Some better error handling with Debug 3 or -3 set, cleaned
up developer errors messages somewhat.
$VERSION = 2.37; $DATE="07/03/2002"
-Fixed the testing directory structures for t/long_names.t
so that tar software like Archive::Tar & Solaris tar that
have problems with long file names will still be able
to untar distribution successfully. Now t/long_names.t
generates its testing directory structures at runtime.
-Fixes for "make test" to work under perl 5.8.0 RC2,
courtesy of Manabu Higashida
+SessionQueryForce setting created for disabling use of cookies
for $Session session-id passing, rather requiring use of SessionQuery*
functionality for session-id passing via URL query string.
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.
$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
$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.
( run in 0.683 second using v1.01-cache-2.11-cpan-39bf76dae61 )