NAME

ePortal::ThePersistent::Base - Base class for storage objects

SYNOPSYS

This package is used for handy work with database objects: SELECT, UPDATE, INSERT, DELETE.

METHODS

new()

Object constructor. Parameters:

• Attributes

  HASHREF or ARRAYREF to attributes description hashes. You can also add attributes later with add_attribute().

• Where

  Obligatory WHERE clause for SQL statements. Added to every SQL statement.

• other parameters

  See Storage related variables for details.

Returns new blessed and initialized object.

initialize()

Object initialization block, called from new() constructor. initialize() is used for attributes initialization. It is the place to override in inherited modules to add its own attributes.

initialize() calls datastore() with all passed parameters.

Parameters are the same as for object constructor. Only Attributes parameter is used internally.

Returns none.

datastore()

It is the place to initialize database related things like DBH connection. Called from new() constructor.

Should not be called directly.

Parameters are the same as for object constructor. See Storage related variables for more details.

Returns newly created database handle.

attribute_object()

Returns named attribute object.

• attribute name

  Name of attribute to return.

attribute()

Returns named attribute parameters as hash. In scalar context returns hash ref.

If attribute does not exists then undef is returned. This method is used to check attribute existance.

• attribute name

  Name of attribute to return.

attributes()

Returns names of ALL attributes of the object as array.

attributes_id()

Returns names of TD attributes of the object as array.

attributes_notid()

Returns names of TD attributes of the object as array.

attributes_storable()

Returns names of attributes of the object as array except Temporary or Transient attributes.

add_attribute()

Add an attribute to the object. Attribute information is used when SQL statement is constructed or when attribute datatype is needed to know.

There is two modes of parameters passing:

• name

• type

  Valid values are ID, Persistent, Temporary or Transient. Attribute type is determined by first character ignoring case.

• datatype

  Data type of attribute. See Supported Data Types for details.

• arguments

  Optional. Arguments to be passed to the data type constructor

The second mode is more powerful:

• name

• hashref

  HASHREF if a hash with a description of attribute type, datatype parameters, and visualization parameters. See Attribute Parameters for details.

Returns none.

value()

Get or set the value of attribute.

• name

  Name of attribute

• new value

  Optional value of attribute to set.

Returns new or current value of attribute.

clear()

Clears (undefs) the fields of the object. This method calls value() directly. No overloaded value() methods will be triggered.

Returns none.

update()

Updates existing object in the datastore.

Returns True if UPDATE was successful.

save()

Saves the object to the data store (insert or update).

Returns:

1 if the object did previously exist in the datastore

0 if the object did not previously exist

undef on error

restore()

Restores the object from the data store.

• @id

  Unique identifier assigned to the object

Returns True if the object was successfully restored and False if the object is not found.

restore_all()

Restores all the objects from the data store and optionally sorted.

• order_by

  Optional. Sort expression for the objects in the form of an SQL ORDER BY clause.

Returns none.

restore_next()

Restores the next object from the data store that matches the query expression in the previous restore_where or restore_all method calls.

Returns True if an object was restored and False if an object was not restored - no more objects to restore

data()

Gets/Sets all data fields of an object.

• $href

  A reference to a hash of object data. Hash keys are named of attributes.

Returns $href - a reference to a hash of object data

insert()

Inserts new object into datastore. If ID attribute is auto_increment then newly generated number for ID is stored in object via _id().

Returns True if INSERT was successful.

delete()

Delete the object.

• @id

  Optional. ID of the object to delete. If omitted then current object is deleted.

Returns True if DELETE was successful.

delete_where()

Conditionaly deletes objects.

Note: Obligatory WHERE clause will be added

• where

  WHERE clause

• binds

  Array of values for binding.

Returns True if DELETE was successful. May be return a number of deleted rows?

restore_where()

Execute conditional SELECT statement.

• where

  WHERE clause for SQL statement. It may be arrayref, than every array element will be ANDed.

• skip_attributes

  ARRAYREF. Do not SELECT these attributes.

  ID attributes always included in SELECT.

  Do not use both skip_attributes and only_attributes!

• only_attributes

  ARRAYREF. Include in SELECT only these attributes.

  ID attributes always included in SELECT.

  Do not use both skip_attributes and only_attributes!

• count_rows

  Just count(*) with supplied WHERE clause and return it.

• order_by

  ORDER BY clause.

• group_by

  group_by clause

• limit_rows

  Limit a number of rows returned from server

• limit_offset

  Limit starting row returned from server. Rows counted from 1.

• bind

  ARRAYREF of bind values for SQL statement.

• other parameter

  Any other parameter passed is treated as condition to WHERE clause if an attribute exists with this name. Undefined parameters are WHEREd to NULL but empty values that eq to '' are omitted.

add_where()

Helper function. Adds another WHERE condition possible ANDed with existing one.

• hashref

  Parameters hashref. Constructed WHERE clause will be added to {where} key of this hash.

• binds

  Array of bind values. These values will be added to {bind} key of parameters hash.

Returns none.

where()

Get/Set obligatory WHERE clause for the object.

• where

  WHERE clause. Bindings are not supported.

Returns ñurrent where clause

validate()

Validates internal data before insert of update. This method does nothing and is subject to override in inherited modules.

• beforeinsert

  True if called from insert(), False if called from update()

Returns undef on success or human readable error message if the object is not valid.

PRIVATE METHODS

_check_dbi_error()

Checks for errors in DBI and croaks if an error has occurred.

• error string

  Error string prepended to the DBI error message

_get_dbh()

Returns the handle of the database.

• new dbh

_id()

Gets/Sets the ID of the object. ID may be an array.

check_id()

Checks that the ID of the object is valid. That is every ID attribute is defined.

SUPPORTED DATA TYPES

VarChar

Number

DateTime

Date

YesNo

INTERNAL VARIABLES

Storage related variables

• $self->{Table}

  Name of database table.

• $self->{DBH}

  DBI database handle.

• $self->{STH}

  Initialized internally. Database statement handle. Used for active SELECT statements.

• $self->{dbi_xxx}

  {dbi_source}, {dbi_user}, {dbi_password} - three parameters to create new DBH. This is opposite to {DBH} parameter.

• $self->{CreatedDBH}

  Initialized internally. True if DBH is created by myself and we need to do disconnect(). This happens when dbi_xxx parameters are passed to constructor.

  If ready to use DBH is passed to constructor then {CreatedDBH} is False.

• $self->{AutoCommit}

  True if commit() is needed after every update statement.

• $self->{SQL}

  This is opposite to {Table}. When {SQL} is passed to constructor it is used for SELECT statement and object become read-only.

• $self->{Where}

  Obliagtory WHERE clause added to every SQL statement

• $self->{Bind}

  Obligatory arrayref of bind values to add to every SQL request

• $self->{OrderBy}

  ORDER BY clause by default if not passed other to restore_where()

• $self->{GroupBy}

  GROUP BY clause added to every SELECT statement with restore_where()

Attributes

• $self->{MetaData}{attr}

  Attribute object. Every attribute object is persent here. Attributes names are in lower case.

• $self->{Parameters}{attr}

  Attribute parameters.

• $self->{IdAttributes}->[]

  Array of names of ID attributes.

• $self->{Attributes}->[]

  Array of names of Persistent attributes.

• $self->{TempAttributes}->[]

  Array of names of Temporary attributes. Temporary attributes are not stored in database.

Other variables

• $self->{Where}

  Obligatory WHERE clause. These conditions are added to WHERE clause for every restore_xxx().

• $self->{CountRows}

  When {CountRows} is True then all SELECT fields are replaced to count(*) field and consctucted WHERE clause is added. This feature is used in restore_where()

ATTRIBUTE PARAMETERS

A lot of attribute parameters are used for description, detalization and visualization.

• type

  [ ID | Persistent | Transient(Temporary) ]

  This is field persistent state. Only first 1 character is significant. Default is Persistent.

• dtype

  Data type. Must correlate with any of supported datatypes. Default is Varchar.

• order

  [1..9]. All fields are sorted by this key before table creation process. Default is 5. Deprecated. Use arrays for list of attributes.

• label

  This label is used to make labels is dialogs.

• header

  This is used for header of column in a table.

• maxlength

  Maximum length of the field. Default is 9 for Number, 255 for Varchar.

• scale

  Scale of a number. Number of digits after point.

• fieldtype

  [textfield | popup_menu | textarea | YesNo | date | datetime]

  Type of dialog item used for this field. Default is textfield.

• size

  Size of field in dialog boxes in characters.

• labels,values

  Used for popup_menu field type. values may be a coderef declared as sub {}. The object ($self) passed to this sub as first parameter.

• auto_increment

  This Number attribute is auto incremented by database during INSERT operation.

• popup_menu

  sub{ my $self=shift; ... return (\@val,\%lab);}

  Coderef used to fill up popup_menu parameters.

• columns,rows

  Used for textarea field type

• description

  Not used

cpanm ePortal::Utils

perl -MCPAN -e shell
install ePortal::Utils