NAME

Rose::DB::Object::Metadata::ForeignKey - Foreign key metadata.

SYNOPSIS

use Rose::DB::Object::Metadata::ForeignKey;

$fk = Rose::DB::Object::Metadata::ForeignKey->new(...);
$fk->make_method(...);
...

DESCRIPTION

Objects of this class store and manipulate metadata for foreign keys in a database table. It stores information about which columns in the local table map to which columns in the foreign table, and is responsible for creating an accessor method for the foreign object.

This class represents (and will create an accessor method for) the thing referenced by the foreign key column(s). You'll still need accessor method(s) for the foreign key column(s) themselves.

Both the local table and the foreign table will need Rose::DB::Object-derived classes fronting them.

Since there is a lot of overlap in responsibilities, this class inherits from Rose::DB::Object::Metadata::Column. Inherited methods that are not overridden will not be documented a second time here. See the Rose::DB::Object::Metadata::Column documentation for more information.

OBJECT METHODS

class [CLASS]

Get or set the class name of the Rose::DB::Object-derived object that encapsulates rows from the table referenced by the foreign key column(s).

key_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.

key_columns [HASH | HASHREF]

Get or set a reference to a hash that maps local column names to foreign column names in the table referenced by the foreign key.

make_method PARAMS

Create an object method used to fetch the Rose::DB::Object-derived object referred to by the foreign key. To do this, the make_methods() class method of the method_maker_class is called. PARAMS are name/value pairs. Valid PARAMS are:

options HASHREF

A reference to a hash of options that will be passed as the first argument to the call to the make_methods() class method of the method_maker_class. This parameter is required, and the HASHREF must include a value for the key target_class, which make_methods() needs in order to determine where to make the method.

The call to make_methods() looks something like this:

my $method_name = $self->method_name;

# Use "name" if "method_name" is undefined
unless(defined $method_name)
{
  # ...and set "method_name" so it's defined now
  $method_name = $self->method_name($self->name);
}

$self->method_maker_class->make_methods(
  $args{'options'}, 
  $self->method_maker_type => 
  [
    $method_name => scalar $self->method_maker_arguments
  ]);

where $args{'options'} is the value of the "options" PARAM.

The method_maker_class is expected to be a subclass of (or otherwise conform to the interface of) Rose::Object::MakeMethods. See the Rose::Object::MakeMethods documentation for more information on the interface, and the make_methods() method in particular.

More than one method may be created, but there must be at least one accessor method created, and its name must match the method_name (or name if method_name is undefined).

method_maker_class

Returns Rose::DB::Object::MakeMethods::Generic.

method_maker_type

Returns object_by_key.

method_name [NAME]

Get or set the name of the object method to be created for this foreign key. This may be left undefined if the desired method name is stored in name instead. Once the method is actually created, the method_name will be set.

name [NAME]

Get or set the name of the foreign key. This name must be unique among all other foreign keys for a given Rose::DB::Object-derived class.

share_db [BOOL]

Get or set the boolean flag that determines whether the db attribute of the current object is shared with the foreign object to be fetched. The default value is true.

type

Returns "foreign key".

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

Copyright (c) 2005 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.