discard_changes is also "refresh from storage"
[dbsrgits/DBIx-Class-Historic.git] / lib / DBIx / Class / Relationship / Base.pm
1 package DBIx::Class::Relationship::Base;
2
3 use strict;
4 use warnings;
5
6 use Scalar::Util ();
7 use base qw/DBIx::Class/;
8
9 =head1 NAME
10
11 DBIx::Class::Relationship::Base - Inter-table relationships
12
13 =head1 SYNOPSIS
14
15 =head1 DESCRIPTION
16
17 This class provides methods to describe the relationships between the
18 tables in your database model. These are the "bare bones" relationships
19 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
20
21 =head1 METHODS
22
23 =head2 add_relationship
24
25 =over 4
26
27 =item Arguments: 'relname', 'Foreign::Class', $cond, $attrs
28
29 =back
30
31   __PACKAGE__->add_relationship('relname', 'Foreign::Class', $cond, $attrs);
32
33 The condition needs to be an L<SQL::Abstract>-style representation of the
34 join between the tables. When resolving the condition for use in a C<JOIN>,
35 keys using the pseudo-table C<foreign> are resolved to mean "the Table on the
36 other side of the relationship", and values using the pseudo-table C<self>
37 are resolved to mean "the Table this class is representing". Other
38 restrictions, such as by value, sub-select and other tables, may also be
39 used. Please check your database for C<JOIN> parameter support.
40
41 For example, if you're creating a relationship from C<Author> to C<Book>, where
42 the C<Book> table has a column C<author_id> containing the ID of the C<Author>
43 row:
44
45   { 'foreign.author_id' => 'self.id' }
46
47 will result in the C<JOIN> clause
48
49   author me JOIN book book ON book.author_id = me.id
50
51 For multi-column foreign keys, you will need to specify a C<foreign>-to-C<self>
52 mapping for each column in the key. For example, if you're creating a
53 relationship from C<Book> to C<Edition>, where the C<Edition> table refers to a
54 publisher and a type (e.g. "paperback"):
55
56   {
57     'foreign.publisher_id' => 'self.publisher_id',
58     'foreign.type_id'      => 'self.type_id',
59   }
60
61 This will result in the C<JOIN> clause:
62
63   book me JOIN edition edition ON edition.publisher_id = me.publisher_id
64     AND edition.type_id = me.type_id
65
66 Each key-value pair provided in a hashref will be used as C<AND>ed conditions.
67 To add an C<OR>ed condition, use an arrayref of hashrefs. See the
68 L<SQL::Abstract> documentation for more details.
69
70 In addition to standard result set attributes, the following attributes are also valid:
71
72 =over 4
73
74 =item join_type
75
76 Explicitly specifies the type of join to use in the relationship. Any SQL
77 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
78 command immediately before C<JOIN>.
79
80 =item proxy
81
82 An arrayref containing a list of accessors in the foreign class to create in
83 the main class. If, for example, you do the following:
84   
85   MyDB::Schema::CD->might_have(liner_notes => 'MyDB::Schema::LinerNotes',
86     undef, {
87       proxy => [ qw/notes/ ],
88     });
89   
90 Then, assuming MyDB::Schema::LinerNotes has an accessor named notes, you can do:
91
92   my $cd = MyDB::Schema::CD->find(1);
93   $cd->notes('Notes go here'); # set notes -- LinerNotes object is
94                                # created if it doesn't exist
95   
96 =item accessor
97
98 Specifies the type of accessor that should be created for the relationship.
99 Valid values are C<single> (for when there is only a single related object),
100 C<multi> (when there can be many), and C<filter> (for when there is a single
101 related object, but you also want the relationship accessor to double as
102 a column accessor). For C<multi> accessors, an add_to_* method is also
103 created, which calls C<create_related> for the relationship.
104
105 =item is_foreign_key_constraint
106
107 If you are using L<SQL::Translator> to create SQL for you and you find that it
108 is creating constraints where it shouldn't, or not creating them where it 
109 should, set this attribute to a true or false value to override the detection
110 of when to create constraints.
111
112 =back
113
114 =head2 register_relationship
115
116 =over 4
117
118 =item Arguments: $relname, $rel_info
119
120 =back
121
122 Registers a relationship on the class. This is called internally by
123 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
124
125 =cut
126
127 sub register_relationship { }
128
129 =head2 related_resultset
130
131 =over 4
132
133 =item Arguments: $relationship_name
134
135 =item Return Value: $related_resultset
136
137 =back
138
139   $rs = $cd->related_resultset('artist');
140
141 Returns a L<DBIx::Class::ResultSet> for the relationship named
142 $relationship_name.
143
144 =cut
145
146 sub related_resultset {
147   my $self = shift;
148   $self->throw_exception("Can't call *_related as class methods")
149     unless ref $self;
150   my $rel = shift;
151   my $rel_obj = $self->relationship_info($rel);
152   $self->throw_exception( "No such relationship ${rel}" )
153     unless $rel_obj;
154   
155   return $self->{related_resultsets}{$rel} ||= do {
156     my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
157     $attrs = { %{$rel_obj->{attrs} || {}}, %$attrs };
158
159     $self->throw_exception( "Invalid query: @_" )
160       if (@_ > 1 && (@_ % 2 == 1));
161     my $query = ((@_ > 1) ? {@_} : shift);
162
163     my $cond = $self->result_source->resolve_condition(
164       $rel_obj->{cond}, $rel, $self
165     );
166     if (ref $cond eq 'ARRAY') {
167       $cond = [ map { my $hash;
168         foreach my $key (keys %$_) {
169           my $newkey = $key =~ /\./ ? "me.$key" : $key;
170           $hash->{$newkey} = $_->{$key};
171         }; $hash } @$cond ];
172     } else {
173       foreach my $key (grep { ! /\./ } keys %$cond) {
174         $cond->{"me.$key"} = delete $cond->{$key};
175       }
176     }
177     $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
178     $self->result_source->related_source($rel)->resultset->search(
179       $query, $attrs
180     );
181   };
182 }
183
184 =head2 search_related
185
186   @objects = $rs->search_related('relname', $cond, $attrs);
187   $objects_rs = $rs->search_related('relname', $cond, $attrs);
188
189 Run a search on a related resultset. The search will be restricted to the
190 item or items represented by the L<DBIx::Class::ResultSet> it was called
191 upon. This method can be called on a ResultSet, a Row or a ResultSource class.
192
193 =cut
194
195 sub search_related {
196   return shift->related_resultset(shift)->search(@_);
197 }
198
199 =head2 search_related_rs
200
201   ( $objects_rs ) = $rs->search_related_rs('relname', $cond, $attrs);
202
203 This method works exactly the same as search_related, except that 
204 it garauntees a restultset, even in list context.
205
206 =cut
207
208 sub search_related_rs {
209   return shift->related_resultset(shift)->search_rs(@_);
210 }
211
212 =head2 count_related
213
214   $obj->count_related('relname', $cond, $attrs);
215
216 Returns the count of all the items in the related resultset, restricted by the
217 current item or where conditions. Can be called on a
218 L<DBIx::Class::Manual::Glossary/"ResultSet"> or a
219 L<DBIx::Class::Manual::Glossary/"Row"> object.
220
221 =cut
222
223 sub count_related {
224   my $self = shift;
225   return $self->search_related(@_)->count;
226 }
227
228 =head2 new_related
229
230   my $new_obj = $obj->new_related('relname', \%col_data);
231
232 Create a new item of the related foreign class. If called on a
233 L<Row|DBIx::Class::Manual::Glossary/"Row"> object, it will magically 
234 set any foreign key columns of the new object to the related primary 
235 key columns of the source object for you.  The newly created item will 
236 not be saved into your storage until you call L<DBIx::Class::Row/insert>
237 on it.
238
239 =cut
240
241 sub new_related {
242   my ($self, $rel, $values, $attrs) = @_;
243   return $self->search_related($rel)->new($values, $attrs);
244 }
245
246 =head2 create_related
247
248   my $new_obj = $obj->create_related('relname', \%col_data);
249
250 Creates a new item, similarly to new_related, and also inserts the item's data
251 into your storage medium. See the distinction between C<create> and C<new>
252 in L<DBIx::Class::ResultSet> for details.
253
254 =cut
255
256 sub create_related {
257   my $self = shift;
258   my $rel = shift;
259   my $obj = $self->search_related($rel)->create(@_);
260   delete $self->{related_resultsets}->{$rel};
261   return $obj;
262 }
263
264 =head2 find_related
265
266   my $found_item = $obj->find_related('relname', @pri_vals | \%pri_vals);
267
268 Attempt to find a related object using its primary key or unique constraints.
269 See L<DBIx::Class::ResultSet/find> for details.
270
271 =cut
272
273 sub find_related {
274   my $self = shift;
275   my $rel = shift;
276   return $self->search_related($rel)->find(@_);
277 }
278
279 =head2 find_or_new_related
280
281   my $new_obj = $obj->find_or_new_related('relname', \%col_data);
282
283 Find an item of a related class. If none exists, instantiate a new item of the
284 related class. The object will not be saved into your storage until you call
285 L<DBIx::Class::Row/insert> on it.
286
287 =cut
288
289 sub find_or_new_related {
290   my $self = shift;
291   return $self->find_related(@_) || $self->new_related(@_);
292 }
293
294 =head2 find_or_create_related
295
296   my $new_obj = $obj->find_or_create_related('relname', \%col_data);
297
298 Find or create an item of a related class. See
299 L<DBIx::Class::ResultSet/find_or_create> for details.
300
301 =cut
302
303 sub find_or_create_related {
304   my $self = shift;
305   my $obj = $self->find_related(@_);
306   return (defined($obj) ? $obj : $self->create_related(@_));
307 }
308
309 =head2 update_or_create_related
310
311   my $updated_item = $obj->update_or_create_related('relname', \%col_data, \%attrs?);
312
313 Update or create an item of a related class. See
314 L<DBIx::Class::ResultSet/update_or_create> for details.
315
316 =cut
317
318 sub update_or_create_related {
319   my $self = shift;
320   my $rel = shift;
321   return $self->related_resultset($rel)->update_or_create(@_);
322 }
323
324 =head2 set_from_related
325
326   $book->set_from_related('author', $author_obj);
327   $book->author($author_obj);                      ## same thing
328
329 Set column values on the current object, using related values from the given
330 related object. This is used to associate previously separate objects, for
331 example, to set the correct author for a book, find the Author object, then
332 call set_from_related on the book.
333
334 This is called internally when you pass existing objects as values to
335 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to acessor.
336
337 The columns are only set in the local copy of the object, call L</update> to
338 set them in the storage.
339
340 =cut
341
342 sub set_from_related {
343   my ($self, $rel, $f_obj) = @_;
344   my $rel_obj = $self->relationship_info($rel);
345   $self->throw_exception( "No such relationship ${rel}" ) unless $rel_obj;
346   my $cond = $rel_obj->{cond};
347   $self->throw_exception(
348     "set_from_related can only handle a hash condition; the ".
349     "condition for $rel is of type ".
350     (ref $cond ? ref $cond : 'plain scalar')
351   ) unless ref $cond eq 'HASH';
352   if (defined $f_obj) {
353     my $f_class = $self->result_source->schema->class($rel_obj->{class});
354     $self->throw_exception( "Object $f_obj isn't a ".$f_class )
355       unless Scalar::Util::blessed($f_obj) and $f_obj->isa($f_class);
356   }
357   $self->set_columns(
358     $self->result_source->resolve_condition(
359        $rel_obj->{cond}, $f_obj, $rel));
360   return 1;
361 }
362
363 =head2 update_from_related
364
365   $book->update_from_related('author', $author_obj);
366
367 The same as L</"set_from_related">, but the changes are immediately updated
368 in storage.
369
370 =cut
371
372 sub update_from_related {
373   my $self = shift;
374   $self->set_from_related(@_);
375   $self->update;
376 }
377
378 =head2 delete_related
379
380   $obj->delete_related('relname', $cond, $attrs);
381
382 Delete any related item subject to the given conditions.
383
384 =cut
385
386 sub delete_related {
387   my $self = shift;
388   my $obj = $self->search_related(@_)->delete;
389   delete $self->{related_resultsets}->{$_[0]};
390   return $obj;
391 }
392
393 =head2 add_to_$rel
394
395 B<Currently only available for C<has_many>, C<many-to-many> and 'multi' type
396 relationships.>
397
398 =over 4
399
400 =item Arguments: ($foreign_vals | $obj), $link_vals?
401
402 =back
403
404   my $role = $schema->resultset('Role')->find(1);
405   $actor->add_to_roles($role);
406       # creates a My::DBIC::Schema::ActorRoles linking table row object
407
408   $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
409       # creates a new My::DBIC::Schema::Role row object and the linking table
410       # object with an extra column in the link
411
412 Adds a linking table object for C<$obj> or C<$foreign_vals>. If the first
413 argument is a hash reference, the related object is created first with the
414 column values in the hash. If an object reference is given, just the linking
415 table object is created. In either case, any additional column values for the
416 linking table object can be specified in C<$link_vals>.
417
418 =head2 set_$rel
419
420 B<Currently only available for C<many-to-many> relationships.>
421
422 =over 4
423
424 =item Arguments: (\@hashrefs | \@objs)
425
426 =back
427
428   my $actor = $schema->resultset('Actor')->find(1);
429   my @roles = $schema->resultset('Role')->search({ role => 
430      { '-in' -> ['Fred', 'Barney'] } } );
431
432   $actor->set_roles(\@roles);
433      # Replaces all of $actor's previous roles with the two named
434
435 Replace all the related objects with the given reference to a list of
436 objects. This does a C<delete> B<on the link table resultset> to remove the
437 association between the current object and all related objects, then calls
438 C<add_to_$rel> repeatedly to link all the new objects.
439
440 Note that this means that this method will B<not> delete any objects in the
441 table on the right side of the relation, merely that it will delete the link
442 between them.
443
444 Due to a mistake in the original implementation of this method, it will also
445 accept a list of objects or hash references. This is B<deprecated> and will be
446 removed in a future version.
447
448 =head2 remove_from_$rel
449
450 B<Currently only available for C<many-to-many> relationships.>
451
452 =over 4
453
454 =item Arguments: $obj
455
456 =back
457
458   my $role = $schema->resultset('Role')->find(1);
459   $actor->remove_from_roles($role);
460       # removes $role's My::DBIC::Schema::ActorRoles linking table row object
461
462 Removes the link between the current object and the related object. Note that
463 the related object itself won't be deleted unless you call ->delete() on
464 it. This method just removes the link between the two objects.
465
466 =head1 AUTHORS
467
468 Matt S. Trout <mst@shadowcatsystems.co.uk>
469
470 =head1 LICENSE
471
472 You may distribute this code under the same terms as Perl itself.
473
474 =cut
475
476 1;