/ 
MKDoc-SQL-0.4
/ MKDoc::SQL::Object

NAME

MKDoc::SQL::Object - Lightweight wrapper around SQL tables

DESCRIPTION

MKDoc::SQL::Object DOES NOT:

manage transactions
map complex structures on a database
manage database object garbage collection

MKDoc::SQL::Object DOES:

provide simple object CRUD subroutines
use prepare_cached statements wherever possible
use Cache::<*> for superior performance

Rather than trying to map objects to a relational database, this module simply turns relational database records into objects. These data objects can be extended to perform complex database operations.

Through mechanisms of inheritance and encapsulation, ideally all the horrible SQL should be localized in your data objects rather than all over your code. Hence, MKDoc::SQL::Object is not meant to be used 'as-is', it should be subclassed first.

MKDoc::SQL::Object will make use of any Cache::Memcached object, provided it lives in $::MKD_CACHE. This should provide a significant speed improvement while dropping database usage - at the expense of memory usage.

By convention, the DBI handle which MKDoc::SQL::Object uses should be stored in $::MKD_DBH. This object should be instanciated and connected before you start using MKDoc::SQL::Object objects.

MAPPING CONVENTION

Table name

The table name is derived from the object class name. For example, This::Is::Your::Class becomes this_is_your_class.

At worse, you can subclass $class->_table_name() to override this behavior.

Table columns

They are the same as your object attributes. Each table MUST have an object_id CHAR(255) column. You can store non persistent attributes in your object, however they must start with a dot, i.e.

$object->{'.wont_be_saved'} = 'test';

Be aware that such non-persistent attributes may be saved in the $::MKD_CACHE object though.

API

$class->new (%args);

Instanciates a new MKDoc::SQL::Object.

$class->load ($object_id);

Loads the object $object_id.

$self->object_id();

Returns the identifier of this object. If undef is returned, it means that the object is not yet persistent.

$self->save();

Saves the current object and returns it, unless $self->validate() doesn't return TRUE, in which case undef is returned instead.

$self->validate();

Returns TRUE.

This method is meant to be subclassed. It is invoked when save() is used. If $self->validate() doesn't return TRUE, then the object is not saved.

This allows you to perform extra checks on your objects to make sure they are OK before they are saved to the database.

$self->delete();

Deletes $self from the persistent store.