view release on metacpan or  search on metacpan

lib/Data/ObjectDriver.pm  view on Meta::CPAN

=item * offset

The offset to start at when limiting the result set.

Optional.

=item * fetchonly

A reference to an array of column names to fetch in the I<SELECT> statement.

Optional; the default is to fetch the values of all of the columns.

=item * for_update

If set to a true value, the I<SELECT> statement generated will include a
I<FOR UPDATE> clause.

=item * comment

A sql comment to watermark the SQL query.

=item * window_size

Used when requesting an iterator for the search method and selecting
a large result set or a result set of unknown size. In such a case,
no LIMIT clause is assigned, which can load all available objects into
memory. Specifying C<window_size> will load objects in manageable chunks.
This will also cause any caching driver to be bypassed for issuing
the search itself. Objects are still placed into the cache upon load.

This attribute is ignored when the search method is invoked in an array
context, or if a C<limit> attribute is also specified that is smaller than
the C<window_size>.

=back

=head2 Class->search(\@terms [, \%options ])

This is an alternative calling signature for the search method documented
above. When providing an array of terms, it allows for constructing complex
expressions that mix 'and' and 'or' clauses. For example:

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

Supported logic operators are: '-and', '-or', '-and_not', '-or_not'.

=head2 Class->add_trigger($trigger, \&callback)

Adds a trigger to all objects of class I<Class>, such that when the event
I<$trigger> occurs to any of the objects, subroutine C<&callback> is run. Note
that triggers will not occur for instances of I<subclasses> of I<Class>, only
of I<Class> itself. See TRIGGERS for the available triggers.

=head2 Class->call_trigger($trigger, [@callback_params])

Invokes the triggers watching class I<Class>. The parameters to send to the
callbacks (in addition to I<Class>) are specified in I<@callback_params>. See
TRIGGERS for the available triggers.

=head2 $obj->save

Saves the object I<$obj> to the database.

If the object is not yet in the database, I<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, I<save> will I<croak>.

Internally, I<save> calls I<update> for records that already exist in the
database, and I<insert> for those that don't.

=head2 $obj->remove

Removes the object I<$obj> from the database.

If an error occurs, I<remove> will I<croak>.

=head2 Class->remove(\%terms, \%args)

Removes objects found with the I<%terms>. So it's a shortcut of:

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

However, when you pass C<nofetch> option set to C<%args>, it won't
create objects with C<search>, but issues I<DELETE> SQL directly to
the database.

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

This might be much faster and useful for tables without Primary Key,
but beware that in this case B<Triggers won't be fired> because no
objects are instantiated.

=head2 Class->bulk_insert([col1, col2], [[d1,d2], [d1,d2]]);

Bulk inserts data into the underlying table.  The first argument
is an array reference of columns names as specified in install_properties

=head2 $obj->add_trigger($trigger, \&callback)

Adds a trigger to the object I<$obj>, such that when the event I<$trigger>
occurs to the object, subroutine C<&callback> is run. See TRIGGERS for the
available triggers. Triggers are invoked in the order in which they are added.

=head2 $obj->call_trigger($trigger, [@callback_params])

Invokes the triggers watching all objects of I<$obj>'s class and the object
I<$obj> specifically for trigger event I<$trigger>. The additional parameters
besides I<$obj>, if any, are passed as I<@callback_params>. See TRIGGERS for
the available triggers.

=head1 TRIGGERS

I<Data::ObjectDriver> provides a trigger mechanism by which callbacks can be
called at certain points in the life cycle of an object. These can be set on a
class as a whole or individual objects (see USAGE).

Triggers can be added and called for these events:

=over 4

=item * pre_save -> ($obj, $orig_obj)

Callbacks on the I<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 C<remove> the object.

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

=item * post_save -> ($obj, $orig_obj)

Callbaks on the I<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 B<NOT> called when you remove the
object.

=item * 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.

=item * post_load -> ($obj)

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

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

Note I<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.

=item * pre_search -> ($class, $terms, $args)

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

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

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

=over

The return values from your callbacks are ignored.

Note that the invocation of callbacks is the responsibility of the object
driver. If you implement a driver that does not delegate to
I<Data::ObjectDriver::Driver::DBI>, it is I<your> responsibility to invoke the
appropriate callbacks with the I<call_trigger> method.

=back

=back

=head1 PROFILING

For performance tuning, you can turn on query profiling by setting
I<$Data::ObjectDriver::PROFILE> to a true value. Or, alternatively, you can
set the I<DOD_PROFILE> environment variable to a true value before starting
your application.

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

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

Then see the documentation for I<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.


=head1 TRANSACTIONS


Transactions are supported by Data::ObjectDriver's default drivers. So each
Driver is capable to deal with transactional state independently. Additionally
<Data::ObjectDriver::BaseObject> class know how to turn transactions switch on
for all objects.

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.

=head2 Example

    ## 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