The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Class-PObject-2.05
River stage zero No dependents
++
/ Class::PObject::Driver

NAME

Class::PObject::Driver - Pobject driver specifications

SYNOPSIS

  package Class::PObject::Driver::my_driver;
  use base ('Class::PObject::Driver');

STOP!

If you just want to be able to use Class::PObject this manual is not for you. This is for those planning to write pobject drivers to support other database systems and storage devices.

If you just want to be able to use Class::PObject, you should refer to its online manual instead.

DESCRIPTION

Class::PObject::Driver is a base class for all the Object drivers.

Driver is another library Class::PObject uses only when disk access is necessary. So you can still use Class::PObject without any valid driver, but it won't be persistent object now, would it? If you want to creating on-the-fly, non-persistent objects, you are better off with Class::Struct.

Driver's certain methods will be invoked when load(), save(), count(), remove() and remove_all() methods of Class::PObject are called. They receive certain arguments, and are required to return certain values.

DRIVER SPECIFICATION

All the Class::PObject drivers should subclass Class::PObject::Driver, thus they all should begin with the following lines:

  package Class::PObject::Driver::my_driver;
  use base ('Class::PObject::Driver');

Exceptions may be DBI-related drivers, which are better off subclassing Class::PObject::Driver::DBI and DBM-related drivers, that are better off subclassing Class::PObject::Driver::DBM

Methods that Class::PObject::Driver defines are:

stash($key [,$value])

For storing data in the driver object safely. This is mostly useful for caching the return value of certain expensive operations that may be used over and over again. Do not try to store data specific to individual pobject classes, such as its columns, or datasource. Class::PObject will try to keep the driver object for as long as possible, even longer than current pobject's scope. So you really should stash() only the data that is less likely to depend on each pobject. Good example is stash()ing database connection.

For example, consider the following example:

  $dbh = DBI->connect(...);
  $self->stash('dbh', $dbh);    # WRONG!

  # ... later, in some other method:
  $dbh = $self->stash( 'dbh' );

The above example works as expected in some cases, since most projects use the same database connection to access several pobjects. So it's safe to associate the database handle with string 'dbh'.

However, sometimes several pobjects can use several database connections. In cases like these the above code will not work. Because the first created $dbh will also be used to synchronize the second object data. Instead, you should do something like this:

    $dbh = DBI->connect(...);
    $self->stash($dsn, $dbh);   # RIGHT!

    # ... later, in some other method:
    $dbh = $self->stash( $dsn );

$dsn in the above example is analogous to Name DBI attribute

errstr($message)

Whenever an error occurs within any of driver methods, you should always call this method with the error message, and return undef.

Class::PObject::Driver also defines new() - constructor. I don't think you should know anything about it. You won't deal with it directly. All the driver methods receive the driver object as the first argument.

WHAT SHOULD DRIVER DO?

Driver should inherit from either Class::PObject::Driver or Class::PObject::Driver::DBI, and override several methods with those relevant to the specific storage method/device.

All the driver methods accept at least 3 same arguments: $self - driver object, $pobject_name - name of the pobject and \%properties hashref of all the properties as passed to pobject() as the second (or first) argument in the form of a hashref.

These arguments are relevant to all the driver methods, unless noted otherwise.

On failure all the driver methods should pass the error message to errstr() method as the first and the only argument, and return undef.

On success they either should return a documented value (below), or boolean value whenever appropriate.

REQUIRED METHODS

If you are inheriting from Class::PObject::Driver, you should provide following methods of your own.

save($self, $pobject_name, \%properties, \%columns)

Whenever a user calls save() method of pobject, that method calls your driver's save() method.

In addition to standard arguments, save() accepts \%columns, which is a hash of column names and their respective values to be stored into disk.

It's the driver's obligation to figure whether the object should be stored, or updated.

New objects usually do not have id defined. This is a clue that it is a new object, thus you need to create a new ID and store the object into disk. If the id exists, it mostly means that object already should exist in the disk, and thus you need to update it.

On success save() should always return id of the object stored or updated.

load_ids($self, $pobject_name, \%properties, [\%terms [, \%arguments]])

When a user asks to load an object by calling load() method of pobject, driver's load_ids() method will be called by Class::PObject.

In addition to aforementioned 3 standard arguments, it may (or may not) receive \%terms - terms passed to initial pobject's load() method as the first argument and \%args - arguments passed to pobject's load() method as the second argument.

Should return an arrayref of object ids.

load($self, $object_name, \%properties, $id)

Is called to retrieve an individual object from the database. Along with standard arguments, it receives $id - ID of the record to be retrieved. On success should return hash-ref of column/value pairs.

remove($self, $object_name, \%properties, $id)

Called when remove() method is called on pobject.

In addition to standard arguments, it will receive $id - ID of the object that needs to be removed.

Your task is to delete the record from the disk, and return any true value indicating success.

OPTIONAL METHODS

You may choose not to override the following methods if you don't want to. In that case Class::PObject::Driver will try to implement these functionality based on other available methods.

So why are these methods required if their functionality can be achieved using other methods? Some drivers, especially RDBMS drivers, may perform these tasks much more efficiently by applying special optimizations to queries. In cases like these, you may want to override these methods. If you don't, default methods still perform as intended, but may not be as efficient.

remove_all($self, $object_name, \%properties [,\%terms])

Called when remove_all() method is called on pobject. It's job is to delete all the objects from the disk.

In addition to standard arguments, it may (or may not) receive \%terms, which is a set of key/value pairs. All the objects matching these terms should be deleted from the disk.

Should return true on success.

count($self, $object_name, \%properties, [,\%terms])

Counts number of objects stored in disk.

In addition to standard arguments, may (or may not) accept \%terms, which is a set of key/value pairs. If \%terms is present, only the count of objects matching these terms should be returned.

On success should return a digit, representing a count of objects.

SEE ALSO

Class::PObject::Driver::DBI

AUTHOR

Sherzod B. Ruzmetov <sherzodr@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003 by Sherzod B. Ruzmetov.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.