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

- NAME
- SYNOPSYS
- METHODS

- `new()`
- `initialize()`
- `datastore()`
- `attribute()`
- `attributes()`
- `add_attribute()`
- `value()`
- `clear()`
- `update()`
- `save()`
- `restore()`
- `restore_all()`
- `restore_next()`
- `data()`
- `insert()`
- `delete()`
- `delete_where()`
- `restore_where()`
- `add_where()`
- `where()`
- `validate()`

- PRIVATE METHODS

- `_check_dbi_error()`
- `dbh()`
- `_id()`
- `check_id()`

- SUPPORTED DATA TYPES

- VarChar
- Number
- DateTime
- Date
- YesNo

- INTERNAL VARIABLES

- Storage related variables
- Attributes
- Other variables

- ATTRIBUTE PARAMETERS

# 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()`

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.

## `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.

- 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

## `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_username}, {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->{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.

- 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