NAME

App::Session - represents a sequence of multiple events perhaps executed in separate processes

SYNOPSIS

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

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.

Class Group: Session

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

• Class: App::Session

• Class: App::Session::HTMLHidden

• Class: App::Session::Cookie

• Class: App::Session::ApacheSession

• Class: App::Session::ApacheSessionX

Constructor Methods:

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

_init()

The _init() method is called from within the standard Session constructor. The _init() method in this class does nothing. It allows subclasses of the Session to customize the behavior of the constructor by overriding the _init() method.

* Signature: _init($named)
* Param:     $named        {}    [in]
* Return:    void
* Throws:    App::Exception
* Since:     0.01

Sample Usage: 

$ref->_init($args);

Public Methods:

get()

The get() returns the var of a session_object.

* Signature: $value = $session->get($service_name_var);
* Signature: $value = $session->get($service, $name, $var);
* Signature: $value = $session->get($service, $name, $var, $default);
* Signature: $value = $session->get($service, $name, $var, $default, $setdefault);
* Param:  $service        string
* Param:  $name           string
* Param:  $attribute      string
* Param:  $default        any
* Param:  $setdefault     boolean
* Return: $value          string,ref
* Throws: <none>
* Since:  0.01

Sample Usage: 

$cname = $session->get("cname");
$cname = $session->get("default.cname");
$cname = $session->get("SessionObject.default.cname");
$cname = $session->get("SessionObject", "default", "cname");
$width = $session->get("SessionObject", "main.app.toolbar.calc", "width", 45, 1);
$width = $session->get("main.app.toolbar.calc.width",     undef,   undef, 45, 1);

set()

The set() sets the value of a variable in one of the Services for the Session.

* Signature: $session->set($service_name_var, $value);
* Signature: $session->set($service, $name, $var, $value);
* Param:  $service_name_var string
* Param:  $service          string
* Param:  $name             string
* Param:  $var              string
* Param:  $value            string,ref
* Return: void
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session->set("cname",                             "main_screen");
$session->set("default.cname",                     "main_screen");
$session->set("SessionObject.default.cname",       "main_screen");
$session->set("SessionObject", "default", "cname", "main_screen");
$session->set("SessionObject", "main.app.toolbar.calc", "width", 50);
$session->set("SessionObject", "xyz", "{arr}[1][2]",  14);
$session->set("SessionObject", "xyz", "{arr.totals}", 14);

default()

The default() sets the value of a SessionObject's attribute only if it is currently undefined.

* Signature: $session->default($service_name_var, $value);
* Signature: $session->default($service, $name, $var, $value);
* Param:  $service_name_var string
* Param:  $service          string
* Param:  $name             string
* Param:  $var              string
* Param:  $value            string,ref
* Return: $value            string,ref
* Throws: <none>
* Since:  0.01

Sample Usage: 

$cname = $session->default("default", "cname");
$width = $session->default("main.app.toolbar.calc", "width");

delete()

The delete() deletes an attribute of a session_object in the Session.

* Signature: $session->delete($service, $name, $attribute);
* Param:  $service      string
* Param:  $name         string
* Param:  $attribute    string
* Return: void
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session->delete("default", "cname");
$session->delete("main.app.toolbar.calc", "width");
$session->delete("xyz", "{arr}[1][2]");
$session->delete("xyz", "{arr.totals}");

get_session_id()

The get_session_id() returns the session_id of this particular session. This session_id is unique for all time. If a session_id does not yet exist, one will be created. The session_id is only created when first requested, and not when the session is instantiated.

* Signature: $session_id = $session->get_session_id();
* Param:  void
* Return: $session_id      string
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session->get_session_id();

new_session_id()

The new_session_id() returns a new, unique session_id.

* Signature: $session_id = $session->new_session_id();
* Param:  void
* Return: $session_id      string
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session_id = $session->new_session_id();

html()

The html() method ...

* Signature: $html = $session->html();
* Param:  void
* Return: $html      string
* Throws: <none>
* Since:  0.01

Sample Usage: 

$session->html();

The html() method on a session may be used by Contexts which embed session information in a web page being returned to the user's browser. (Some contexts do not use HTML for the User Interface and will not call this routine.)

The most common method of embedding the session information in the HTML is to encode the session_id in an HTML hidden variable (<input type=hidden>). That is what this implementation does.

dump()

* Signature: $perl = $session->dump();
* Param:     void
* Return:    $perl      text
* Throws:    App::Exception
* Since:     0.01

Sample Usage: 

$session = $context->session();
print $session->dump(), "\n";

cpanm App::Context

perl -MCPAN -e shell
install App::Context