NAME

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;

    ## Shorthand constructor
    my $ingredient = Ingredient->new(recipe_id=> $recipe->id,
                                     name => 'Milk',
                                     quantity => 2);

DESCRIPTION

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.

METHODOLOGY

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:

1.

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.

2.

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 look 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.

3.

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.

4.

The caching layer, when it receives the object loaded in Step 3, will store the object in memcached.

5.

The object will be passed back to the caller. Subsequent lookups of that same object will come from the cache.

HOW IS IT DIFFERENT?

• 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_multi([
        [ 5, 3 ],
        [ 4, 2 ],
    ]);

    [
        undef,
        $object
    ]

    my $iter = Ingredient->search({ recipe_id => 5 });
    while (my $ingredient = $iter->()) {
        ...
    }

    my $iter = Ingredient->search({ recipe_id => 5 });
    while (my $ingredient = $iter->next()) {
        ...
    }

    my $iter = Ingredient->search([ { recipe_id => 5 },
        -or => { calories => { value => 300, op => '<' } } ]);
    while (my $ingredient = $iter->()) {
        ...
    }

  my @obj = Class->search(\%terms, \%args);
  for my $obj (@obj) {
      $obj->remove;
  }

  ## issues "DELETE FROM tbl WHERE user_id = 2"
  Class->remove({ user_id => 2 }, { nofetch => 1 });

TRIGGERS

Triggers can be added and called for these events:

• pre_save -> ($obj, $orig_obj)

  Callbacks on the pre_save trigger are called when the object is about to be saved to the database. For example, use this callback to translate special code strings into numbers for storage in an integer column in the database. Note that this hook is also called when you "remove" the object.

  Modifications to $obj will affect the values passed to subsequent triggers and saved in the database, but not the original object on which the save method was invoked.

• post_save -> ($obj, $orig_obj)

  Callbaks on the post_save triggers are called after the object is saved to the database. Use this trigger when your hook needs primary key which is automatically assigned (like auto_increment and sequence). Note that this hooks is NOT called when you remove the object.

• pre_insert/post_insert/pre_update/post_update/pre_remove/post_remove -> ($obj, $orig_obj)

  Those triggers are fired before and after $obj is created, updated and deleted.

• post_load -> ($obj)

  Callbacks on the post_load trigger are called when an object is being created from a database query, such as with the lookup and search class methods. For example, use this callback to translate the numbers your pre_save callback caused to be saved back into string codes.

  Modifications to $obj will affect the object passed to subsequent triggers and returned from the loading method.

  Note pre_load should only be used as a trigger on a class, as the object to which the load is occurring was not previously available for triggers to be added.

• pre_search -> ($class, $terms, $args)

  Callbacks on the pre_search trigger are called when a content addressed query for objects of class $class is performed with the search method. For example, use this callback to translate the entry in $terms for your code string field to its appropriate integer value.

  Modifications to $terms and $args will affect the parameters to subsequent triggers and what objects are loaded, but not the original hash references used in the search query.

  Note pre_search should only be used as a trigger on a class, as search is never invoked on specific objects.

PROFILING

To obtain the profile statistics, get the global Data::ObjectDriver::Profiler instance:

    my $profiler = Data::ObjectDriver->profiler;

Then see the documentation for Data::ObjectDriver::Profiler to see the methods on that class.

In some applications there are phases of execution in which no I/O operations should occur, but sometimes it's difficult to tell when, where, or if those I/O operations are happening. One approach to surfacing these situations is to set, either globally or locally, the $Data::ObjectDriver::RESTRICT_IO flag. If set, this will tell Data::ObjectDriver to die with some context rather than executing network calls for data.

TRANSACTIONS

In the case of a global transaction all drivers used during this time are put in a transactional state until the end of the transaction.

    ## start a transaction
    Data::ObjectDriver::BaseObject->begin_work;

    $recipe = Recipe->new;
    $recipe->title('lasagnes');
    $recipe->save;

    my $ingredient = Ingredient->new;
    $ingredient->recipe_id($recipe->recipe_id);
    $ingredient->name("more layers");
    $ingredient->insert;
    $ingredient->remove;

    if ($you_are_sure) {
        Data::ObjectDriver::BaseObject->commit;
    }
    else {
        ## erase all trace of the above
        Data::ObjectDriver::BaseObject->rollback;
    }

    ## example coming from the test suite
    __PACKAGE__->install_properties({
        columns => [ 'recipe_id', 'partition_id', 'title' ],
        datasource => 'recipes',
        primary_key => 'recipe_id',
        driver => Data::ObjectDriver::Driver::Cache::Cache->new(
            cache => Cache::Memory->new,
            fallback => Data::ObjectDriver::Driver::DBI->new(
                dsn      => 'dbi:SQLite:dbname=global.db',
                reuse_dbh => 1,  ## be sure that the corresponding dbh is shared
            ),
        ),
    });

EXAMPLES

    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;

FORK SAFETY

SUPPORTED DATABASES

• MySQL is well supported and has been heavily tested.
• PostgreSQL has been used in production and should just work, too.
• SQLite is supported, but YMMV depending on the version. This is the backend used for the test suite.
• Oracle support has been added in 0.06

LICENSE

AUTHOR & COPYRIGHT