Rose::DB::Object::Metadata::Relationship::ManyToMany - Many to many table relationship metadata object.

  use Rose::DB::Object::Metadata::Relationship::ManyToMany;

  $rel = Rose::DB::Object::Metadata::Relationship::ManyToMany->new(...);
  $rel->make_methods(...);
  ...

    CREATE TABLE widgets
    (
      id    SERIAL PRIMARY KEY,
      name  VARCHAR(255)
    );

    CREATE TABLE colors
    (
      id    SERIAL PRIMARY KEY,
      name  VARCHAR(255)
    );

    CREATE TABLE widget_color_map
    (
      id         SERIAL PRIMARY KEY,
      widget_id  INT NOT NULL REFERENCES widgets (id),
      color_id   INT NOT NULL REFERENCES colors (id),
      UNIQUE(widget_id, color_id)
    );

  package Widget;

  use base 'Rose::DB::Object';

  __PACKAGE__->meta->setup
  (
    table => 'widgets',

    columns =>
    [
      id   => { type => 'int', primary_key => 1 },
      name => { type => 'varchar', length => 255 },
    ],

    relationships =>
    [
      # Define "many to many" relationship to get colors
      colors =>
      {
        type      => 'many to many',
        map_class => 'WidgetColorMap',

        # These are only necessary if the relationship is ambiguous
        #map_from  => 'widget',
        #map_to    => 'color',
      },
    ],
  );

  1;

  package Color;

  use base 'Rose::DB::Object';

  __PACKAGE__->meta->setup
  (
    table => 'colors',

    columns =>
    [
      id   => { type => 'int', primary_key => 1 },
      name => { type => 'varchar', length => 255 },
    ],

    relationships =>
    [
      # Define "many to many" relationship to get widgets
      widgets =>
      {
        type      => 'many to many',
        map_class => 'WidgetColorMap',

        # These are only necessary if the relationship is ambiguous
        #map_from  => 'color',
        #map_to    => 'widget',
      },
    ],
  );

  1;

  package WidgetColorMap;

  use base 'Rose::DB::Object';

  __PACKAGE__->meta->setup
  (
    table => 'widget_color_map',

    columns =>
    [
      id        => { type => 'int', primary_key => 1 },
      widget_id => { type => 'int' },
      color_id  => { type => 'int' },
    ],

    foreign_keys =>
    [
      # Define foreign keys that point to each of the two classes 
      # that this class maps between.
      color => 
      {
        class => 'Color',
        key_columns => { color_id => 'id' },
      },

      widget => 
      {
        class => 'Widget',
        key_columns => { widget_id => 'id' },
      },
    ],
  );

  1;

  INSERT INTO widgets (id, name) VALUES (1, 'Sprocket');
  INSERT INTO widgets (id, name) VALUES (2, 'Flange');

  INSERT INTO colors (id, name) VALUES (1, 'Red');
  INSERT INTO colors (id, name) VALUES (2, 'Green');
  INSERT INTO colors (id, name) VALUES (3, 'Blue');

  INSERT INTO widget_color_map (widget_id, color_id) VALUES (1, 1);
  INSERT INTO widget_color_map (widget_id, color_id) VALUES (1, 2);
  INSERT INTO widget_color_map (widget_id, color_id) VALUES (2, 3);

  use Widget;
  use Color;

  $widget = Widget->new(id => 1);
  $widget->load;

  @colors = map { $_->name } $widget->colors; # ('Red', 'Green')

  $color = Color->new(id => 1);
  $color->load;

  @widgets = map { $_->name } $color->widgets; # ('Sprocket')

package Rose::DB::Object::Metadata::Relationship::ManyToMany;

use strict;

use Carp();
use Scalar::Util qw(weaken);

use Rose::DB::Object::Metadata::Relationship;
our @ISA = qw(Rose::DB::Object::Metadata::Relationship);

use Rose::DB::Object::Exception;
use Rose::Object::MakeMethods::Generic;
use Rose::DB::Object::MakeMethods::Generic;

use Rose::DB::Object::Constants qw(PRIVATE_PREFIX);

our $VERSION = '0.784';

our $Debug = 0;

__PACKAGE__->default_auto_method_types(qw(find get_set_on_save add_on_save));

__PACKAGE__->add_common_method_maker_argument_names
(
  qw(share_db map_class map_from map_to manager_class manager_method
     manager_count_method manager_iterator_method manager_find_method
     manager_args query_args map_record_method)
);

use Rose::Object::MakeMethods::Generic
(
  boolean =>
  [
    'share_db' => { default => 1 },
  ],
);

Rose::Object::MakeMethods::Generic->make_methods
(
  { preserve_existing => 1 },
  scalar => 
  [
    __PACKAGE__->common_method_maker_argument_names,
  ],

  # These are set by the method maker when make_methods() is called

  scalar => 
  [
    'foreign_class', # class to be fetched
  ],

  hash =>
  [
    # Map from map-table columns to self-table columns
    'column_map',
  ]
);

__PACKAGE__->method_maker_info
(
  count =>
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'count',
  },

  find =>
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'find',
  },

  iterator =>
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'iterator',
  },

  get_set =>
  {
    class => 'Rose::DB::Object::MakeMethods::Generic',
    type  => 'objects_by_map',
    interface => 'get_set',
  },

  get_set_now =>
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'get_set_now',
  },

  get_set_on_save =>
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'get_set_on_save',
  },

  add_now => 
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'add_now',
  },

  add_on_save => 
  {
    class     => 'Rose::DB::Object::MakeMethods::Generic',
    type      => 'objects_by_map',
    interface => 'add_on_save',
  },
);

sub type { 'many to many' }

sub is_singular { 0 }

use constant MAP_RECORD_ATTR   => PRIVATE_PREFIX . '_map_record';
use constant MAP_RECORD_METHOD => 'map_record';

MAKE_MAP_RECORD_METHOD:
{
  my $counter = 1;

  sub make_map_record_method
  {
    my($map_to_class, $map_record_method, $map_class) = @_;

    my $key = MAP_RECORD_ATTR . '_' . $counter++;

    no strict 'refs';
    *{"${map_to_class}::$map_record_method"} = sub 
    {
      my($self) = shift;

      if(@_)
      {
        my $arg    = shift;
        my $weaken = shift;

        if(ref $arg eq 'HASH')
        {
          return $self->{$key} = $map_class->new(%$arg);
        }
        elsif(!ref $arg || !UNIVERSAL::isa($arg, $map_class))
        {
          Carp::croak "Illegal map record argument: $arg";
        }

        return $weaken ? (weaken($self->{$key} = $arg)) : ($self->{$key} = $arg);
      }

      return $self->{$key}; # ||= $map_class->new;
    };

    $map_to_class->meta->map_record_method_key($map_record_method => $key);

    return $key;
  }
}

sub manager_args
{
  my($self) = shift;

  return $self->{'manager_args'}  unless(@_);

  my $args = $self->{'manager_args'} = shift;

  if(my $method = $args->{'with_map_records'})
  {
    $method = MAP_RECORD_METHOD  unless($method =~ /^[A-Za-z_]\w*$/);

    $self->map_record_method($method);
  }

  return $args;
}

sub build_method_name_for_type
{
  my($self, $type) = @_;

  if($type eq 'get_set' || $type eq 'get_set_now' || $type eq 'get_set_on_save')
  {
    return $self->name;
  }
  elsif($type eq 'add_now' || $type eq 'add_on_save')
  {
    return 'add_' . $self->name;
  }
  elsif($type eq 'find')
  {
    return 'find_' . $self->name;
  }
  elsif($type eq 'iterator')
  {
    return $self->name . '_iterator';
  }
  elsif($type eq 'count')
  {
    return $self->name . '_count';
  }

  return undef;
}

sub sanity_check
{
  my($self) = shift;

  defined $self->map_class or 
    Carp::croak $self->type, " relationship '", $self->name,
                "' is missing a map_class";

  return 1;
}
my $i;
my %C;

sub is_ready_to_make_methods
{
  my($self) = shift;

  my $error;

  TRY:
  {
    local $@;

    # This code is (ug) duplicated from the method-maker itself, and
    # slightly modified to run here.  If the method-maker can't get all
    # the info it needs, then we're not yet ready to make these methods.
    eval
    {
      # Workaround for http://rt.perl.org/rt3/Ticket/Display.html?id=60890
      local $SIG{'__DIE__'};

      my $map_class = $self->map_class or die "Missing map class";

      unless(UNIVERSAL::isa($map_class, 'Rose::DB::Object'))
      {
        die Rose::DB::Object::Exception::ClassNotReady->new(
          "Map class $map_class not yet ready");
      }

      my $map_meta  = $map_class->meta or die
        Rose::DB::Object::Exception::ClassNotReady->new(
          "Missing meta object for $map_class");

      my $map_from  = $self->map_from;
      my $map_to    = $self->map_to;
      my $relationship = $self;

      my $target_class = $self->parent->class;
      my $meta         = $target_class->meta or die
        Rose::DB::Object::Exception::ClassNotReady->new(
          "Missing meta object for $target_class");

      my($map_to_class, $map_to_meta, $map_to_method);

      # "map" is the map table, "self" is the $target_class, and "remote"
      # is the foreign object class
      my(%map_column_to_self_method,
         %map_column_to_self_column,
         %map_method_to_remote_method);

      # Also grab the foreign object class that the mapper points to,
      # the relationship name that points back to us, and the class 
      # name of the objects we really want to fetch.
      my($require_objects, $local_rel, $foreign_class, %seen_fk);

      foreach my $item ($map_meta->foreign_keys, $map_meta->relationships)
      {
        # Track which foreign keys we've seen
        if($item->isa('Rose::DB::Object::Metadata::ForeignKey'))
        {
          $seen_fk{$item->id}++;
        }
        elsif($item->isa('Rose::DB::Object::Metadata::Relationship'))
        {
          # Skip a relationship if we've already seen the equivalent foreign key
          next  if($seen_fk{$item->id});
        }

        if($item->can('class') && $item->class eq $target_class)
        {
          # Skip if there was an explicit local relationship name and
          # this is not that name.
          unless($map_from && $item->name ne $map_from)
          {
            if(%map_column_to_self_method)
            {
              die Rose::DB::Object::Exception::ClassNotReady->new(
                "Map class $map_class has more than one foreign key " .
                "and/or 'many to one' relationship that points to the " .
                "class $target_class.  Please specify one by name " .
                "with a 'local' parameter in the 'map' hash");
            }

            $map_from = $local_rel = $item->name;

            my $map_columns = 
              $item->can('column_map') ? $item->column_map : $item->key_columns;

            # "local" and "foreign" here are relative to the *mapper* class
            while(my($local_column, $foreign_column) = each(%$map_columns))
            {
              my $foreign_method = $meta->column_accessor_method_name($foreign_column)
                or die Rose::DB::Object::Exception::ClassNotReady->new(
                     "Missing accessor method for column '$foreign_column'" .
                     " in class " . $meta->class);
              $map_column_to_self_method{$local_column} = $foreign_method;
              $map_column_to_self_column{$local_column} = $foreign_column;
            }

            next;
          }
        }

        if($item->isa('Rose::DB::Object::Metadata::ForeignKey') ||
              $item->type eq 'many to one')
        {
          # Skip if there was an explicit foreign relationship name and
          # this is not that name.
          next  if($map_to && $item->name ne $map_to);

          $map_to = $item->name;

          if($require_objects)
          {
            die Rose::DB::Object::Exception::ClassNotReady->new(
              "Map class $map_class has more than one foreign key " .
              "and/or 'many to one' relationship that points to a " .
              "class other than $target_class.  Please specify one " .
              "by name with a 'foreign' parameter in the 'map' hash");
          }

          $map_to_class = $item->class;

          unless(UNIVERSAL::isa($map_to_class, 'Rose::DB::Object'))
          {
            die Rose::DB::Object::Exception::ClassNotReady->new(
              "Map-to-class $map_to_class not yet ready");
          }

          $map_to_meta  = $map_to_class->meta or die
            Rose::DB::Object::Exception::ClassNotReady->new(
              "Missing meta object for $map_to_class");

          my $map_columns = 
            $item->can('column_map') ? $item->column_map : $item->key_columns;

          # "local" and "foreign" here are relative to the *mapper* class
          while(my($local_column, $foreign_column) = each(%$map_columns))
          {
            my $local_method = $map_meta->column_accessor_method_name($local_column)
              or die Rose::DB::Object::Exception::ClassNotReady->new(
                "Missing accessor method for column '$local_column'" .
                " in class " . $map_meta->class);

            my $foreign_method = $map_to_meta->column_accessor_method_name($foreign_column)
              or die Rose::DB::Object::Exception::ClassNotReady->new(
                "Missing accessor method for column '$foreign_column'" .
                " in class " . $map_to_meta->class);

            # local           foreign
            # Map:color_id => Color:id
            $map_method_to_remote_method{$local_method} = $foreign_method;
          }

          $require_objects = [ $item->name ];
          $foreign_class = $item->class;

          $map_to_method = $item->method_name('get_set') || 
                           $item->method_name('get_set_now') ||
                           $item->method_name('get_set_on_save') ||
                           die Rose::DB::Object::Exception::ClassNotReady->new(
                             "No 'get_*' method found for " . $item->name);
        }
      }

      unless(%map_column_to_self_method)
      {
        die Rose::DB::Object::Exception::ClassNotReady->new(
          "Could not find a foreign key or 'many to one' relationship "  .
          "in $map_class that points to $target_class");
      }

      unless(%map_column_to_self_column)
      {
        die Rose::DB::Object::Exception::ClassNotReady->new(
          "Could not find a foreign key or 'many to one' relationship " .
          "in $map_class that points to " . ($map_to_class || $map_to));
      }

      unless($require_objects)
      {
        # Make a second attempt to find a a suitable foreign relationship in the
        # map class, this time looking for links back to $target_class so long as
        # it's a different relationship than the one used in the local link.
        foreach my $item ($map_meta->foreign_keys, $map_meta->relationships)
        {
          # Skip a relationship if we've already seen the equivalent foreign key
          if($item->isa('Rose::DB::Object::Metadata::Relationship'))
          {
            next  if($seen_fk{$item->id});
          }

          if(($item->isa('Rose::DB::Object::Metadata::ForeignKey') ||
             $item->type eq 'many to one') &&
             $item->class eq $target_class && $item->name ne $local_rel)
          {  
            if($require_objects)
            {
              die Rose::DB::Object::Exception::ClassNotReady->new(
                "Map class $map_class has more than two foreign keys " .
                "and/or 'many to one' relationships that points to a " .
                "$target_class.  Please specify which ones to use " .
                "by including 'local' and 'foreign' parameters in the " .
                "'map' hash");
            }

            $require_objects = [ $item->name ];
            $foreign_class = $item->class;
            $map_to_method = $item->method_name('get_set') ||
                             $item->method_name('get_set_now') ||
                             $item->method_name('get_set_on_save') ||
                             die Rose::DB::Object::Exception::ClassNotReady->new(
                               "No 'get_*' method found for " . $item->name);
          }
        }
      }

      unless($require_objects)
      {
        die Rose::DB::Object::Exception::ClassNotReady->new(
          "Could not find a foreign key or 'many to one' relationship " .
          "in $map_class that points to a class other than $target_class");
      }

      unless($foreign_class)
      {
        die Rose::DB::Object::Exception::ClassNotReady->new("Missing foreign class");
      }
    };

    $error = $@;
  }

  if($error)
  {
    if($Debug || $Rose::DB::Object::Metadata::Debug)
    {
      my $err = $error;
      $err =~ s/ at .*//;
      warn $self->parent->class, ': many-to-many relationship ', $self->name, " NOT READY - $err";
    }

    die $error  unless(UNIVERSAL::isa($error, 'Rose::DB::Object::Exception::ClassNotReady'));
  }

  return $error ? 0 : 1;
}

sub perl_relationship_definition_attributes
{
  grep { $_ !~ /^(?:column_map|foreign_class)$/ }
    shift->SUPER::perl_relationship_definition_attributes(@_);
}

1;

__END__