NAME
Data::ObjectDriver - Simple, transparent data interface, with caching
SYNOPSIS
## Set up your database driver code.
package FoodDriver;
sub driver {
Data::ObjectDriver::Driver::DBI->new(
dsn => 'dbi:mysql:dbname',
username => 'username',
password => 'password',
}
## Set up the classes for your recipe and ingredient objects.
package Recipe;
use base qw( Data::ObjectDriver::BaseObject );
__PACKAGE__->install_properties(
columns => [ 'recipe_id', 'title' ],
datasource => 'recipe',
primary_key => 'recipe_id',
driver => FoodDriver->driver,
);
package Ingredient;
use base qw( Data::ObjectDriver::BaseObject );
__PACKAGE__->install_properties(
columns => [ 'ingredient_id', 'recipe_id', 'name', 'quantity' ],
datasource => 'ingredient',
primary_key => [ 'recipe_id', 'ingredient_id' ],
driver => FoodDriver->driver,
);
## And now, use them!
my $recipe = Recipe->new;
$recipe->title('Banana Milkshake');
$recipe->save;
my $ingredient = Ingredient->new;
$ingredient->recipe_id($recipe->id);
$ingredient->name('Bananas');
$ingredient->quantity(5);
$ingredient->save;
## Needs more bananas!
$ingredient->quantity(10);
$ingredient->save;DESCRIPTION
Data::ObjectDriver is an object relational mapper, meaning that it maps object-oriented design concepts onto a relational database.
It's inspired by, and descended from, the MT::ObjectDriver classes in Six Apart's Movable Type and TypePad weblogging products. But it adds in caching and partitioning layers, allowing you to spread data across multiple physical databases, without your application code needing to know where the data is stored.
It's currently considered ALPHA code. The API is largely fixed, but may seen some small changes in the future. For what it's worth, the likeliest area for changes are in the syntax for the search method, and would most likely not break much in the way of backwards compatibility.
METHODOLOGY
Data::ObjectDriver provides you with a framework for building database-backed applications. It provides built-in support for object caching and database partitioning, and uses a layered approach to allow building very sophisticated database interfaces without a lot of code.
You can build a driver that uses any number of caching layers, plus a partitioning layer, then a final layer that actually knows how to load data from a backend datastore.
For example, the following code:
my $driver = Data::ObjectDriver::Driver::Cache::Memcached->new(
cache => Cache::Memcached->new(
servers => [ '127.0.0.1:11211' ],
),
fallback => Data::ObjectDriver::Driver::Partition->new(
get_driver => \&get_driver,
),
);creates a new driver that supports both caching (using memcached) and partitioning.
It's useful to demonstrate the flow of a sample request through this driver framework. The following code:
my $ingredient = Ingredient->lookup([ $recipe->recipe_id, 1 ]);would take the following path through the Data::ObjectDriver framework:
The caching layer would look up the object with the given primary key in all of the specified memcached servers.
If the object was found in the cache, it would be returned immediately.
If the object was not found in the cache, the caching layer would fall back to the driver listed in the fallback setting: the partitioning layer.
The partitioning layer does not know how to look up objects by itself--all it knows how to do is to give back a driver that does know how to loko up objects in a backend datastore.
In our example above, imagine that we're partitioning our ingredient data based on the recipe that the ingredient is found in. For example, all of the ingredients for a "Banana Milkshake" would be found in one partition; all of the ingredients for a "Chocolate Sundae" might be found in another partition.
So the partitioning layer needs to tell us which partition to look in to load the ingredients for $recipe->recipe_id. If we store a partition_id column along with each $recipe object, that information can be loaded very easily, and the partitioning layer will then instantiate a DBI driver that knows how to load an ingredient from that recipe.
Using the DBI driver that the partitioning layer created, Data::ObjectDriver can look up the ingredient with the specified primary key. It will return that key back up the chain, giving each layer a chance to do something with it.
The caching layer, when it receives the object loaded in Step 3, will store the object in memcached.
The object will be passed back to the caller. Subsequent lookups of that same object will come from the cache.
HOW IS IT DIFFERENT?
Data::ObjectDriver differs from other similar frameworks (e.g. Class::DBI) in a couple of ways:
It has built-in support for caching.
It has built-in support for data partitioning.
Drivers are attached to classes, not to the application as a whole.
This is essential for partitioning, because your partition drivers need to know how to load a specific class of data.
But it can also be useful for caching, because you may find that it doesn't make sense to cache certain classes of data that change constantly.
The driver class != the base object class.
All of the object classes you declare will descend from Data::ObjectDriver::BaseObject, and all of the drivers you instantiate or subclass will descend from Data::ObjectDriver itself.
This provides a useful distinction between your data/classes, and the drivers that describe how to act on that data, meaning that an object based on Data::ObjectDriver::BaseObject is not tied to any particular type of driver.
USAGE
Class->lookup($id)
Looks up/retrieves a single object with the primary key $id, and returns the object.
$id can be either a scalar or a reference to an array, in the case of a class with a multiple column primary key.
Class->lookup_multi(\@ids)
Looks up/retrieves multiple objects with the IDs \@ids, which should be a reference to an array of IDs. As in the case of lookup, an ID can be either a scalar or a reference to an array.
Returns a reference to an array of objects in the same order as the IDs you passed in. Any objects that could not successfully be loaded will be represented in that array as an undef element.
So, for example, if you wanted to load 2 objects with the primary keys [ 5, 3 ] and [ 4, 2 ], you'd call lookup_multi like this:
Class->lookup_multi([
[ 5, 3 ],
[ 4, 2 ],
]);And if the first object in that list could not be loaded successfully, you'd get back a reference to an array like this:
[
undef,
$object
]where $object is an instance of Class.
Class->search(\%terms [, \%options ])
Searches for objects matching the terms %terms. In list context, returns an array of matching objects; in scalar context, returns a reference to a subroutine that acts as an iterator object, like so:
my $iter = Ingredient->search({ recipe_id => 5 });
while (my $ingredient = $iter->()) {
...
}The keys in %terms should be column names for the database table modeled by Class (and the values should be the desired values for those columns).
%options can contain:
sort
The name of a column to use to sort the result set.
Optional.
direction
The direction in which you want to sort the result set. Must be either
ascendordescend.Optional.
limit
The value for a LIMIT clause, to limit the size of the result set.
Optional.
offset
The offset to start at when limiting the result set.
Optional.
fetchonly
A reference to an array of column names to fetch in the SELECT statement.
Optional; the default is to fetch the values of all of the columns.
$obj->save
Saves the object $obj to the database.
If the object is not yet in the database, save will automatically generate a primary key and insert the record into the database table. Otherwise, it will update the existing record.
If an error occurs, save will croak.
$obj->remove
Removes the object $obj from the database.
If an error occurs, save will croak.
EXAMPLES
A Partitioned, Caching Driver
package Ingredient;
use strict;
use base qw( Data::ObjectDriver::BaseObject );
use Data::ObjectDriver::Driver::DBI;
use Data::ObjectDriver::Driver::Partition;
use Data::ObjectDriver::Driver::Cache::Cache;
use Cache::Memory;
use Carp;
our $IDs;
__PACKAGE__->install_properties({
columns => [ 'ingredient_id', 'recipe_id', 'name', 'quantity', ],
datasource => 'ingredients',
primary_key => [ 'recipe_id', 'ingredient_id' ],
driver =>
Data::ObjectDriver::Driver::Cache::Cache->new(
cache => Cache::Memory->new( namespace => __PACKAGE__ ),
fallback =>
Data::ObjectDriver::Driver::Partition->new(
get_driver => \&get_driver,
pk_generator => \&generate_pk,
),
),
});
sub get_driver {
my($terms) = @_;
my $recipe;
if (ref $terms eq 'HASH') {
my $recipe_id = $terms->{recipe_id}
or Carp::croak("recipe_id is required");
$recipe = Recipe->lookup($recipe_id);
} elsif (ref $terms eq 'ARRAY') {
$recipe = Recipe->lookup($terms->[0]);
}
Carp::croak("Unknown recipe") unless $recipe;
Data::ObjectDriver::Driver::DBI->new(
dsn => 'dbi:mysql:database=cluster' . $recipe->cluster_id,
username => 'foo',
pk_generator => \&generate_pk,
);
}
sub generate_pk {
my($obj) = @_;
$obj->ingredient_id(++$IDs{$obj->recipe_id});
1;
}
1;LICENSE
Data::ObjectDriver is free software; you may redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR & COPYRIGHT
Except where otherwise noted, Data::ObjectDriver is Copyright 2005 Six Apart, cpan@sixapart.com. All rights reserved.