view release on metacpan or  search on metacpan

lib/DBIx/QuickORM/RowManager.pm  view on Meta::CPAN

package DBIx::QuickORM::RowManager;
use strict;
use warnings;

our $VERSION = '0.000022';

use Carp qw/confess croak/;
use Scalar::Util qw/weaken/;
use DBIx::QuickORM::Util qw/load_class/;

use DBIx::QuickORM::Affinity();

use DBIx::QuickORM::Connection::RowData qw{
    STORED
    PENDING
    DESYNC
    TRANSACTION
    ROW_DATA
};

use Object::HashBase qw{
    transactions
    connection
};

=pod

=encoding UTF-8

=head1 NAME

DBIx::QuickORM::RowManager - Base row manager mediating row state and storage.

=head1 DESCRIPTION

A row manager turns fetched/pending data sets into row objects and drives
their state transitions for insert, update, delete, and select against a
connection. It tracks the current transaction stack so newly created rows
are tagged with the active transaction.

This base class implements no caching: C<does_cache> is false and the cache
hooks are no-ops. L<DBIx::QuickORM::RowManager::Cached> subclasses it to add
a per-source identity cache.

=head1 SYNOPSIS

    my $mgr = DBIx::QuickORM::RowManager->new(connection => $connection);

    my $row = $mgr->select(source => $source, fetched => \%data);

=head1 ATTRIBUTES

=over 4

=item transactions

Arrayref of the connection's active transactions; defaults from the
connection. The last entry is the innermost active transaction.

=item connection

The owning connection (held weakly).

=back

=cut

sub init {
    my $self = shift;

    my $con = $self->{+CONNECTION} or croak "Connection was not provided";
    $self->{+TRANSACTIONS} //= $con->transactions;

    weaken($self->{+CONNECTION});
}

=pod

=head1 PUBLIC METHODS

=over 4

=item $bool = $mgr->does_cache

True if this manager keeps a row cache. False for the base class.

=item $mgr->cache($source, $row, $old_pk, $new_pk)

=item $row = $mgr->uncache($source, $row, $old_pk, $new_pk)

Cache hooks. No-ops in the base class; overridden by caching subclasses.

=cut

sub does_cache { 0 }

sub cache   { }
sub uncache { }

=pod

=item $row = $mgr->cache_lookup(source => $source, ...)

Look up a row in the cache by its parsed parameters. Returns the cached row
or undef.

=cut

sub cache_lookup {
    my $self = shift;
    return $self->do_lookup($self->parse_params({@_}));
}

=pod

=item $row = $mgr->do_cache_lookup($source, $fetched, $old_pk, $new_pk, $row)

Backend cache lookup. Returns undef in the base class; caching subclasses
override it.

=cut

sub do_cache_lookup {
    my $self = shift;
    my ($source, $fetched, $old_pk, $new_pk, $row) = @_;
    return undef;
}

=pod

=item $mgr->invalidate(source => $source, ...)

Mark a row's data invalid, both on any passed-in row and on the cached copy,
recording a reason (defaulting to the caller's file and line).