librose-db-object-perl 1:0.815-1 / usr / share / perl5 / Rose / DB / Object / Metadata / Relationship / OneToMany.pm

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

use strict;

use Carp();

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

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

our $Debug = 0;

our $VERSION = '0.781';

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

__PACKAGE__->add_common_method_maker_argument_names
(
  qw(class share_db key_columns manager_class manager_method 
     manager_count_method manager_iterator_method manager_find_method
     manager_args query_args join_args)
);

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

  hash =>
  [
    key_column  => { hash_key  => 'key_columns' },
    key_columns => { interface => 'get_set_all' },
  ],
);

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

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

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

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

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

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

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

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

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

sub type { 'one to many' }

sub is_singular { 0 }

sub foreign_class { shift->class(@_) }

*map_column = \&key_column;
*column_map = \&key_columns;

sub id
{
  my($self) = shift;

  my $column_map = $self->column_map;

  return $self->parent->class . ' ' .   $self->class . ' ' . 
    join("\0", map { join("\1", lc $_, lc $column_map->{$_}) } sort keys %$column_map);
    #join("\0", map { $_ . '=' . ($self->$_() || 0) } qw(required));
}

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 is_ready_to_make_methods 
{
  my($self) = shift;

  if($Debug || $Rose::DB::Object::Metadata::Debug)
  {
    my $error;

    if(!$self->class)
    {
      $error = "does not belong to a class";
    }
    elsif(!$self->key_columns && !$self->query_args)
    {
      $error = "has no key columns or query args";
    }

    warn $self->parent->class, ': one-to-many relationship ', $self->name, " NOT READY - $error"
      if($error);
  }

  return $self->class && ($self->key_columns || $self->query_args) ? 1 : 0;
}

1;

__END__

=head1 NAME

Rose::DB::Object::Metadata::Relationship::OneToMany - One to many table relationship metadata object.

=head1 SYNOPSIS

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

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

=head1 DESCRIPTION

Objects of this class store and manipulate metadata for relationships in which a single row from one table refers to multiple rows in another table.

This class inherits from L<Rose::DB::Object::Metadata::Relationship>. Inherited methods that are not overridden will not be documented a second time here.  See the L<Rose::DB::Object::Metadata::Relationship> documentation for more information.

=head1 METHOD MAP

=over 4

=item C<count>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'count'> ...

=item C<find>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'find'> ...

=item C<iterator>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'iterator'> ...

=item C<get_set>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, 
C<interface =E<gt> 'get_set'> ...

=item C<get_set_now>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'get_set_now'> ...

=item C<get_set_on_save>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'get_set_on_save'> ...

=item C<add_now>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'add_now'> ...

=item C<add_on_save>

L<Rose::DB::Object::MakeMethods::Generic>, L<objects_by_key|Rose::DB::Object::MakeMethods::Generic/objects_by_key>, C<interface =E<gt> 'add_on_save'> ...

=back

See the L<Rose::DB::Object::Metadata::Relationship|Rose::DB::Object::Metadata::Relationship/"MAKING METHODS"> documentation for an explanation of this method map.

=head1 CLASS METHODS

=over 4

=item B<default_auto_method_types [TYPES]>

Get or set the default list of L<auto_method_types|Rose::DB::Object::Metadata::Relationship/auto_method_types>.  TYPES should be a list of relationship method types.  Returns the list of default relationship method types (in list context) or a reference to an array of the default relationship method types (in scalar context).  The default list contains "find", "get_set_on_save", and "add_on_save".

=back

=head1 OBJECT METHODS

=over 4

=item B<build_method_name_for_type TYPE>

Return a method name for the relationship method type TYPE.  

For the method types "get_set", "get_set_now", and "get_set_on_save", the relationship's L<name|Rose::DB::Object::Metadata::Relationship/name> is returned.

For the method types "add_now" and "add_on_save", the relationship's L<name|Rose::DB::Object::Metadata::Relationship/name> prefixed with "add_" is returned.

For the method type "find", the relationship's L<name|Rose::DB::Object::Metadata::Relationship/name> prefixed with "find_" is returned.

For the method type "count", the relationship's L<name|Rose::DB::Object::Metadata::Relationship/name> suffixed with "_count" is returned.

For the method type "iterator", the relationship's L<name|Rose::DB::Object::Metadata::Relationship/name> suffixed with "_iterator" is returned.

Otherwise, undef is returned.

=item B<is_singular>

Returns false.

=item B<manager_class [CLASS]>

Get or set the name of the L<Rose::DB::Object::Manager>-derived class used to fetch objects.  The L<make_methods|Rose::DB::Object::Metadata::Relationship/make_methods> method will use L<Rose::DB::Object::Manager> if this value is left undefined.

B<Note:> when the name of a relationship that has C<manager_args> is used in a L<Rose::DB::Object::Manager> L<with_objects|Rose::DB::Object::Manager/with_objects> or L<require_objects|Rose::DB::Object::Manager/require_objects> parameter value, I<only> the L<sort_by|Rose::DB::Object::Manager/sort_by> argument will be copied from C<manager_args> and incorporated into the query.

=item B<manager_method [METHOD]>

Get or set the name of the L<manager_class|/manager_class> class method to call when fetching objects.  The L<make_methods|Rose::DB::Object::Metadata::Relationship/make_methods> method will use L<get_objects|Rose::DB::Object::Manager/get_objects> if this value is left undefined.

=item B<manager_count_method [METHOD]>

Get or set the name of the L<manager_class|/manager_class> class method to call when counting objects.  The L<make_methods|Rose::DB::Object::Metadata::Relationship/make_methods> method will use L<get_objects_count|Rose::DB::Object::Manager/get_objects_count> if this value is left undefined.

=item B<manager_iterator_method [METHOD]>

Get or set the name of the L<manager_class|/manager_class> class method to call when creating an iterator.  The L<make_methods|Rose::DB::Object::Metadata::Relationship/make_methods> method will use L<get_objects_iterator|Rose::DB::Object::Manager/get_objects_iterator> if this value is left undefined.

=item B<manager_args [HASHREF]>

Get or set a reference to a hash of name/value arguments to pass to the L<manager_method|/manager_method> when fetching objects.  For example, this can be used to enforce a particular sort order for objects fetched via this relationship.  For example:

  Product->meta->add_relationship
  (
    code_names =>
    {
      type         => 'one to many',
      class        => 'CodeName',
      column_map   => { id => 'product_id' },
      manager_args => 
      {
        sort_by => CodeName->meta->table . '.name',
      },
    },
  );

This would ensure that a C<Product>'s C<code_names()> are listed in alphabetical order.  Note that the "name" column is prefixed by the name of the table fronted by the C<CodeName> class.  This is important because several tables may have a column named "name."  If this relationship is used to form a JOIN in a query along with one of those tables, then the "name" column will be ambiguous.  Adding a table name prefix disambiguates the column name.

Also note that the table name is not hard-coded.  Instead, it is fetched from the L<Rose::DB::Object>-derived class that fronts the table.  This is more verbose, but is a much better choice than including the literal table name when it comes to long-term maintenance of the code.

See the documentation for L<Rose::DB::Object::Manager>'s L<get_objects|Rose::DB::Object::Manager/get_objects> method for a full list of valid arguments for use with the C<manager_args> parameter, but remember that you can define your own custom L<manager_class|/manager_class> and thus can also define what kinds of arguments C<manager_args> will accept.

=item B<map_column LOCAL [, FOREIGN]>

If passed a local column name LOCAL, return the corresponding column name in the foreign table.  If passed both a local column name LOCAL and a foreign column name FOREIGN, set the local/foreign mapping and return the foreign column name.

=item B<column_map [HASH | HASHREF]>

Get or set a reference to a hash that maps local column names to foreign column names.

=item B<query_args [ARRAYREF]>

Get or set a reference to an array of query arguments to add to the L<query|Rose::DB::Object::Manager/query> passed to the L<manager_method|/manager_method> when fetching objects.

=item B<type>

Returns "one to many".

=back

=head1 AUTHOR

John C. Siracusa (siracusa@gmail.com)

=head1 LICENSE

Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.