NAME

Rose::DB::Object::Metadata::Relationship - Base class for table relationship metadata objects.

SYNOPSIS

  package MyRelationshipType;

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

DESCRIPTION

This is the base class for objects that store and manipulate database table relationship metadata. Relationship metadata objects are responsible for creating object methods that fetch and/or manipulate objects from foreign tables. See the Rose::DB::Object::Metadata documentation for more information.

CONSTRUCTOR

new PARAMS

Constructs a new object based on PARAMS, where PARAMS are name/value pairs. Any object method is a valid parameter name.

OBJECT METHODS

class [CLASS]

Get or set the name of the Rose::DB::Object-derived class that fronts the foreign table referenced by this relationship.

make_method PARAMS

Create an object method used to fetch and/or manipulate objects from foreign tables. 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 method created, and its name must match the method_name (or name if method_name is undefined).

method_maker_arguments

Returns a hash (in list context) or a reference to a hash (in scalar context) or arguments that will be passed (as a hash ref) to the call to the make_methods() class method of the method_maker_class, as shown in the make_method example above.

The default implementation populates the hash with the defined return values of the object methods named by method_maker_argument_names. (Method names that return undefined values are not included in the hash.)

method_maker_argument_names

Returns a list of methods to call in order to generate the method_maker_arguments hash.

method_maker_class

Returns the name of the Rose::Object::MakeMethods-derived class used to create the object method that will fetch and/or manipulate objects from foreign tables. You must override this method in your subclass. The default implementation causes a fatal error if called.

method_maker_type

Returns the method type, which is passed to the call to the make_methods() class method of the method_maker_class, as shown in the make_method example above. You must override this method in your subclass. The default implementation causes a fatal error if called.

method_name [NAME]

Get or set the name of the object method to be created for this relationship. 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 relationship. This name must be unique among all other relationships for a given Rose::DB::Object-derived class.

type

Returns a string describing the type of relationship. You must override this method in your subclass. The default implementation causes a fatal error if called.

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.