| 1 | package Class::DBI::Storable; | ||
| 2 | our $VERSION = '0.01'; | ||
| 3 | |||
| 4 | =pod | ||
| 5 | |||
| 6 | =head1 NAME | ||
| 7 | |||
| 8 | Class::DBI::Storable - Mixin Storable hooks to freeze and thaw objects | ||
| 9 | |||
| 10 | =head1 VERSION | ||
| 11 | |||
| 12 | Version 0.01 | ||
| 13 | |||
| 14 | =head1 SYNOPSIS | ||
| 15 | |||
| 16 | package My::Class; | ||
| 17 | use base 'Class::DBI'; | ||
| 18 | use Class::DBI::Storable; | ||
| 19 | |||
| 20 | package main; | ||
| 21 | use Storable qw(freeze thaw dclone); | ||
| 22 | |||
| 23 | my $obj = My::Class->retrieve($id); | ||
| 24 | |||
| 25 | dclone($obj); # Produces a warning | ||
| 26 | |||
| 27 | =head1 DESCRIPTION | ||
| 28 | |||
| 29 | Class::DBI attempts to maintain the the uniqueness of objects | ||
| 30 | in memory. Serializers such as Storable will generally violate | ||
| 31 | this constraint when an object is frozen and thawed. | ||
| 32 | |||
| 33 | This mixin module makes your Class::DBI objects serializable with | ||
| 34 | Storable. Only the primary keys are serialized and the objects | ||
| 35 | is thawed using "retrieve" on the appropriate CDBI class. | ||
| 36 | |||
| 37 | The Storable hooks carp if there are unsaved changes to the object | ||
| 38 | being frozen or if you attempt to dclone a object. | ||
| 39 | Using dclone on a CDBI object doesn't really make sense. | ||
| 40 | |||
| 41 | STORABLE_freeze and STORABLE_attach the only methods. They will be | ||
| 42 | called automatically by Storable. | ||
| 43 | |||
| 44 | =head2 Are You Sure This Is A Good Idea? | ||
| 45 | |||
| 46 | No. | ||
| 47 | |||
| 48 | This module exists to try to make Class::DBI and Storable work | ||
| 49 | together acceptably. It's existence is not to be construed as | ||
| 50 | a recommendation of the practice. | ||
| 51 | |||
| 52 | =head1 DIAGNOSTICS | ||
| 53 | |||
| 54 | Storable::dclone($cdbi_object) will emit: | ||
| 55 | |||
| 56 | "Warning, cloning a Class::DBI object of class <class name>" | ||
| 57 | |||
| 58 | This is to help catch inadvertent uses of dclone and to discourage it's use. | ||
| 59 | (The warning can be suppressed with the $CloneCarp package variable) | ||
| 60 | |||
| 61 | If Storable::freeze is called of an object with unsaved changes then: | ||
| 62 | |||
| 63 | "Warning, freezing <class name> discards unsaved changes" | ||
| 64 | |||
| 65 | It also calls the discard_changes method from Class::DBI which may | ||
| 66 | throw an exception. | ||
| 67 | (Suppress the warning with the package variable $FreezeCarp) | ||
| 68 | |||
| 69 | =head1 DEPENDENCIES | ||
| 70 | |||
| 71 | Storable 2.14 or newer | ||
| 72 | |||
| 73 | =head1 BUGS AND LIMITATIONS | ||
| 74 | |||
| 75 | There are no known bugs in this module. | ||
| 76 | |||
| 77 | Please report problems to the author directly or via RT | ||
| 78 | |||
| 79 | =head1 SEE ALSO | ||
| 80 | |||
| 81 | L<Class::DBI> in particular "Uniqueness of Objects in Memory", L<Storable> | ||
| 82 | |||
| 83 | =head1 AUTHOR | ||
| 84 | |||
| 85 | Brad Bowman E<lt>cpan@bereft.netE<gt> | ||
| 86 | |||
| 87 | =head1 LICENCE AND COPYRIGHT | ||
| 88 | |||
| 89 | Copyright (c) 2005 Brad Bowman E<lt>cpan@bereft.netE<gt>. All rights reserved. | ||
| 90 | |||
| 91 | This module is free software; you can redistribute it and/or | ||
| 92 | modify it under the same terms as Perl itself. | ||
| 93 | |||
| 94 | This program is distributed in the hope that it will be useful, | ||
| 95 | but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 96 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | ||
| 97 | |||
| 98 | =cut | ||
| 99 | |||
| 100 | use strict; | ||
| 101 | use Storable qw(nfreeze thaw); # XXX Storable must be 2.14 or greater | ||
| 102 | use Carp qw(croak carp); | ||
| 103 | |||
| 104 | # The hooks can be imported or inherited | ||
| 105 | use Exporter; | ||
| 106 | our @EXPORT = qw(STORABLE_freeze STORABLE_attach); | ||
| 107 | |||
| 108 | our $CloneCarp = 1; | ||
| 109 | our $FreezeCarp = 1; | ||
| 110 | |||
| 111 | sub STORABLE_freeze { | ||
| 112 | my ($self, $cloning) = @_; | ||
| 113 | |||
| 114 | if ($cloning) { | ||
| 115 | if($CloneCarp) { | ||
| 116 | carp "Warning, cloning a Class::DBI object of class ", ref($self); | ||
| 117 | } | ||
| 118 | return; | ||
| 119 | } | ||
| 120 | |||
| 121 | if ($self->is_changed) { | ||
| 122 | if($FreezeCarp) { | ||
| 123 | carp "Warning, freezing ", ref($self), " discards unsaved changes"; | ||
| 124 | } | ||
| 125 | $self->discard_changes; # May throw an exception | ||
| 126 | } | ||
| 127 | |||
| 128 | return nfreeze([ $self->id ]); | ||
| 129 | } | ||
| 130 | |||
| 131 | sub STORABLE_attach { | ||
| 132 | my ($class, $cloning, $serialized) = @_; | ||
| 133 | |||
| 134 | return if ($cloning); | ||
| 135 | |||
| 136 | my @id = @{ thaw($serialized) }; | ||
| 137 | |||
| 138 | my %key_values; | ||
| 139 | @key_values{ $class->columns('Primary') } = @id; | ||
| 140 | |||
| 141 | return $class->retrieve(%key_values); | ||
| 142 | } | ||
| 143 | |||
| 144 | 1; |