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