Class::PObject::Driver - Pobject driver specifications
package Class::PObject::Driver::my_driver; use base ('Class::PObject::Driver');
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.
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 create on-the-fly, non-persistent objects, you are better off with Class::Struct
Driver's certain methods will be invoked when
remove_all() methods of Class::PObject are called. They receive certain arguments, and are required to return certain values.
All the Class::PObject drivers should subclass Class::PObject::Driver, thus they all should begin with the following lines or equivalent
package Class::PObject::Driver::my_driver; use base ("Class::PObject::Driver");
Methods that Class::PObject::Driver defines are:
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. Good example is stash()ing database connection.
For example, consider the following example:
$dbh = DBI->connect(...); $self->stash($dsn, $dbh); # ... later, in some other method: $dbh = $self->stash( 'dbh' );
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.
All the driver methods accept at least three same arguments:
$self - driver object,
$class_name - name of the class 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.
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 turn.
In addition to standard arguments,
\%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.
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)
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.
drop_datasource($self, $object_name, \%properties)
drop_datasource() method is called on pobject. Its task is to remove the storage device allocated for storing this particular object. On success should return 1.
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.
Class::PObject::Driver provides several utility methods for you to ease the serialization of data.
These methods consult
serializer attribute of pobject declaration to discover what type of serialization to be used. Available attributes are, xml, which serializes the data into an XML document using XML::Dumper; dumper, which serializes the data into pretty-printed string using Data::Dumper; storable, which serializes the data using Stroable.
Default is storable, for backward compatibility.
Following are the specs of these methods.
freeze($self, $object_name, \%properties, $hashref)
In addition to standard arguments, accepts
$hashref, which is an in-memory perl Hash table needed to be serialized into a string.
Should return serialized string on success, undef otherwise.
thaw($self, $object_name, \%properties, $datastr)
Should reverse the serialization process performed by
In addition to standard arguments, accepts
$datastr, which is a serialized string needed to be de-serialized into in-memory Perl data.
For author and copyright information refer to Class::PObject's online manual.