NAME¶
KiokuDB::TypeMap::Entry::MOP - A KiokuDB::TypeMap entry for objects with a
metaclass.
VERSION¶
version 0.57
SYNOPSIS¶
KiokuDB::TypeMap->new(
entries => {
'My::Class' => KiokuDB::TypeMap::Entry::MOP->new(
intrinsic => 1,
),
},
);
DESCRIPTION¶
This typemap entry handles collapsing and expanding of Moose based objects.
It supports anonymous classes with runtime roles, the KiokuDB::Role::ID role.
Code for immutable classes is cached and performs several orders of magnitude
better, so make use of "make_immutable" in Moose::Meta::Class.
ATTRIBUTES¶
- intrinsic
- If true the object will be collapsed as part of its parent, without an
ID.
- check_class_versions
- If true (the default) then class versions will be checked on load and if
there is a mismatch between the stored version number and the current
version number, the version upgrade handler tables will be used to convert
the out of date entry.
- version_table
- class_version_table
- Tables of handlers.
See also KiokuDB::Role::Upgrade::Data and
KiokuDB::Role::Upgrade::Handlers::Table for convenience roles that do not
require a central table.
The first is a global version table (useful when the typemap entry is only
handling one class) and the second is a table of tables keyed by the class
name.
The tables are keyed by version number (as a string, "undef" and
"" are considered the same), and the value can be either a code
reference that processes the entry to bring it up to date, a hash
reference of overridden fields, or a string denoting a version number that
this version is equivalent to.
Version numbers have no actual ordinal meaning, they are taken as simple
string identifiers.
If we had 3 versions, 1.0, 1.1 and 2.0, where 1.1 is a minor update to the
class that requires no structural changes from 1.0, our table could be
written like this:
{
'1.0' => '1.1', # upgrading the data from 1.0 to 1.1 is a noop
'1.1' => sub {
my ( $self, %args ) = @_;
# manually convert the entry data
return $entry->clone(
class_version => '2.0',
prev => $entry,
data => ...,
),
},
}
When an object that was stored as version 1.0 is retrieved from the
database, and the current definition of the class has $VERSION 2.0, table
declares 1.0 is the same as 1.1, so we search for the handler for 1.1 and
apply it.
The resulting class has the version 2.0 which is the same as what we have
now, so this object can be thawed.
The callback is invoked with the following arguments:
- entry
- The entry to upgrade.
- from_version
- The key under which the handler was found (not necessarily the same as
"$entry->class_version").
- meta
- The Class::MOP::Class of the entry's class.
- linker
- The KiokuDB::Linker instance that is inflating this object.
Can be used to retrieve additional required objects (cycles are not a
problem but be aware that the objects might not be usable yet at the time
of the callback's invocation).
When a hash is provided as a handler it'll be used to create an entry like this:
$entry->derive(
%$handler,
data => {
%{ $entry->data },
%{ $handler->{data} || {} },
},
);
The field "class_version" is required, and "data" must
contain a hash:
KiokuDB->connect(
class_version_table => {
Foo => {
"0.02" => {
class_version => "0.03", # upgrade 0.02 to 0.03
data => {
a_new_field => "default_value",
},
},
},
},
);
- write_upgrades
- If true, after applying version upgrade handlers, the updated entry will
be written back to the database.
Defaults to false but might default to true in future versions (unless the
database is in readonly mode).
AUTHOR¶
Yuval Kogman <nothingmuch@woobling.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by Yuval Kogman, Infinity Interactive.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.