App::SessionObject - Interface for configurable, stateful objects

    use App;

    $context = App->context();
    $session_object = $context->service("SessionObject");  # or ...
    $session_object = $context->session_object();

A SessionObject is an object that can be manipulated without having to worry about its lifecycle (i.e. persistence, saving and restoring state, etc.) or its location (local or remote).

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

* Class: App::SessionObject

* Class: App::SessionObject::Entity - entity session_objects are business objects (like EJB)

* Class: App::SessionObject::Entity::Repository - a local entity session_object stored in a Repository

* Class: App::SessionObject::Entity::SOAP - a remote entity session_object, accessed via SOAP

* Class: App::SessionObject::HTML - user interface session_objects displayed on a browser in HTML

* Class: App::SessionObject::Curses - user interface session_objects displayed on a terminal using Curses

* Class: App::SessionObject::Gtk - user interface session_objects displayed in X11 using Gtk

* Class: App::SessionObject::Tk - user interface session_objects displayed in X11 using Tk

* Class: App::SessionObject::WxPerl - user interface session_objects displayed on Windows using wxPerl

A SessionObject is an object that can be manipulated without having to worry about its lifecycle (i.e. persistence, saving and restoring state, etc.) or its location (local or remote).

A SessionObject is a App Service, and it inherits all of the features of App Services.

  * Each SessionObject may be identified by a unique (text) name
  * Entity SessionObject are kept separate from UI SessionObject by naming convention
  * SessionObject are accessed by requesting them by name from the Context
  * SessionObject have attributes (which may be references to complex data structures)
  * Attributes of SessionObject are accessed via get()/set() methods
  * get($attribute) is equivalent to $self->{$attribute} (but not set())
  * Attributes may be defaulted in the code that first accesses the SessionObject,
    configured in the Config file, or overridden at runtime for the
    duration of the Session

A user interface SessionObject also has a display() method to display the SessionObject on the user agent. The values that are set are stored in the user's Session, so every user Session has a unique copy of every user interface SessionObject.

An entity SessionObject is shared between all user Sessions. It maintains its state in a shared data store such as a Repository.

A SessionObject Service is a means by which an object can be manipulated without having to worry about its lifecycle (i.e. persistence, saving and restoring state, etc.) or its location (local or remote).

 * Throws: App::Exception::SessionObject
 * Since:  0.01

The constructor is inherited from App::Service|App::Service/"new()".

The _init() method is called from within the standard Service constructor. Common to all SessionObject initializations, is the absorption of container attributes. "Absorbable attributes" from the session_object are copied from the container session_object to the initialized session_object.

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

    Sample Usage: 

    $service->_init(\%args);

    * Signature: $self->shutdown();
    * Throws:    App::Exception
    * Since:     0.01

    $session_object->shutdown();

    * Signature: $self->container();
    * Signature: $self->container($name);
    * Params:    $name      string
    * Throws:    App::Exception
    * Since:     0.01

    $container = $session_object->container();

    * Signature: $attrib = $self->container_attrib();
    * Signature: $attrib = $self->container_attrib($name);
    * Params:    $name      string
    * Returns:   $attrib    string
    * Throws:    App::Exception
    * Since:     0.01

    $attrib = $session_object->container_attrib();

    * Signature: $handled = $self->handle_event($session_object_name,$event,@args);
    * Param:     $session_object_name    string
    * Param:     $event          string
    * Param:     @args           any
    * Return:    $handled        boolean
    * Throws:    App::Exception
    * Since:     0.01

    $handled = $session_object->handle_event("app.table.sort","click","up",4,20);
    $handled = $session_object->handle_event("app.table","sort","down","last_name");

    * Signature: $self->set_value($value);
    * Param:     $value          any
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    $session_object->set_value("hello");
    $session_object->set_value(43);

    * Signature: $value = $self->get_value();
    * Param:     void
    * Return:    $value          any
    * Throws:    App::Exception
    * Since:     0.01

    $value = $session_object->get_value();

    * Signature: $formatted_value = $self->fget_value();
    * Signature: $formatted_value = $self->fget_value($format);
    * Param:     $format            string
    * Return:    $formatted_value   scalar
    * Throws:    App::Exception
    * Since:     0.01

    $formatted_date = $date_session_object->fget_value();  # use default format
    $formatted_date = $date_session_object->fget_value("%Y-%m-%d"); # supply format

    * Signature: $values = $self->get_values();
    * Signature: $values = $self->get_values($default);
    * Signature: $values = $self->get_values($default,$setdefault);
    * Param:     $default        any
    * Param:     $setdefault     boolean
    * Return:    $values         []
    * Throws:    App::Exception
    * Since:     0.01

    $values = $session_object->get_values();

    * Signature: $self->set($attribute,$value);
    * Param:     $attribute      string
    * Param:     $value          any
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    $session_object->set("last_name","Jones");

    * Signature: $value = $self->get($attribute);
    * Signature: $value = $self->get($attribute,$default);
    * Signature: $value = $self->get($attribute,$default,$setdefault);
    * Param:     $attribut       string
    * Param:     $default        any
    * Param:     $setdefault     boolean
    * Return:    $value          any
    * Throws:    App::Exception
    * Since:     0.01

    $last_name = $session_object->get("last_name");
    $is_adult = $session_object->get("adult_ind","Y");   # assume adult
    $is_adult = $session_object->get("adult_ind","Y",1); # assume adult, remember

    * Signature: $self->delete($attribute);
    * Param:     $attribute      string
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    $session_object->delete("voter_id");

    * Signature: $self->set_default($attribute,$default);
    * Param:     $attribute      string
    * Param:     $default        any
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    $session_object->set_default("adult_ind","Y");

    * Signature: $label = $self->label();
    * Signature: $label = $self->label($attrib);
    * Signature: $label = $self->label($attrib,$lang);
    * Param:     $session_object_name    string
    * Param:     $event          string
    * Param:     @args           any
    * Return:    $handled        boolean
    * Throws:    App::Exception
    * Since:     0.01

    print $w->label();           # "Allez!"  (if current lang is "fr")
    print $w->label("name");     # "Jacques" (translation of alternate attribute) (if curr lang is "fr")
    print $w->label("name","en");# "Jack"    (translation of alternate attribute) (override lang is "en")
    print $w->label("","en");    # "Go!"     (default label, overridden lang of "en")
    print $w->label("","en_ca"); # "Go! eh?" (default label, overridden lang of "en_ca")

    * Signature: ($values, $labels) = $self->values_labels();
    * Param:     void
    * Return:    $values       []
    * Return:    $labels       {}
    * Throws:    App::Exception
    * Since:     0.01

    ($values, $labels) = $gender_session_object->values_labels();
    # $values = [ "M", "F" ];
    # $labels = { "M" => "Male", "F" => "Female" };

    * Signature: $labels = $self->labels();
    * Signature: $labels = $self->labels($attribute);
    * Signature: $labels = $self->labels($attribute,$lang);
    * Param:     $attribute      string
    * Param:     $lang           string
    * Return:    $labels         {}
    * Throws:    App::Exception
    * Since:     0.01

    $labels = $w->labels();
    $labels = $w->labels("names");
    $labels = $w->labels("","en");      # English
    $labels = $w->labels("","en_ca");   # Canadian English

    * Signature: $self->print();
    * Param:     void
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    $w->print();

    * Signature: $formatted_value = $self->format($value, $type, $format);
    * Param:     $value             scalar
    * Param:     $type              string
    * Param:     $format            string
    * Return:    $formatted_value   string
    * Throws:    App::Exception
    * Since:     0.01

    $formatted_value = $session_object->format("20020127","date","%Y-%m-%d");
    $formatted_value = $session_object->format("27-Jan-02","date","%Y-%m-%d");
    $formatted_value = $session_object->format("01/27/2002","date","%Y-%m-%d");
    $formatted_value = App::SessionObject->format("01/27/2002","date","%Y-%m-%d");

A static method.

    * Signature: $translated_label = $session_object->translate($label, $lang);
    * Param:     $label               string
    * Param:     $lang                string
    * Return:    $translated_label    string
    * Throws:    App::Exception
    * Since:     0.01

    $translated_label = $session_object->translate($label, $lang);
    print $w->translate("Hello","fr");     # "Bonjour"
    print $w->translate("Hello","fr_ca");  # "Bonjour, eh" (french canadian)

Translates the label into the desired language based on the dictionary which is current in the session_object at the time. This dictionary is usually a reference to a global dictionary which is absorbed from the container session_object.

Returns 'SessionObject';

    * Signature: $service_type = App::SessionObject->service_type();
    * Param:     void
    * Return:    $service_type  string
    * Since:     0.01

    $service_type = $session_object->service_type();

Returns a list of attributes which a service of this type would like to absorb from its container service. This is a *static* method. It doesn't require an instance of the class to call it.

    * Signature: $attribs = App::Service->absorbable_attribs()
    * Param:     void
    * Return:    $attribs       []
    * Throws:    App::Exception
    * Since:     0.01

    $attribs = $session_object->absorbable_attribs();
    @attribs = @{$session_object->absorbable_attribs()};

 * Author:  Stephen Adkins <spadkins@gmail.com>
 * License: This is free software. It is licensed under the same terms as Perl itself.

App::Context|App::Context, App::Service|App::Service