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       $self->throw_exception ($_) if $self->in_storage;
 487       $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION;  # RV, no return()
 488     };
 489
 490     # keep in mind that the following if() block is part of a do{} - no return()s!!!
 491     if ($is_crosstable) {
 492       $self->throw_exception (
 493         "A cross-table relationship condition returned for statically declared '$rel'"
 494       ) unless ref $rel_info->{cond} eq 'CODE';
 495
 496       # A WHOREIFFIC hack to reinvoke the entire condition resolution
 497       # with the correct alias. Another way of doing this involves a
 498       # lot of state passing around, and the @_ positions are already
 499       # mapped out, making this crap a less icky option.
 500       #
 501       # The point of this exercise is to retain the spirit of the original
 502       # $obj->search_related($rel) where the resulting rset will have the
 503       # root alias as 'me', instead of $rel (as opposed to invoking
 504       # $rs->search_related)
 505
 506       local $rsrc->{_relationships}{me} = $rsrc->{_relationships}{$rel};  # make the fake 'me' rel
 507       my $obj_table_alias = lc($rsrc->source_name) . '__row';
 508       $obj_table_alias =~ s/\W+/_/g;
 509
 510       $rsrc->resultset->search(
 511         $self->ident_condition($obj_table_alias),
 512         { alias => $obj_table_alias },
 513       )->search_related('me', $query, $attrs)
 514     }
 515     else {
 516       # FIXME - this conditional doesn't seem correct - got to figure out
 517       # at some point what it does. Also the entire UNRESOLVABLE_CONDITION
 518       # business seems shady - we could simply not query *at all*
 519       if ($cond eq $DBIx::Class::ResultSource::UNRESOLVABLE_CONDITION) {
 520         my $reverse = $rsrc->reverse_relationship_info($rel);
 521         foreach my $rev_rel (keys %$reverse) {
 522           if ($reverse->{$rev_rel}{attrs}{accessor} && $reverse->{$rev_rel}{attrs}{accessor} eq 'multi') {
 523             weaken($attrs->{related_objects}{$rev_rel}[0] = $self);
 524           } else {
 525             weaken($attrs->{related_objects}{$rev_rel} = $self);
 526           }
 527         }
 528       }
 529       elsif (ref $cond eq 'ARRAY') {
 530         $cond = [ map {
 531           if (ref $_ eq 'HASH') {
 532             my $hash;
 533             foreach my $key (keys %$_) {
 534               my $newkey = $key !~ /\./ ? "me.$key" : $key;
 535               $hash->{$newkey} = $_->{$key};
 536             }
 537             $hash;
 538           } else {
 539             $_;
 540           }
 541         } @$cond ];
 542       }
 543       elsif (ref $cond eq 'HASH') {
 544        foreach my $key (grep { ! /\./ } keys %$cond) {
 545           $cond->{"me.$key"} = delete $cond->{$key};
 546         }
 547       }
 548
 549       $query = ($query ? { '-and' => [ $cond, $query ] } : $cond);
 550       $rsrc->related_source($rel)->resultset->search(
 551         $query, $attrs
 552       );
 553     }
 554   };
 555 }
 556
 557 =head2 search_related
 558
 559 =over 4
 560
 561 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 562
 563 =item Return Value: L<$resultset|DBIx::Class::ResultSet> (scalar context) | L<@result_objs|DBIx::Class::Manual::ResultClass> (list context)
 564
 565 =back
 566
 567 Run a search on a related resultset. The search will be restricted to the
 568 results represented by the L<DBIx::Class::ResultSet> it was called
 569 upon.
 570
 571 See L<DBIx::Class::ResultSet/search_related> for more information.
 572
 573 =cut
 574
 575 sub search_related {
 576   return shift->related_resultset(shift)->search(@_);
 577 }
 578
 579 =head2 search_related_rs
 580
 581 This method works exactly the same as search_related, except that
 582 it guarantees a resultset, even in list context.
 583
 584 =cut
 585
 586 sub search_related_rs {
 587   return shift->related_resultset(shift)->search_rs(@_);
 588 }
 589
 590 =head2 count_related
 591
 592 =over 4
 593
 594 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 595
 596 =item Return Value: $count
 597
 598 =back
 599
 600 Returns the count of all the rows in the related resultset, restricted by the
 601 current result or where conditions.
 602
 603 =cut
 604
 605 sub count_related {
 606   shift->search_related(@_)->count;
 607 }
 608
 609 =head2 new_related
 610
 611 =over 4
 612
 613 =item Arguments: $rel_name, \%col_data
 614
 615 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 616
 617 =back
 618
 619 Create a new result object of the related foreign class.  It will magically set
 620 any foreign key columns of the new object to the related primary key columns
 621 of the source object for you.  The newly created result will not be saved into
 622 your storage until you call L<DBIx::Class::Row/insert> on it.
 623
 624 =cut
 625
 626 sub new_related {
 627   my ($self, $rel, $values) = @_;
 628
 629   # FIXME - this is a bad position for this (also an identical copy in
 630   # set_from_related), but I have no saner way to hook, and I absolutely
 631   # want this to throw at least for coderefs, instead of the "insert a NULL
 632   # when it gets hard" insanity --ribasushi
 633   #
 634   # sanity check - currently throw when a complex coderef rel is encountered
 635   # FIXME - should THROW MOAR!
 636
 637   if (ref $self) {  # cdbi calls this as a class method, /me vomits
 638
 639     my $rsrc = $self->result_source;
 640     my $rel_info = $rsrc->relationship_info($rel)
 641       or $self->throw_exception( "No such relationship '$rel'" );
 642     my (undef, $crosstable, $nonequality_foreign_columns) = $rsrc->_resolve_condition (
 643       $rel_info->{cond}, $rel, $self, $rel
 644     );
 645
 646     $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
 647       if $crosstable;
 648
 649     if (
 650       $nonequality_foreign_columns
 651         and
 652       my @unspecified_rel_condition_chunks = grep { ! exists $values->{$_} } @$nonequality_foreign_columns
 653     ) {
 654       $self->throw_exception(sprintf (
 655         "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
 656         $rel,
 657         map { "'$_'" } @unspecified_rel_condition_chunks
 658       ));
 659     }
 660   }
 661
 662   return $self->search_related($rel)->new_result($values);
 663 }
 664
 665 =head2 create_related
 666
 667 =over 4
 668
 669 =item Arguments: $rel_name, \%col_data
 670
 671 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 672
 673 =back
 674
 675   my $result = $obj->create_related($rel_name, \%col_data);
 676
 677 Creates a new result object, similarly to new_related, and also inserts the
 678 result's data into your storage medium. See the distinction between C<create>
 679 and C<new> in L<DBIx::Class::ResultSet> for details.
 680
 681 =cut
 682
 683 sub create_related {
 684   my $self = shift;
 685   my $rel = shift;
 686   my $obj = $self->new_related($rel, @_)->insert;
 687   delete $self->{related_resultsets}->{$rel};
 688   return $obj;
 689 }
 690
 691 =head2 find_related
 692
 693 =over 4
 694
 695 =item Arguments: $rel_name, \%col_data | @pk_values, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 696
 697 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass> | undef
 698
 699 =back
 700
 701   my $result = $obj->find_related($rel_name, \%col_data);
 702
 703 Attempt to find a related object using its primary key or unique constraints.
 704 See L<DBIx::Class::ResultSet/find> for details.
 705
 706 =cut
 707
 708 sub find_related {
 709   #my ($self, $rel, @args) = @_;
 710   return shift->search_related(shift)->find(@_);
 711 }
 712
 713 =head2 find_or_new_related
 714
 715 =over 4
 716
 717 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 718
 719 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 720
 721 =back
 722
 723 Find a result object of a related class.  See L<DBIx::Class::ResultSet/find_or_new>
 724 for details.
 725
 726 =cut
 727
 728 sub find_or_new_related {
 729   my $self = shift;
 730   my $obj = $self->find_related(@_);
 731   return defined $obj ? $obj : $self->new_related(@_);
 732 }
 733
 734 =head2 find_or_create_related
 735
 736 =over 4
 737
 738 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 739
 740 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 741
 742 =back
 743
 744 Find or create a result object of a related class. See
 745 L<DBIx::Class::ResultSet/find_or_create> for details.
 746
 747 =cut
 748
 749 sub find_or_create_related {
 750   my $self = shift;
 751   my $obj = $self->find_related(@_);
 752   return (defined($obj) ? $obj : $self->create_related(@_));
 753 }
 754
 755 =head2 update_or_create_related
 756
 757 =over 4
 758
 759 =item Arguments: $rel_name, \%col_data, { key => $unique_constraint, L<%attrs|DBIx::Class::ResultSet/ATTRIBUTES> }?
 760
 761 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 762
 763 =back
 764
 765 Update or create a result object of a related class. See
 766 L<DBIx::Class::ResultSet/update_or_create> for details.
 767
 768 =cut
 769
 770 sub update_or_create_related {
 771   #my ($self, $rel, @args) = @_;
 772   shift->related_resultset(shift)->update_or_create(@_);
 773 }
 774
 775 =head2 set_from_related
 776
 777 =over 4
 778
 779 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
 780
 781 =item Return Value: not defined
 782
 783 =back
 784
 785   $book->set_from_related('author', $author_obj);
 786   $book->author($author_obj);                      ## same thing
 787
 788 Set column values on the current object, using related values from the given
 789 related object. This is used to associate previously separate objects, for
 790 example, to set the correct author for a book, find the Author object, then
 791 call set_from_related on the book.
 792
 793 This is called internally when you pass existing objects as values to
 794 L<DBIx::Class::ResultSet/create>, or pass an object to a belongs_to accessor.
 795
 796 The columns are only set in the local copy of the object, call L</update> to
 797 set them in the storage.
 798
 799 =cut
 800
 801 sub set_from_related {
 802   my ($self, $rel, $f_obj) = @_;
 803
 804   my $rsrc = $self->result_source;
 805   my $rel_info = $rsrc->relationship_info($rel)
 806     or $self->throw_exception( "No such relationship '$rel'" );
 807
 808   if (defined $f_obj) {
 809     my $f_class = $rel_info->{class};
 810     $self->throw_exception( "Object '$f_obj' isn't a ".$f_class )
 811       unless blessed $f_obj and $f_obj->isa($f_class);
 812   }
 813
 814
 815   # FIXME - this is a bad position for this (also an identical copy in
 816   # new_related), but I have no saner way to hook, and I absolutely
 817   # want this to throw at least for coderefs, instead of the "insert a NULL
 818   # when it gets hard" insanity --ribasushi
 819   #
 820   # sanity check - currently throw when a complex coderef rel is encountered
 821   # FIXME - should THROW MOAR!
 822   my ($cond, $crosstable, $nonequality_foreign_columns) = $rsrc->_resolve_condition (
 823     $rel_info->{cond}, $f_obj, $rel, $rel
 824   );
 825   $self->throw_exception("Custom relationship '$rel' does not resolve to a join-free condition fragment")
 826     if $crosstable;
 827
 828   $self->throw_exception(sprintf (
 829     "Custom relationship '%s' not definitive - returns conditions instead of values for column(s): %s",
 830     $rel,
 831     map { "'$_'" } @$nonequality_foreign_columns
 832   )) if $nonequality_foreign_columns;
 833
 834   $self->set_columns($cond);
 835
 836   return 1;
 837 }
 838
 839 =head2 update_from_related
 840
 841 =over 4
 842
 843 =item Arguments: $rel_name, L<$result|DBIx::Class::Manual::ResultClass>
 844
 845 =item Return Value: not defined
 846
 847 =back
 848
 849   $book->update_from_related('author', $author_obj);
 850
 851 The same as L</"set_from_related">, but the changes are immediately updated
 852 in storage.
 853
 854 =cut
 855
 856 sub update_from_related {
 857   my $self = shift;
 858   $self->set_from_related(@_);
 859   $self->update;
 860 }
 861
 862 =head2 delete_related
 863
 864 =over 4
 865
 866 =item Arguments: $rel_name, $cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
 867
 868 =item Return Value: $underlying_storage_rv
 869
 870 =back
 871
 872 Delete any related row, subject to the given conditions.  Internally, this
 873 calls:
 874
 875   $self->search_related(@_)->delete
 876
 877 And returns the result of that.
 878
 879 =cut
 880
 881 sub delete_related {
 882   my $self = shift;
 883   my $obj = $self->search_related(@_)->delete;
 884   delete $self->{related_resultsets}->{$_[0]};
 885   return $obj;
 886 }
 887
 888 =head2 add_to_$rel
 889
 890 B<Currently only available for C<has_many>, C<many_to_many> and 'multi' type
 891 relationships.>
 892
 893 =head3 has_many / multi
 894
 895 =over 4
 896
 897 =item Arguments: \%col_data
 898
 899 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 900
 901 =back
 902
 903 Creates/inserts a new result object.  Internally, this calls:
 904
 905   $self->create_related($rel, @_)
 906
 907 And returns the result of that.
 908
 909 =head3 many_to_many
 910
 911 =over 4
 912
 913 =item Arguments: (\%col_data | L<$result|DBIx::Class::Manual::ResultClass>), \%link_col_data?
 914
 915 =item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
 916
 917 =back
 918
 919   my $role = $schema->resultset('Role')->find(1);
 920   $actor->add_to_roles($role);
 921       # creates a My::DBIC::Schema::ActorRoles linking table result object
 922
 923   $actor->add_to_roles({ name => 'lead' }, { salary => 15_000_000 });
 924       # creates a new My::DBIC::Schema::Role result object and the linking table
 925       # object with an extra column in the link
 926
 927 Adds a linking table object. If the first argument is a hash reference, the
 928 related object is created first with the column values in the hash. If an object
 929 reference is given, just the linking table object is created. In either case,
 930 any additional column values for the linking table object can be specified in
 931 C<\%link_col_data>.
 932
 933 See L<DBIx::Class::Relationship/many_to_many> for additional details.
 934
 935 =head2 set_$rel
 936
 937 B<Currently only available for C<many_to_many> relationships.>
 938
 939 =over 4
 940
 941 =item Arguments: (\@hashrefs_of_col_data | L<\@result_objs|DBIx::Class::Manual::ResultClass>), $link_vals?
 942
 943 =item Return Value: not defined
 944
 945 =back
 946
 947   my $actor = $schema->resultset('Actor')->find(1);
 948   my @roles = $schema->resultset('Role')->search({ role =>
 949      { '-in' => ['Fred', 'Barney'] } } );
 950
 951   $actor->set_roles(\@roles);
 952      # Replaces all of $actor's previous roles with the two named
 953
 954   $actor->set_roles(\@roles, { salary => 15_000_000 });
 955      # Sets a column in the link table for all roles
 956
 957
 958 Replace all the related objects with the given reference to a list of
 959 objects. This does a C<delete> B<on the link table resultset> to remove the
 960 association between the current object and all related objects, then calls
 961 C<add_to_$rel> repeatedly to link all the new objects.
 962
 963 Note that this means that this method will B<not> delete any objects in the
 964 table on the right side of the relation, merely that it will delete the link
 965 between them.
 966
 967 Due to a mistake in the original implementation of this method, it will also
 968 accept a list of objects or hash references. This is B<deprecated> and will be
 969 removed in a future version.
 970
 971 =head2 remove_from_$rel
 972
 973 B<Currently only available for C<many_to_many> relationships.>
 974
 975 =over 4
 976
 977 =item Arguments: L<$result|DBIx::Class::Manual::ResultClass>
 978
 979 =item Return Value: not defined
 980
 981 =back
 982
 983   my $role = $schema->resultset('Role')->find(1);
 984   $actor->remove_from_roles($role);
 985       # removes $role's My::DBIC::Schema::ActorRoles linking table result object
 986
 987 Removes the link between the current object and the related object. Note that
 988 the related object itself won't be deleted unless you call ->delete() on
 989 it. This method just removes the link between the two objects.
 990
 991 =head1 AUTHOR AND CONTRIBUTORS
 992
 993 See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
 994
 995 =head1 LICENSE
 996
 997 You may distribute this code under the same terms as Perl itself.
 998
 999 =cut
1000
1001 1;