view release on metacpan or  search on metacpan

lib/App/Session.pm  view on Meta::CPAN

   # ... official way to get a Session object ...
   use App;
   $session = App->context();
   $context = $session->session();   # get the session

   # any of the following named parameters may be specified
   $session = $context->session(
   );

   # ... alternative way (used internally) ...
   use App::Session;
   $session = App::Session->new();

=cut

#############################################################################
# CONSTANTS
#############################################################################

=head1 DESCRIPTION

A Session class models the sequence of events associated with a
use of the system.  These events may occur in different processes.

For instance, in a web environment, when a new user arrives at a web site,
he is allocated a new
Session, even though he may not even be authenticated.  In subsequent
requests, his actions are tied together by a Session ID that is transmitted
from the browser to the server on each request.  During the Session, he
may log in, log out, and log in again.
Finally, Sessions in the web environment generally time out if not 
accessed for a certain period of time.

Conceptually, the Session may span processes, so they generally have a
way to persist themselves so that they may be reinstantiated wherever
they are needed.  This would certainly be true in CGI or Cmd Contexts
where each CGI request or command execution relies on and contributes
to the running state accumulated in the Session.  Other execution
Contexts (Curses, Gtk) only require trivial implementations of a Session
because it stays in memory for the duration of the process.
Nonetheless, even these Contexts use a Session object so that the
programming model across multiple platforms is the same.

=cut

#############################################################################
# CLASS GROUP
#############################################################################

=head1 Class Group: Session

The following classes might be a part of the Session Class Group.

=over

=item * Class: App::Session

=item * Class: App::Session::HTMLHidden

=item * Class: App::Session::Cookie

=item * Class: App::Session::ApacheSession

=item * Class: App::Session::ApacheSessionX

=back

=cut

#############################################################################
# CONSTRUCTOR METHODS
#############################################################################

=head1 Constructor Methods:

=cut

#############################################################################
# new()
#############################################################################

=head2 new()

This constructor is used to create Session objects.
Customized behavior for a particular type of Sessions
is achieved by overriding the _init() method.

    * Signature: $session = App::Session->new($array_ref)
    * Signature: $session = App::Session->new($hash_ref)
    * Signature: $session = App::Session->new("array",@args)
    * Signature: $session = App::Session->new(%named)
    * Param:     $array_ref          []
    * Param:     $hash_ref           {}
    * Return:    $session            App::Session
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage:

    use "App::Session";

    $ref = App::Session->new("array", "x", 1, -5.4, { pi => 3.1416 });
    $ref = App::Session->new( [ "x", 1, -5.4 ] );
    $ref = App::Session->new(
        arg1 => 'value1',
        arg2 => 'value2',
    );

=cut

sub new {
    &App::sub_entry if ($App::trace);
    my $this = shift;
    my $class = ref($this) || $this;

    my $self = {};
    bless $self, $class;

    $self->_init(@_);  # allows a subclass to override this portion