lib/DBIx/Class/Relationship/Base.pm

   1 package DBIx::Class::Relationship::Base;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/DBIx::Class/;
   7
   8 use Scalar::Util qw/weaken blessed/;
   9 use Try::Tiny;
  10 use namespace::clean;
  11
  12 =head1 NAME
  13
  14 DBIx::Class::Relationship::Base - Inter-table relationships
  15
  16 =head1 SYNOPSIS
  17
  18   __PACKAGE__->add_relationship(
  19     spiders => 'My::DB::Result::Creatures',
  20     sub {
  21       my $args = shift;
  22       return {
  23         "$args->{foreign_alias}.id"   => { -ident => "$args->{self_alias}.id" },
  24         "$args->{foreign_alias}.type" => 'arachnid'
  25       };
  26     },
  27   );
  28
  29 =head1 DESCRIPTION
  30
  31 This class provides methods to describe the relationships between the
  32 tables in your database model. These are the "bare bones" relationships
  33 methods, for predefined ones, look in L<DBIx::Class::Relationship>.
  34
  35 =head1 METHODS
  36
  37 =head2 add_relationship
  38
  39 =over 4
  40
  41 =item Arguments: 'relname', 'Foreign::Class', $condition, $attrs
  42
  43 =back
  44
  45   __PACKAGE__->add_relationship('relname',
  46                                 'Foreign::Class',
  47                                 $condition, $attrs);
  48
  49 Create a custom relationship between one result source and another
  50 source, indicated by its class name.
  51
  52 =head3 condition
  53
  54 The condition argument describes the C<ON> clause of the C<JOIN>
  55 expression used to connect the two sources when creating SQL queries.
  56
  57 =head4 Simple equality
  58
  59 To create simple equality joins, supply a hashref containing the remote
  60 table column name as the key(s) prefixed by C<'foreign.'>, and the
  61 corresponding local table column name as the value(s) prefixed by C<'self.'>.
  62 Both C<foreign> and C<self> are pseudo aliases and must be entered
  63 literally. They will be replaced with the actual correct table alias
  64 when the SQL is produced.
  65
  66 For example given:
  67
  68   My::Schema::Author->has_many(
  69     books => 'My::Schema::Book',
  70     { 'foreign.author_id' => 'self.id' }
  71   );
  72
  73 A query like:
  74
  75   $author_rs->search_related('books')->next
  76
  77 will result in the following C<JOIN> clause:
  78
  79   ... FROM author me LEFT JOIN book books ON books.author_id = me.id ...
  80
  81 This describes a relationship between the C<Author> table and the
  82 C<Book> table where the C<Book> table has a column C<author_id>
  83 containing the ID value of the C<Author>.
  84
  85 Similarly:
  86
  87   My::Schema::Book->has_many(
  88     editions => 'My::Schema::Edition',
  89     {
  90       'foreign.publisher_id' => 'self.publisher_id',
  91       'foreign.type_id'      => 'self.type_id',
  92     }
  93   );
  94
  95   ...
  96
  97   $book_rs->search_related('editions')->next
  98
  99 will result in the C<JOIN> clause:
 100
 101   ... FROM book me
 102       LEFT JOIN edition editions ON
 103            editions.publisher_id = me.publisher_id
 104        AND editions.type_id = me.type_id ...
 105
 106 This describes the relationship from C<Book> to C<Edition>, where the
 107 C<Edition> table refers to a publisher and a type (e.g. "paperback"):
 108
 109 =head4 Multiple groups of simple equality conditions
 110
 111 As is the default in L<SQL::Abstract>, the key-value pairs will be
 112 C<AND>ed in the resulting C<JOIN> clause. An C<OR> can be achieved with
 113 an arrayref. For example a condition like:
 114
 115   My::Schema::Item->has_many(
 116     related_item_links => My::Schema::Item::Links,
 117     [
 118       { 'foreign.left_itemid'  => 'self.id' },
 119       { 'foreign.right_itemid' => 'self.id' },
 120     ],
 121   );
 122
 123 will translate to the following C<JOIN> clause:
 124
 125  ... FROM item me JOIN item_relations related_item_links ON
 126          related_item_links.left_itemid = me.id
 127       OR related_item_links.right_itemid = me.id ...
 128
 129 This describes the relationship from C<Item> to C<Item::Links>, where
 130 C<Item::Links> is a many-to-many linking table, linking items back to
 131 themselves in a peer fashion (without a "parent-child" designation)
 132
 133 =head4 Custom join conditions
 134
 135   NOTE: The custom join condition specification mechanism is capable of
 136   generating JOIN clauses of virtually unlimited complexity. This may limit
 137   your ability to traverse some of the more involved relationship chains the
 138   way you expect, *and* may bring your RDBMS to its knees. Exercise care
 139   when declaring relationships as described here.
 140
 141 To specify joins which describe more than a simple equality of column
 142 values, the custom join condition coderef syntax can be used. For
 143 example:
 144
 145   My::Schema::Artist->has_many(
 146     cds_80s => 'My::Schema::CD',
 147     sub {
 148       my $args = shift;
 149
 150       return {
 151         "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
 152         "$args->{foreign_alias}.year"   => { '>', "1979", '<', "1990" },
 153       };
 154     }
 155   );
 156
 157   ...
 158
 159   $artist_rs->search_related('cds_80s')->next;
 160
 161 will result in the C<JOIN> clause:
 162
 163   ... FROM artist me LEFT JOIN cd cds_80s ON
 164         cds_80s.artist = me.artistid
 165     AND cds_80s.year < ?
 166     AND cds_80s.year > ?
 167
 168 with the bind values:
 169
 170    '1990', '1979'
 171
 172 C<< $args->{foreign_alias} >> and C<< $args->{self_alias} >> are supplied the
 173 same values that would be otherwise substituted for C<foreign> and C<self>
 174 in the simple hashref syntax case.
 175
 176 The coderef is expected to return a valid L<SQL::Abstract> query-structure, just
 177 like what one would supply as the first argument to
 178 L<DBIx::Class::ResultSet/search>. The return value will be passed directly to
 179 L<SQL::Abstract> and the resulting SQL will be used verbatim as the C<ON>
 180 clause of the C<JOIN> statement associated with this relationship.
 181
 182 While every coderef-based condition must return a valid C<ON> clause, it may
 183 elect to additionally return a simplified join-free condition hashref when
 184 invoked as C<< $result->relationship >>, as opposed to
 185 C<< $rs->related_resultset('relationship') >>. In this case C<$result> is
 186 passed to the coderef as C<< $args->{self_rowobj} >>, so a user can do the
 187 following:
 188
 189   sub {
 190     my $args = shift;
 191
 192     return (
 193       {
 194         "$args->{foreign_alias}.artist" => { -ident => "$args->{self_alias}.artistid" },
 195         "$args->{foreign_alias}.year"   => { '>', "1979", '<', "1990" },
 196       },
 197       $args->{self_rowobj} && {
 198         "$args->{foreign_alias}.artist" => $args->{self_rowobj}->artistid,
 199         "$args->{foreign_alias}.year"   => { '>', "1979", '<', "1990" },
 200       },
 201     );
 202   }
 203
 204 Now this code:
 205
 206     my $artist = $schema->resultset("Artist")->find({ id => 4 });
 207     $artist->cds_80s->all;
 208
 209 Can skip a C<JOIN> altogether and instead produce:
 210
 211     SELECT cds_80s.cdid, cds_80s.artist, cds_80s.title, cds_80s.year, cds_80s.genreid, cds_80s.single_track
 212       FROM cd cds_80s
 213       WHERE cds_80s.artist = ?
 214         AND cds_80s.year < ?
 215         AND cds_80s.year > ?
 216
 217 With the bind values:
 218
 219     '4', '1990', '1979'
 220
 221 Note that in order to be able to use
 222 L<< $result->create_related|DBIx::Class::Relationship::Base/create_related >>,
 223 the coderef must not only return as its second such a "simple" condition
 224 hashref which does not depend on joins being available, but the hashref must
 225 contain only plain values/deflatable objects, such that the result can be
 226 passed directly to L<DBIx::Class::Relationship::Base/set_from_related>. For
 227 instance the C<year> constraint in the above example prevents the relationship
 228 from being used to create related objects (an exception will be thrown).
 229
 230 In order to allow the user to go truly crazy when generating a custom C<ON>
 231 clause, the C<$args> hashref passed to the subroutine contains some extra
 232 metadata. Currently the supplied coderef is executed as:
 233
 234   $relationship_info->{cond}->({
 235     self_alias        => The alias of the invoking resultset ('me' in case of a result object),
 236     foreign_alias     => The alias of the to-be-joined resultset (often matches relname),
 237     self_resultsource => The invocant's resultsource,
 238     foreign_relname   => The relationship name (does *not* always match foreign_alias),
 239     self_rowobj       => The invocant itself in case of a $result_object->$relationship call
 240   });
 241
 242 =head3 attributes
 243
 244 The L<standard ResultSet attributes|DBIx::Class::ResultSet/ATTRIBUTES> may
 245 be used as relationship attributes. In particular, the 'where' attribute is
 246 useful for filtering relationships:
 247
 248      __PACKAGE__->has_many( 'valid_users', 'MyApp::Schema::User',
 249         { 'foreign.user_id' => 'self.user_id' },
 250         { where => { valid => 1 } }
 251     );
 252
 253 The following attributes are also valid:
 254
 255 =over 4
 256
 257 =item join_type
 258
 259 Explicitly specifies the type of join to use in the relationship. Any SQL
 260 join type is valid, e.g. C<LEFT> or C<RIGHT>. It will be placed in the SQL
 261 command immediately before C<JOIN>.
 262
 263 =item proxy =E<gt> $column | \@columns | \%column
 264
 265 The 'proxy' attribute can be used to retrieve values, and to perform
 266 updates if the relationship has 'cascade_update' set. The 'might_have'
 267 and 'has_one' relationships have this set by default; if you want a proxy
 268 to update across a 'belongs_to' relationship, you must set the attribute
 269 yourself.
 270
 271 =over 4
 272
 273 =item \@columns
 274
 275 An arrayref containing a list of accessors in the foreign class to create in
 276 the main class. If, for example, you do the following:
 277
 278   MyApp::Schema::CD->might_have(liner_notes => 'MyApp::Schema::LinerNotes',
 279     undef, {
 280       proxy => [ qw/notes/ ],
 281     });
 282
 283 Then, assuming MyApp::Schema::LinerNotes has an accessor named notes, you can do:
 284
 285   my $cd = MyApp::Schema::CD->find(1);
 286   $cd->notes('Notes go here'); # set notes -- LinerNotes object is
 287                                # created if it doesn't exist
 288
 289 For a 'belongs_to relationship, note the 'cascade_update':
 290
 291   MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd,
 292       { proxy => ['title'], cascade_update => 1 }
 293   );
 294   $track->title('New Title');
 295   $track->update; # updates title in CD
 296
 297 =item \%column
 298
 299 A hashref where each key is the accessor you want installed in the main class,
 300 and its value is the name of the original in the foreign class.
 301
 302   MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
 303       proxy => { cd_title => 'title' },
 304   });
 305
 306 This will create an accessor named C<cd_title> on the C<$track> result object.
 307
 308 =back
 309
 310 NOTE: you can pass a nested struct too, for example:
 311
 312   MyApp::Schema::Track->belongs_to( cd => 'MyApp::Schema::CD', 'cd', {
 313     proxy => [ 'year', { cd_title => 'title' } ],
 314   });
 315
 316 =item accessor
 317
 318 Specifies the type of accessor that should be created for the relationship.
 319 Valid values are C<single> (for when there is only a single related object),
 320 C<multi> (when there can be many), and C<filter> (for when there is a single
 321 related object, but you also want the relationship accessor to double as
 322 a column accessor). For C<multi> accessors, an add_to_* method is also
 323 created, which calls C<create_related> for the relationship.
 324
 325 =item is_foreign_key_constraint
 326
 327 If you are using L<SQL::Translator> to create SQL for you and you find that it
 328 is creating constraints where it shouldn't, or not creating them where it
 329 should, set this attribute to a true or false value to override the detection
 330 of when to create constraints.
 331
 332 =item cascade_copy
 333
 334 If C<cascade_copy> is true on a C<has_many> relationship for an
 335 object, then when you copy the object all the related objects will
 336 be copied too. To turn this behaviour off, pass C<< cascade_copy => 0 >>
 337 in the C<$attr> hashref.
 338
 339 The behaviour defaults to C<< cascade_copy => 1 >> for C<has_many>
 340 relationships.
 341
 342 =item cascade_delete
 343
 344 By default, DBIx::Class cascades deletes across C<has_many>,
 345 C<has_one> and C<might_have> relationships. You can disable this
 346 behaviour on a per-relationship basis by supplying
 347 C<< cascade_delete => 0 >> in the relationship attributes.
 348
 349 The cascaded operations are performed after the requested delete,
 350 so if your database has a constraint on the relationship, it will
 351 have deleted/updated the related records or raised an exception
 352 before DBIx::Class gets to perform the cascaded operation.
 353
 354 =item cascade_update
 355
 356 By default, DBIx::Class cascades updates across C<has_one> and
 357 C<might_have> relationships. You can disable this behaviour on a
 358 per-relationship basis by supplying C<< cascade_update => 0 >> in
 359 the relationship attributes.
 360
 361 The C<belongs_to> relationship does not update across relationships
 362 by default, so if you have a 'proxy' attribute on a belongs_to and want to
 363 use 'update' on it, you muse set C<< cascade_update => 1 >>.
 364
 365 This is not a RDMS style cascade update - it purely means that when
 366 an object has update called on it, all the related objects also
 367 have update called. It will not change foreign keys automatically -
 368 you must arrange to do this yourself.
 369
 370 =item on_delete / on_update
 371
 372 If you are using L<SQL::Translator> to create SQL for you, you can use these
 373 attributes to explicitly set the desired C<ON DELETE> or C<ON UPDATE> constraint
 374 type. If not supplied the SQLT parser will attempt to infer the constraint type by
 375 interrogating the attributes of the B<opposite> relationship. For any 'multi'
 376 relationship with C<< cascade_delete => 1 >>, the corresponding belongs_to
 377 relationship will be created with an C<ON DELETE CASCADE> constraint. For any
 378 relationship bearing C<< cascade_copy => 1 >> the resulting belongs_to constraint
 379 will be C<ON UPDATE CASCADE>. If you wish to disable this autodetection, and just
 380 use the RDBMS' default constraint type, pass C<< on_delete => undef >> or
 381 C<< on_delete => '' >>, and the same for C<on_update> respectively.
 382
 383 =item is_deferrable
 384
 385 Tells L<SQL::Translator> that the foreign key constraint it creates should be
 386 deferrable. In other words, the user may request that the constraint be ignored
 387 until the end of the transaction. Currently, only the PostgreSQL producer
 388 actually supports this.
 389
 390 =item add_fk_index
 391
 392 Tells L<SQL::Translator> to add an index for this constraint. Can also be
 393 specified globally in the args to L<DBIx::Class::Schema/deploy> or
 394 L<DBIx::Class::Schema/create_ddl_dir>. Default is on, set to 0 to disable.
 395
 396 =back
 397
 398 =head2 register_relationship
 399
 400 =over 4
 401
 402 =item Arguments: $rel_name, $rel_info
 403
 404 =back
 405
 406 Registers a relationship on the class. This is called internally by
 407 DBIx::Class::ResultSourceProxy to set up Accessors and Proxies.
 408
 409 =cut
 410
 411 sub register_relationship { }
 412
 413 =head2 related_resultset
 414
 415 =over 4
 416
 417 =item Arguments: $rel_name
 418
 419 =item Return Value: L<$related_resultset|DBIx::Class::ResultSet>
 420
 421 =back
 422
 423   $rs = $cd->related_resultset('artist');
 424
 425 Returns a L<DBIx::Class::ResultSet> for the relationship named
 426 $rel_name.
 427
 428 =head2 $relationship_accessor
 429
 430 =over 4
 431
 432 =item Arguments: none
 433
 434 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | L<$related_resultset|DBIx::Class::ResultSet> | undef
 435
 436 =back
 437
 438   # These pairs do the same thing
 439   $result = $cd->related_resultset('artist')->single;  # has_one relationship
 440   $result = $cd->artist;
 441   $rs = $cd->related_resultset('tracks');           # has_many relationship
 442   $rs = $cd->tracks;
 443
 444 This is the recommended way to traverse through relationships, based
 445 on the L</accessor> name given in the relationship definition.
 446
 447 This will return either a L<Result|DBIx::Class::Manual::ResultClass> or a
 448 L<ResultSet|DBIx::Class::ResultSet>, depending on if the relationship is
 449 C<single> (returns only one row) or C<multi> (returns many rows).  The
 450 method may also return C<undef> if the relationship doesn't exist for
 451 this instance (like in the case of C<might_have> relationships).
 452
 453 =cut
 454
 455 sub related_resultset {
 456   my $self = shift;
 457
 458   $self->throw_exception("Can't call *_related as class methods")
 459     unless ref $self;
 460
 461   my $rel = shift;
 462
 463   return $self->{related_resultsets}{$rel}
 464     if defined $self->{related_resultsets}{$rel};
 465
 466   return $self->{related_resultsets}{$rel} = do {
 467
 468     my $rel_info = $self->relationship_info($rel)
 469       or $self->throw_exception( "No such relationship '$rel'" );
 470
 471     my $attrs = (@_ > 1 && ref $_[$#_] eq 'HASH' ? pop(@_) : {});
 472     $attrs = { %{$rel_info->{attrs} || {}}, %$attrs };
 473
 474     $self->throw_exception( "Invalid query: @_" )
 475       if (@_ > 1 && (@_ % 2 == 1));
 476     my $query = ((@_ > 1) ? {@_} : shift);
 477
 478     my $rsrc = $self->result_source;
 479
 480     # condition resolution may fail if an incomplete master-object prefetch
 481     # is encountered - that is ok during prefetch construction (not yet in_storage)
 482     my ($cond, $is_crosstable) = try {
 483       $rsrc->_resolve_condition( $rel_info->{cond}, $rel, $self, $rel )
 484     }
 485     catch {
 486       if ($self->in_storage) {
 487         $self->throw_exception ($_);
 488       }
 489
 490       $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION;  # RV
 491     };
 492
 493     # keep in mind that the following if() block is part of a do{} - no return()s!!!
 494     if ($is_crosstable) {
 495       $self->throw_exception (
 496         "A cross-table relationship condition returned for statically declared '$rel'"
 497       ) unless ref $rel_info->{cond} eq 'CODE';
 498
 499       # A WHOREIFFIC hack to reinvoke the entire condition resolution
 500       # with the correct alias. Another way of doing this involves a
 501       # lot of state passing around, and the @_ positions are already
 502       # mapped out, making this crap a less icky option.
 503       #
 504       # The point of this exercise is to retain the spirit of the original
 505       # $obj->search_related($rel) where the resulting rset will have the
 506       # root alias as 'me', instead of $rel (as opposed to invoking
 507       # $rs->search_related)
 508
 509       local $rsrc->{_relationships}{me} = $rsrc->{_relationships}{$rel};  # make the fake 'me' rel
 510       my $obj_table_alias = lc($rsrc->source_name) . '__row';
 511       $obj_table_alias =~ s/\W+/_/g;
 512
 513       $rsrc->resultset->search(
 514         $self->ident_condition($obj_table_alias),
 515         { alias => $obj_table_alias },
 516       )->search_related('me', $query, $attrs)
 517     }
 518     else {
 519       # FIXME - this conditional doesn't seem correct - got to figure out
 520       # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
 521       # business seems shady - we could simply not query *at all*
 522       if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
 523         my $reverse = $rsrc->reverse_relationship_info($rel);
 524         foreach my $rev_rel (keys %$reverse) {
 525           if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
 526             weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
 527           } else {
 528             weaken($attrs->{related_objects}{$rev_rel} = $self);
 529           }
 530         }
 531       }
 532       elsif (ref $cond eq 'ARRAY') {
 533         $cond = [ map {
 534           if (ref $_ eq 'HASH') {
 535             my $hash;
 536             foreach my $key (keys %$_) {
 537               my $newkey = $key !~ /\./ ? "me.$key" : $key;
 538               $hash->{$newkey} = $_->{$key};
 539             }
 540             $hash;
 541           } else {
 542             $_;
 543           }
 544         } @$cond ];
 545       }
 546       elsif (ref $cond eq 'HASH') {
 547        foreach my $key (grep { ! /\./ } keys %$cond) {
 548           $cond->{"me.$key"} = delete $cond->{$key};
 549         }
 550       }
 551
 552       $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
 553       $rsrc->related_source($rel)->resultset->search(
 554         $query, $attrs
 555       );
 556     }
 557   };
 558 }
 559
 560 =head2 search_related
 561
 562 =over 4
 563
 564 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 565
 566 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 567
 568 =back
 569
 570 Run a search on a related resultset. The search will be restricted to the
 571 results represented by the L<DBIx::Class::ResultSet> it was called
 572 upon.
 573
 574 See L<DBIx::Class::ResultSet/search_related> for more information.
 575
 576 =cut
 577
 578 sub search_related {
 579   return shift->related_resultset(shift)->search(@_);
 580 }
 581
 582 =head2 search_related_rs
 583
 584 This method works exactly the same as search_related, except that
 585 it guarantees a resultset, even in list context.
 586
 587 =cut
 588
 589 sub search_related_rs {
 590   return shift->related_resultset(shift)->search_rs(@_);
 591 }
 592
 593 =head2 count_related
 594
 595 =over 4
 596
 597 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 598
 599 =item Return Value: $count
 600
 601 =back
 602
 603 Returns the count of all the rows in the related resultset, restricted by the
 604 current result or where conditions.
 605
 606 =cut
 607
 608 sub count_related {
 609   shift->search_related(@_)->count;
 610 }
 611
 612 =head2 new_related
 613
 614 =over 4
 615
 616 =item Arguments: $rel_name, \%col_data
 617
 618 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 619
 620 =back
 621
 622 Create a new result object of the related foreign class.  It will magically set
 623 any foreign key columns of the new object to the related primary key columns
 624 of the source object for you.  The newly created result will not be saved into
 625 your storage until you call L<DBIx::Class::Row/insert> on it.
 626
 627 =cut
 628
 629 sub new_related {
 630   my ($self, $rel, $values) = @_;
 631
 632   # FIXME - this is a bad position for this (also an identical copy in
 633   # set_from_related), but I have no saner way to hook, and I absolutely
 634   # want this to throw at least for coderefs, instead of the "insert a NULL
 635   # when it gets hard" insanity --ribasushi
 636   #
 637   # sanity check - currently throw when a complex coderef rel is encountered
 638   # FIXME - should THROW MOAR!
 639
 640   if (ref $self) {  # cdbi calls this as a class method, /me vomits
 641
 642     my $rsrc = $self->result_source;
 643     my $rel_info = $rsrc->relationship_info($rel)
 644       or $self->throw_exception( "No such relationship '$rel'" );
 645     my (undef, $crosstable, $cond_targets) = $rsrc->_resolve_condition (
 646       $rel_info->{cond}, $rel, $self, $rel
 647     );
 648
 649     $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
 650       if $crosstable;
 651
 652     if (my @unspecified_rel_condition_chunks = grep { ! exists $values->{$_} } @{$cond_targets||[]} ) {
 653       $self->throw_exception(sprintf (
 654         "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
 655         $rel,
 656         map { "'$_'" } @unspecified_rel_condition_chunks
 657       ));
 658     }
 659   }
 660
 661   return $self->search_related($rel)->new_result($values);
 662 }
 663
 664 =head2 create_related
 665
 666 =over 4
 667
 668 =item Arguments: $rel_name, \%col_data
 669
 670 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 671
 672 =back
 673
 674   my $result = $obj->create_related($rel_name, \%col_data);
 675
 676 Creates a new result object, similarly to new_related, and also inserts the
 677 result's data into your storage medium. See the distinction between C<create>
 678 and C<new> in L<DBIx::Class::ResultSet> for details.
 679
 680 =cut
 681
 682 sub create_related {
 683   my $self = shift;
 684   my $rel = shift;
 685   my $obj = $self->new_related($rel, @_)->insert;
 686   delete $self->{related_resultsets}->{$rel};
 687   return $obj;
 688 }
 689
 690 =head2 find_related
 691
 692 =over 4
 693
 694 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 695
 696 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
 697
 698 =back
 699
 700   my $result = $obj->find_related($rel_name, \%col_data);
 701
 702 Attempt to find a related object using its primary key or unique constraints.
 703 See L<DBIx::Class::ResultSet/find> for details.
 704
 705 =cut
 706
 707 sub find_related {
 708   #my ($self, $rel, @args) = @_;
 709   return shift->search_related(shift)->find(@_);
 710 }
 711
 712 =head2 find_or_new_related
 713
 714 =over 4
 715
 716 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 717
 718 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 719
 720 =back
 721
 722 Find a result object of a related class.  See L<DBIx::Class::ResultSet/find_or_new>
 723 for details.
 724
 725 =cut
 726
 727 sub find_or_new_related {
 728   my $self = shift;
 729   my $obj = $self->find_related(@_);
 730   return defined $obj ? $obj : $self->new_related(@_);
 731 }
 732
 733 =head2 find_or_create_related
 734
 735 =over 4
 736
 737 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 738
 739 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 740
 741 =back
 742
 743 Find or create a result object of a related class. See
 744 L<DBIx::Class::ResultSet/find_or_create> for details.
 745
 746 =cut
 747
 748 sub find_or_create_related {
 749   my $self = shift;
 750   my $obj = $self->find_related(@_);
 751   return (defined($obj) ? $obj : $self->create_related(@_));
 752 }
 753
 754 =head2 update_or_create_related
 755
 756 =over 4
 757
 758 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 759
 760 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 761
 762 =back
 763
 764 Update or create a result object of a related class. See
 765 L<DBIx::Class::ResultSet/update_or_create> for details.
 766
 767 =cut
 768
 769 sub update_or_create_related {
 770   #my ($self, $rel, @args) = @_;
 771   shift->related_resultset(shift)->update_or_create(@_);
 772 }
 773
 774 =head2 set_from_related
 775
 776 =over 4
 777
 778 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
 779
 780 =item Return Value: not defined
 781
 782 =back
 783
 784   $book->set_from_related('author', $author_obj);
 785   $book->author($author_obj);                      ## same thing
 786
 787 Set column values on the current object, using related values from the given
 788 related object. This is used to associate previously separate objects, for
 789 example, to set the correct author for a book, find the Author object, then
 790 call set_from_related on the book.
 791
 792 This is called internally when you pass existing objects as values to
 793 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
 794
 795 The columns are only set in the local copy of the object, call L</update> to
 796 set them in the storage.
 797
 798 =cut
 799
 800 sub set_from_related {
 801   my ($self, $rel, $f_obj) = @_;
 802
 803   my $rsrc = $self->result_source;
 804   my $rel_info = $rsrc->relationship_info($rel)
 805     or $self->throw_exception( "No such relationship '$rel'" );
 806
 807   if (defined $f_obj) {
 808     my $f_class = $rel_info->{class};
 809     $self->throw_exception( "Object '$f_obj' isn't a ".$f_class )
 810       unless blessed $f_obj and $f_obj->isa($f_class);
 811   }
 812
 813
 814   # FIXME - this is a bad position for this (also an identical copy in
 815   # new_related), but I have no saner way to hook, and I absolutely
 816   # want this to throw at least for coderefs, instead of the "insert a NULL
 817   # when it gets hard" insanity --ribasushi
 818   #
 819   # sanity check - currently throw when a complex coderef rel is encountered
 820   # FIXME - should THROW MOAR!
 821   my ($cond, $crosstable, $cond_targets) = $rsrc->_resolve_condition (
 822     $rel_info->{cond}, $f_obj, $rel, $rel
 823   );
 824   $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
 825     if $crosstable;
 826   $self->throw_exception(sprintf (
 827     "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
 828     $rel,
 829     map { "'$_'" } @$cond_targets
 830   )) if $cond_targets;
 831
 832   $self->set_columns($cond);
 833
 834   return 1;
 835 }
 836
 837 =head2 update_from_related
 838
 839 =over 4
 840
 841 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
 842
 843 =item Return Value: not defined
 844
 845 =back
 846
 847   $book->update_from_related('author', $author_obj);
 848
 849 The same as L</"set_from_related">, but the changes are immediately updated
 850 in storage.
 851
 852 =cut
 853
 854 sub update_from_related {
 855   my $self = shift;
 856   $self->set_from_related(@_);
 857   $self->update;
 858 }
 859
 860 =head2 delete_related
 861
 862 =over 4
 863
 864 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 865
 866 =item Return Value: $underlying_storage_rv
 867
 868 =back
 869
 870 Delete any related row, subject to the given conditions.  Internally, this
 871 calls:
 872
 873   $self->search_related(@_)->delete
 874
 875 And returns the result of that.
 876
 877 =cut
 878
 879 sub delete_related {
 880   my $self = shift;
 881   my $obj = $self->search_related(@_)->delete;
 882   delete $self->{related_resultsets}->{$_[0]};
 883   return $obj;
 884 }
 885
 886 =head2 add_to_$rel
 887
 888 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
 889 relationships.>
 890
 891 =head3 has_many / multi
 892
 893 =over 4
 894
 895 =item Arguments: \%col_data
 896
 897 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 898
 899 =back
 900
 901 Creates/inserts a new result object.  Internally, this calls:
 902
 903   $self->create_related($rel, @_)
 904
 905 And returns the result of that.
 906
 907 =head3 many_to_many
 908
 909 =over 4
 910
 911 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
 912
 913 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 914
 915 =back
 916
 917   my $role = $schema->resultset('Role')->find(1);
 918   $actor->add_to_roles($role);
 919       # creates a My::DBIC::Schema::ActorRoles linking table result object
 920
 921   $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
 922       # creates a new My::DBIC::Schema::Role result object and the linking table
 923       # object with an extra column in the link
 924
 925 Adds a linking table object. If the first argument is a hash reference, the
 926 related object is created first with the column values in the hash. If an object
 927 reference is given, just the linking table object is created. In either case,
 928 any additional column values for the linking table object can be specified in
 929 C<\%link_col_data>.
 930
 931 See L<DBIx::Class::Relationship/many_to_many> for additional details.
 932
 933 =head2 set_$rel
 934
 935 B<Currently only available for C<many_to_many> relationships.>
 936
 937 =over 4
 938
 939 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
 940
 941 =item Return Value: not defined
 942
 943 =back
 944
 945   my $actor = $schema->resultset('Actor')->find(1);
 946   my @roles = $schema->resultset('Role')->search({ role =>
 947      { '-in' => ['Fred', 'Barney'] } } );
 948
 949   $actor->set_roles(\@roles);
 950      # Replaces all of $actor's previous roles with the two named
 951
 952   $actor->set_roles(\@roles, { salary => 15_000_000 });
 953      # Sets a column in the link table for all roles
 954
 955
 956 Replace all the related objects with the given reference to a list of
 957 objects. This does a C<delete> B<on the link table resultset> to remove the
 958 association between the current object and all related objects, then calls
 959 C<add_to_$rel> repeatedly to link all the new objects.
 960
 961 Note that this means that this method will B<not> delete any objects in the
 962 table on the right side of the relation, merely that it will delete the link
 963 between them.
 964
 965 Due to a mistake in the original implementation of this method, it will also
 966 accept a list of objects or hash references. This is B<deprecated> and will be
 967 removed in a future version.
 968
 969 =head2 remove_from_$rel
 970
 971 B<Currently only available for C<many_to_many> relationships.>
 972
 973 =over 4
 974
 975 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
 976
 977 =item Return Value: not defined
 978
 979 =back
 980
 981   my $role = $schema->resultset('Role')->find(1);
 982   $actor->remove_from_roles($role);
 983       # removes $role's My::DBIC::Schema::ActorRoles linking table result object
 984
 985 Removes the link between the current object and the related object. Note that
 986 the related object itself won't be deleted unless you call ->delete() on
 987 it. This method just removes the link between the two objects.
 988
 989 =head1 AUTHOR AND CONTRIBUTORS
 990
 991 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
 992
 993 =head1 LICENSE
 994
 995 You may distribute this code under the same terms as Perl itself.
 996
 997 =cut
 998
 999 1;