NAME

PSA.pm - Perl Server Applications

SYNOPSIS

use PSA qw(Cache Request::CGI Response::HTTP);

# See the man pages for PSA::Cache and T2::Storage for more
my $cache = PSA::Cache->new( base_dir => "../psa-bin" );
my $storage = T2::Storage->open( "myapp" );

my $acceptor = PSA::Acceptor::AutoCGI->new();

while ( my $request = $acceptor->get_request() ) {

    my $psa = PSA->new
        (
         request => $request,
         response => PSA::Response::HTTP->new(),

         # your persistent PSA::Cache object for cached code
         cache => $cache,
         # your application's Tangram storage backend
         storage => $storage,
        );

    # If your sessions are in your Tangram storage
    $psa->set_session
        ( PSA::Session->fetch($storage, $psa->sid) );

    # Process the request
    $psa->run("whassap.pl");

}

$storage->disconnect();

DESCRIPTION

Perl Server Applications are a fast and scalable solution to dynamic page generation and general purpose application servers.

A PSA object represents a request processor; instances of it may be created for individual requests. It has methods of accepting requests (PSA::Acceptor::XXX objects), that emit request objects (PSA::Request::XXX). PSA pages, like small CGI fragments (but as fast as code cached by mod_perl et al) extract information from the request, do whatever they need to do with storage and then respond with some form of PSA::Response::XXX object.

There are many other parts of the PSA object that come into play, see below for details.

ATTRIBUTES

These are the attributes of the psa object.

request

a PSA::Request derived object. See PSA::Request, though most people will be interested in PSA::Request::CGI.

response

a PSA::Response derived object. See PSA::Request, though most people will be interested in PSA::Request::HTTP.

session

database-held, schema driven session data. See PSA::Session

heap

session-file or database-held, free form session data.

heap_obj

Object behind heap (may or may not bear some relation to tied($psa->heap), if set). See PSA::Heap.

cache

the PSA::Cache object; responsible for efficiently calling other parts of the application. eg, when you need to "run" other pages, this happens through $psa->cache->run(). See PSA::Cache.

schema

The `Schema' object(s) for the application(s) currently housed by this PSA instance. This is normally a T2::Schema object; see T2::Schema for more.

storage

The Tangram::Storage (or, perhaps, T2::Storage) object(s) for the application(s) currently housed by this PSA instance.

sid

The Session ID of this PSA session. This is normally a 32 letter hex string (md5sum style). Usually auto-generated or auto-slurped from the request object.

docroot

Where on the local filesystem that "/" appears to be. Auto-detected.

mileage

How many requests this particular instance of the Perl Server Application has served.

IMPORTER ARGUMENTS

By specifying a list of partial modules to load, make the code look tidier;

use PSA qw(Acceptor::AutoCGI Request::CGI Response::HTTP);

METHODS

$psa->run("page.psa", [@args])

Runs "page.psa", passing @args as parameters. You don't need to pass the PSA object as the first parameter; this is automatic.

$psa->yield("state", args);

Like ->run(), but calls the page after this PSA has reached the top of its call stack.

$psa->spawn(@options)

Like ->run(), but calls the page after this page has finished, and with a new PSA object, which is a copy of this one. @options is passed to the copy constructor.

$psa->wait($child_psa, $state, @args)

Lets the PSA object $child_psa know that you're waiting for it to finish. When it's done, and anything it's yielded, etc, are also done, then it will signal completion by calling the passed state on $psa.

ie, this will call on completion:

$psa->run($psa->rel_path($state), @args)

Note: using the POE runtime, this only works if $psa is the parent of $child_psa as created using $psa->spawn().

closure("page.psa", [@args])

Returns an anonymous subroutine to "page.psa" compiled into a sub.

the sub is basically

{
  my @args = (@_);
  my $psa
  sub {
     $psa->run("page.psa", @args, @_);
  }
}

ie, the PSA object you construct it with becomes a default parameter to it.

my $widget = $psa->closure("mywidget.psa");

$psa->include("mypagewithawidgetasaparameter.psa", $widget);

get_session

Returns the PSA::Session object for this PSA instance.

sid

Returns the session ID as a string. The SID of the Session/Heap takes priority over any SID received in the input request (they should be the same of course :-))

Returns undef if there is no SID already. Generally the Session constructor should set up the SID in the PSA object.

storage([ $site ])

Returns the currently primary Tangram::Storage object, or the one for the named site if given.

All connection details, as well as the file where the Tangram Schema can be found, are stored in files in the web root in etc/.

schema([ $site ])

Returns the currently active T2::Schema object for the currently running PSA site. Note that this is a `T2::Schema' object, not a `Tangram::Schema' object; the Tangram::Schema object can be retrieved using $schema->schema ($psa->schema->schema).

uri(...)

Returns a URI to the next page. See PSA::Request->uri

filename($pkgspace)

Returns the PSA filename associated with the Perl package space $pkgspace (as probably returned by a function like caller().

$psa->docroot_ok($filename)

Returns the local relative or absolute path to the passed relative docroot location.

Should only return a path if the file is found to exist.

$psa->attach_session

Starts the session via PSA::Session (database-side sessions).

$psa->attach_heap

Starts the session via PSA::Heap (middleware sessions).

$psa->detach_heap

Saves the session via PSA::Heap.

$psa->rollback_heap

Forgets all of the changes to the heap and restores it to the way it was the last time it was read, or written. ie, it's fetched again. You better not have any remaining references to the main session object, otherwise nothing will happen...

$psa->commit_heap

Saves the session, but keeps its data available

AUTHOR

Sam Vilain, <samv@cpan.org>

cpanm PSA

perl -MCPAN -e shell
install PSA