Devstack » Articles » Intro to Apache2::ASP

Intro to Apache2::ASP

Topics

What is Apache2::ASP?
Anatomy of an Apache2::ASP Website
Apache2::ASP Configuration - XML
Apache2::ASP Configuration - Apache

What is Apache2::ASP?

Apache2::ASP is a web application framework inspired by Classic ASP, ASP.NET, Apache Struts (formerly "Jakarta" Struts) and JavaServer Pages (JSP). Apache2::ASP was developed specifically to address the following problems with web application development:

Unit Testing
The ability to automatically test all or part of a web application.
Code Coverage Analysis
The ability to ensure that the unit tests exercise the entire code base.
Profiling
The ability to discover speed bottlenecks and eliminate them.

In addition, Apache2::ASP provides the following features (to start):

Unified Configuration
A single point of configuration, plus the ability to further refine the configuration via configuration post-processors.
Rich File Upload System
File uploads, archiving, security and downloads via a simple Object-Oriented interface: the MediaManager.
Secure Authorization & Request Filtering
Guaranteed security from unauthorized requests require only a few lines of simple code to set up.
Shared-Nothing Architecture
Session- and Application-State is stored in a database, so simple load-balancing schemes like round robin or Perlbal allowing even simple, inexpensive networks to scale out indefinitely.
MasterPages and Partial-Page Caching
As in ASP.NET, MasterPages can be thought of as a kind of "super-class" which other pages can subclass. Computationally expensive parts of a web page can be cached, keyed on various Form or Session variables.
Support for an MVC Architecture
Out-of-the-box, Apache2::ASP provides support for a simple, effective MVC Architecture (Model-View-Controller). However Apache2::ASP does not require the use any prescribed development methodology.
Embeddable Within Other Systems
Through the use of Apache2::ASP::Test::Base, Apache2::ASP web applications can be accessed directly from your own code, without the need for a web server.

Anatomy of an Apache2::ASP Website

www.example.com
|-- MEDIA
|-- PAGE_CACHE
|-- conf
|   |-- apache2-asp-config.xml
|   `-- httpd.conf
|-- etc
|   |-- properties.yaml
|   `-- test_fixtures.yaml
|-- handlers
|-- htdocs
|   |-- GlobalASA.pm
|   `-- index.asp
`-- lib

If you simply run the asphelper script that comes with Apache2::ASP, this file structure will be created automatically for you.

NOTE: - Place your website-specific Perl modules under the lib directory.

Apache2::ASP Configuration - XML

As with every web application framework, Apache2::ASP has its own style of configuration.

The configuration has 4 parts, listed below:

system

This section tells Apache2::ASP which modules to load, which lib-dirs should be included into @INC, the %ENV variables that should be set, settings you want global access to and any post-processors that should be called.

The system section looks like this by default:

  <system>
    <post_processors>
<!--
      <class>My::PostProcessor</class>
      <class>My::PostProcessor2</class>
-->
    </post_processors>
    <libs>
      <lib>@ServerRoot@/lib</lib>
    </libs>
    <load_modules>
      <module>DBI</module>
    </load_modules>
    <env_vars>
      <var>
        <name>environment-var1</name>
        <value>value-1</value>
      </var>
      <var>
        <name>environment-var2</name>
        <value>value-2</value>
      </var>
    </env_vars>
    <settings>
      <setting>
        <name>mysetting</name>
        <value>some-value</value>
      </setting>
      <setting>
        <name>anothersetting</name>
        <value>anothervalue</value>
      </setting>
    </settings>
  </system>

Of particular interest is the settings part. To access one of those settings, you could simply use $Config->settings->mysetting; or $Config->settings->anothersetting;

NOTE: settings are read-only and can only be changed by manually editing the XML config file.

errors

When Bad Things Happen, you might want to get an email about it. Use this section to tell Apache2::ASP how to send you an email of the error as a stacktrace, so you know exactly what went wrong, how, and when.

The errors section looks like this, by default:

  <errors>
    <error_handler>Apache2::ASP::ErrorHandler</error_handler>
    <mail_errors_to>you@domain.com</mail_errors_to>
    <mail_errors_from>root@localhost.com</mail_errors_from>
    <smtp_server>localhost</smtp_server>
  </errors>

If you want to do something else when an error happens, subclass Apache2::ASP::ErrorHandler and do something like this:

package My::ErrorHandler;

use strict;
use warnings 'all';
use base 'Apache2::ASP::ErrorHandler';
use vars __PACKAGE__>VARS;

sub run {
  my ($s, $context) = @_;
  
  # Go ahead and send the error notification email (if you want):
  $s->SUPER::run( $context );
  
  # Now do something special about the error:
  my $error = $Stash->{error};

  # TIP: the error object looks like this:
  $VAR1 = {
    title       => "An error occurred in file ... at line ...",
    file        => "/path/to/some/file.pm",
    line        => 40,
    stacktrace  => "long mess from Carp::confess"
  };
}# end run()

1;# return true:

web

Website-specific configuration, such as where your website is located on disk, where compiled ASP scripts should be stored, and any Request Filters you have installed.

The web section looks like this by default:

  <web>
    <application_name>MyApp</application_name>
    <application_root>@ServerRoot@</application_root>
    <handler_root>@ServerRoot@/handlers</handler_root>
    <media_manager_upload_root>@ServerRoot@/MEDIA</media_manager_upload_root>
    <www_root>@ServerRoot@/htdocs</www_root>
    <page_cache_root>@ServerRoot@/PAGE_CACHE</page_cache_root>
    <request_filters>
<!--
      <filter>
        <uri_match>/.*</uri_match>
        <class>My::MemberFilter</class>
      </filter>
      <filter>
        <uri_equals>/index.asp</uri_equals>
        <class>My::MemberFilter2</class>
      </filter>
-->
    </request_filters>
  </web>

data_connections

By default, Apache2::ASP uses 3 data connections:

session - For session state management.
application - For application state management.
main - Your web application's primary data source.

The data_connections section looks like this by default:

  <data_connections>
    <session>
      <manager>Apache2::ASP::SessionStateManager::MySQL</manager>
      <cookie_domain>www.example.com</cookie_domain>
      <cookie_name>session-id</cookie_name>
      <dsn>DBI:mysql:dstack_dev:localhost</dsn>
      <username>root</username>
      <password>j@p@n</password>
      <session_timeout>30</session_timeout>
    </session>
    <application>
      <manager>Apache2::ASP::ApplicationStateManager::MySQL</manager>
      <dsn>DBI:mysql:dstack_dev:localhost</dsn>
      <username>root</username>
      <password>j@p@n</password>
    </application>
    <main>
      <dsn>DBI:mysql:dstack_dev:localhost</dsn>
      <username>root</username>
      <password>j@p@n</password>
    </main>
  </data_connections>

Apache2::ASP Configuration - Apache

After running asphelper, the file conf/httpd.conf will look something like this:

# Needed for CGI::Apache2::Wrapper to work properly:
LoadModule apreq_module    modules/mod_apreq2.so

# Load up some important modules:
PerlModule DBI
PerlModule Apache2::ASP::ModPerl

# Admin website:
<VirtualHost *:80>

  ServerName    www.example.com
  DocumentRoot  /usr/local/dstack/www.example.com/htdocs
  
  # Set the directory index:
  DirectoryIndex index.asp
  
  # All *.asp files are handled by Apache2::ASP::ModPerl
  <Files ~ (.asp$)>
    SetHandler  perl-script
    PerlResponseHandler Apache2::ASP::ModPerl
  </Files>
  
  # !IMPORTANT! Prevent anyone from viewing your GlobalASA.pm
  <Files ~ (.pm$)>
    Order allow,deny
    Deny from all
  </Files>
  
  # All requests to /handlers/* will be handled by their respective handler:
  <Location /handlers>
    SetHandler  perl-script
    PerlResponseHandler Apache2::ASP::ModPerl
  </Location>
  
</VirtualHost>