NAME

PSA.pm - Perl Server Applications

SYNOPSIS

See PSA::Intro for a quick introduction to PSA, from an application developer's and system administrator's viewpoint.

See "psa" in bin for information on how to start PSA applications with the command-line psa utility.

See PSA::All for information on starting arbitrary PSA applications on system startup, and monitoring their use via a system such as Nagios.

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 are created for individual requests. It has methods of accepting requests (PSA::Acceptor-derived objects), that emit request objects (PSA::Request-derived objects). PSA pages, like small CGI extract information from the request, do whatever they need to do with storage, commit and then respond by passing some form of a PSA::Response object (possibly mutating it to a PSA::Response::Template).

Systems like ASP use global variables to represent some of the objects that are properties of the PSA 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::Response, though most people will be interested in PSA::Response::HTTP.

session

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

heap_obj

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

heap

session-file or database-held, free form session data. This is always an application scratchpad, available no matter whether ACID sessions (see PSA::Session) or locking-style sessions (see PSA::Heap) are in use.

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. See Tangram::Storage and/or T2::Storage.

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);

or, if using PSA::Init:

  use PSA qw(Init);

this will load config and other things.

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().

$psa->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);

$psa->get_session

Returns the PSA::Session object for this PSA instance. Automatically connects the session if no Heap/Session is open, so be careful :)

$psa->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.

$psa->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/.

$psa->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).

$psa->uri(...)

Returns a URI to the next page. Delegated to PSA::Request->uri, but this is the primary method called by the default templates.

$psa->filename($pkgspace)

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

This is a PSA::Cache reverse lookup!

$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.

This function is used by the default/fallback templates that serve static content (sometimes handled by PSA applications in the interest of configuration flexibility).

$psa->attach_session

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

If the $psa->config property is correctly configured, the class of the Session can be overridden with the following etc/psa.yml fragment:

 classes:
   session: Your::Session

$psa->attach_heap

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

$psa->detach_heap

Saves the session via PSA::Heap.

E<$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. The session is from that point on, read-only.

AUTHOR

Sam Vilain, <samv@cpan.org>

cpanm PSA

perl -MCPAN -e shell
install PSA