P5EEx-Blue-0.01

P5EEx::Blue::PersistentObject


NAME

P5EEx::Blue::PersistentObject - Interface for persistent business objects


SYNOPSIS

    use P5EEx::Blue::P5EE;
    $context = P5EEx::Blue::P5EE->context();
    $po = $context->service("PersistentObject");  # or ...
    $po = $context->persistent_object();


DESCRIPTION

A PersistentObject 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).


Class Group: PersistentObject

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

A PersistentObject 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 PersistentObject is a P5EE Service, and it inherits all of the features of P5EE Services.

  * Each PersistentObject may be identified by a unique (text) name
  * Entity PersistentObject are kept separate from UI PersistentObjects by naming convention
  * PersistentObjects are accessed by requesting them by name from the Context
  * PersistentObjects have attributes (which may be references to complex data structures)
  * Attributes of PersistentObjects 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 PersistentObject,
    configured in the Config file, or overridden at runtime for the
    duration of the Session

A user interface PersistentObject also has a display() method to display the PersistentObject 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 PersistentObject.

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


Class: P5EEx::Blue::PersistentObject

A PersistentObject 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: P5EEx::Blue::Exception::PersistentObject
 * Since:  0.01


Constructor Methods:

new()

The constructor is inherited from P5EEx::Blue::Service.

init()

The init() method is called from within the standard Service constructor. Common to all PersistentObject initializations, is the absorption of container attributes. ``Absorbable attributes'' from the persistent_object are copied from the container persistent_object to the initialized persistent_object.

    * Signature: init($named)
    * Param:     $named      {}   [in]
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    Sample Usage:
    $service->init(\%args);


Public Methods:

handle_event()

    * Signature: $handled = $self->handle_event($po_name,$event,@args);
    * Param:     $po_name    string
    * Param:     $event          string
    * Param:     @args           any
    * Return:    $handled        boolean
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $handled = $po->handle_event("app.table.sort","click","up",4,20);
    $handled = $po->handle_event("app.table","sort","down","last_name");

set_value()

    * Signature: $self->set_value($value);
    * Param:     $value          any
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $po->set_value("hello");
    $po->set_value(43);

get_value()

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

fget_value()

    * Signature: $formatted_value = $self->fget_value();
    * Signature: $formatted_value = $self->fget_value($format);
    * Param:     $format            string
    * Return:    $formatted_value   scalar
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $formatted_date = $date_persistent_object->fget_value();  # use default format
    $formatted_date = $date_persistent_object->fget_value("%Y-%m-%d"); # supply format

get_values()

    * 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:    P5EEx::Blue::Exception
    * Since:     0.01
    $values = $po->get_values();

set()

    * Signature: $self->set($attribute,$value);
    * Param:     $attribute      string
    * Param:     $value          any
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $po->set("last_name","Jones");

get()

    * 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:    P5EEx::Blue::Exception
    * Since:     0.01
    $last_name = $po->get("last_name");
    $is_adult = $po->get("adult_ind","Y");   # assume adult
    $is_adult = $po->get("adult_ind","Y",1); # assume adult, remember

delete()

    * Signature: $self->delete($attribute);
    * Param:     $attribute      string
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $po->delete("voter_id");

set_default()

    * Signature: $self->set_default($attribute,$default);
    * Param:     $attribute      string
    * Param:     $default        any
    * Return:    void
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $po->set_default("adult_ind","Y");

label()

    * Signature: $label = $self->label();
    * Signature: $label = $self->label($attrib);
    * Signature: $label = $self->label($attrib,$lang);
    * Param:     $po_name    string
    * Param:     $event          string
    * Param:     @args           any
    * Return:    $handled        boolean
    * Throws:    P5EEx::Blue::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")

values_labels()

    * Signature: ($values, $labels) = $self->values_labels();
    * Param:     void
    * Return:    $values       []
    * Return:    $labels       {}
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    ($values, $labels) = $gender_persistent_object->values_labels();
    # $values = [ "M", "F" ];
    # $labels = { "M" => "Male", "F" => "Female" };

labels()

    * Signature: $labels = $self->labels();
    * Signature: $labels = $self->labels($attribute);
    * Signature: $labels = $self->labels($attribute,$lang);
    * Param:     $attribute      string
    * Param:     $lang           string
    * Return:    $labels         {}
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $labels = $w->labels();
    $labels = $w->labels("names");
    $labels = $w->labels("","en");      # English
    $labels = $w->labels("","en_ca");   # Canadian English

dump()

    * Signature: $text = $self->dump();
    * Param:     void
    * Return:    $text           text
    * Throws:    P5EEx::Blue::Exception
    * Since:     0.01
    $text = $po->dump();

print()

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


Protected Methods:

service_type()

Returns 'PersistentObject';

    * Signature: $service_type = P5EEx::Blue::PersistentObject->service_type();
    * Param:     void
    * Return:    $service_type  string
    * Since:     0.01
    $service_type = $po->service_type();


ACKNOWLEDGEMENTS

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


SEE ALSO

P5EEx::Blue::Context, P5EEx::Blue::Service