Cleaner error message for using source() without required argument
[dbsrgits/DBIx-Class.git] / lib / DBIx / Class / ResultSourceHandle.pm
1 package DBIx::Class::ResultSourceHandle;
2
3 use strict;
4 use warnings;
5
6 use base qw/DBIx::Class/;
7
8 use Storable qw/nfreeze thaw/;
9 use DBIx::Class::Exception;
10 use Try::Tiny;
11
12 use namespace::clean;
13
14 use overload
15     q/""/ => sub { __PACKAGE__ . ":" . shift->source_moniker; },
16     fallback => 1;
17
18 __PACKAGE__->mk_group_accessors('simple' => qw/schema source_moniker _detached_source/);
19
20 # Schema to use when thawing.
21 our $thaw_schema;
22
23 =head1 NAME
24
25 DBIx::Class::ResultSourceHandle - Serializable pointers to ResultSource instances
26
27 =head1 DESCRIPTION
28
29 Currently instances of this class are used to allow proper serialization of
30 L<ResultSources|DBIx::Class::ResultSource> (which may contain unserializable
31 elements like C<CODE> references).
32
33 Originally this module was used to remove the fixed link between
34 L<Rows|DBIx::Class::Row>/L<ResultSets|DBIx::Class::ResultSet> and the actual
35 L<result source objects|DBIx::Class::ResultSource> in order to obviate the need
36 of keeping a L<schema instance|DBIx::Class::Schema> constantly in scope, while
37 at the same time avoiding leaks due to circular dependencies. This is however
38 no longer needed after introduction of a proper mutual-assured-destruction
39 contract between a C<Schema> instance and its C<ResultSource> registrants.
40
41 =head1 METHODS
42
43 =head2 new
44
45 =cut
46
47 sub new {
48   my ($class, $args) = @_;
49   my $self = bless $args, ref $class || $class;
50
51   unless( ($self->{schema} || $self->{_detached_source}) && $self->{source_moniker} ) {
52     my $err = 'Expecting a schema instance and a source moniker';
53     $self->{schema}
54       ? $self->{schema}->throw_exception($err)
55       : DBIx::Class::Exception->throw($err)
56   }
57
58   $self;
59 }
60
61 =head2 resolve
62
63 Resolve the moniker into the actual ResultSource object
64
65 =cut
66
67 sub resolve {
68   return $_[0]->{schema}->source($_[0]->source_moniker) if $_[0]->{schema};
69
70   $_[0]->_detached_source || DBIx::Class::Exception->throw( sprintf (
71     # vague error message as this is never supposed to happen
72     "Unable to resolve moniker '%s' - please contact the dev team at %s",
73     $_[0]->source_moniker,
74     'http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class.pm#GETTING_HELP/SUPPORT',
75   ), 'full_stacktrace');
76 }
77
78 =head2 STORABLE_freeze
79
80 Freezes a handle.
81
82 =cut
83
84 sub STORABLE_freeze {
85   my ($self, $cloning) = @_;
86
87   my $to_serialize = { %$self };
88
89   delete $to_serialize->{schema};
90   delete $to_serialize->{_detached_source};
91   $to_serialize->{_frozen_from_class} = $self->{schema}
92     ? $self->{schema}->class($self->source_moniker)
93     : $self->{_detached_source}->result_class
94   ;
95
96   nfreeze($to_serialize);
97 }
98
99 =head2 STORABLE_thaw
100
101 Thaws frozen handle. Resets the internal schema reference to the package
102 variable C<$thaw_schema>. The recommended way of setting this is to use 
103 C<< $schema->thaw($ice) >> which handles this for you.
104
105 =cut
106
107 sub STORABLE_thaw {
108   my ($self, $cloning, $ice) = @_;
109   %$self = %{ thaw($ice) };
110
111   my $from_class = delete $self->{_frozen_from_class};
112
113   if( $thaw_schema ) {
114     $self->schema( $thaw_schema );
115   }
116   elsif( my $rs = $from_class->result_source_instance ) {
117     # in the off-chance we are using CDBI-compat and have leaked $schema already
118     if( my $s = try { $rs->schema } ) {
119       $self->schema( $s );
120     }
121     else {
122       $rs->source_name( $self->source_moniker );
123       $rs->{_detached_thaw} = 1;
124       $self->_detached_source( $rs );
125     }
126   }
127   else {
128     DBIx::Class::Exception->throw(
129       "Thaw failed - original result class '$from_class' does not exist on this system"
130     );
131   }
132 }
133
134 =head1 AUTHOR
135
136 Ash Berlin C<< <ash@cpan.org> >>
137
138 =cut
139
140 1;