NAME

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

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: does_cache is false and the cache hooks are no-ops. DBIx::QuickORM::RowManager::Cached subclasses it to add a per-source identity cache.

SYNOPSIS

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

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

ATTRIBUTES

transactions

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

connection

The owning connection (held weakly).

PUBLIC METHODS

$bool = $mgr->does_cache

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

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

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

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

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

Look up a row in the cache. The row may be identified by fetched data, a primary key, or a row object; fetched data is not required. Returns the cached row or undef.

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

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

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). The row can be identified by a row object, fetched data, or a primary key; none of them is individually required.

$state = $mgr->_state(%params)

Build a row-state hashref, tagging it with the innermost active transaction.

$row = $mgr->_vivify($source, $state)

Construct a new row object of the appropriate row class wrapping fresh row data for the given state.

$row = $mgr->vivify(source => $source, ...)

Ensure there is a row object to work with for the given data, like Perl's own autovivification of a nested hash slot. This is a low-level primitive: it hands back a row to operate on before the caller necessarily knows whether that row is stored in the database.

If a row matching the data's primary key is already loaded, that existing row is returned as-is (it already carries known state, so it wins). Otherwise a new row is created with the supplied data as its pending (unsaved) state.

vivify does not query the database and does not guarantee the row exists there. On a cache hit the supplied data is not applied to the existing row; existing values win. If the supplied data would silently overwrite-and-lose information that way (a non-primary-key field whose value differs from the loaded row), a warning is emitted naming those fields. To change a loaded row, fetch it and call $row->update; to ensure a row exists in the database, use the connection's find_or_insert or update_or_insert helpers.

$mgr->_warn_vivify_discard($source, $fetched, $row)

Warn when vivify returns an already-loaded row and the supplied data would silently lose information: a non-primary-key field present in $fetched whose value differs from the loaded row's current value. Primary-key fields (the identity that found the row) and matching values are not reported.

$row = $mgr->insert(source => $source, fetched => \%data, ...)

$row = $mgr->update(source => $source, fetched => \%data, ...)

$row = $mgr->delete(source => $source, fetched => \%data, ...)

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

Apply the named storage operation to a row (creating one if needed), updating the cache accordingly, and return the row.

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

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

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

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

Backend state transitions invoked by the matching public method, after parameters have been parsed. They change the row's state and skip cache maintenance.

($source, $fetched, $old_pk, $new_pk, $row, $params) = $mgr->parse_params(\%params, %skip)

Validate and normalize the common operation parameters: confirm the source role, extract old/new primary keys from the fetched data, validate any passed-in row against the source and connection, and resolve a cached row. Returns the unpacked values plus the original params hashref.

SOURCE

The source code repository for DBIx::QuickORM can be found at https://github.com/exodist/DBIx-QuickORM.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/