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_methods(...);
         ...

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.

       This class will create methods 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 must have Rose::DB::Object-derived classes
       fronting them.

       Foreign keys can represent both "one to one" and "many to one" relationships.  To choose,
       set the relationship_type attribute to either "one to one" or "many to one".  The default
       is "many to one".

   MAKING METHODS
       A Rose::DB::Object::Metadata::ForeignKey-derived object is responsible for creating object
       methods that manipulate objects referenced by a foreign key.  Each foreign key object can
       make zero or more methods for each available foreign key method type.  A foreign key
       method type describes the purpose of a method.  The default list of foreign key method
       types contains only one type:

       "get_set"
           A method that returns the object referenced by the foreign key.

       Methods are created by calling make_methods.  A list of method types can be passed to the
       call to make_methods.  If absent, the list of method types is determined by the
       auto_method_types method.  A list of all possible method types is available through the
       available_method_types method.

       These methods make up the "public" interface to foreign key method creation.  There are,
       however, several "protected" methods which are used internally to implement the methods
       described above.  (The word "protected" is used here in a vaguely C++ sense, meaning
       "accessible to subclasses, but not to the public.")  Subclasses will probably find it
       easier to override and/or call these protected methods in order to influence the behavior
       of the "public" method maker methods.

       A Rose::DB::Object::Metadata::ForeignKey object delegates method creation to a
       Rose::Object::MakeMethods-derived class.  Each Rose::Object::MakeMethods-derived class has
       its own set of method types, each of which takes it own set of arguments.

       Using this system, four pieces of information are needed to create a method on behalf of a
       Rose::DB::Object::Metadata::ForeignKey-derived object:

       •   The foreign key method type (e.g., "get_set")

       •   The method maker class (e.g., Rose::DB::Object::MakeMethods::Generic)

       •   The method maker method type (e.g., object_by_key)

       •   The method maker arguments (e.g., "interface => 'get_set'")

       This information can be organized conceptually into a "method map" that connects a foreign
       key method type to a method maker class and, finally, to one particular method type within
       that class, and its arguments.

       The default method map for Rose::DB::Object::Metadata::ForeignKey is:

       "get_set"
           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface => 'get_set'" ...

       "get_set_now"
           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface => 'get_set_now'"
           ...

       "get_set_on_save"
           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface =>
           'get_set_on_save'" ...

       "delete_now"
           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface => 'delete_now'" ...

       "delete_on_save"
           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface => 'delete_on_save'"
           ...

       Each item in the map is a foreign key method type.  For each foreign key method type, the
       method maker class, the method maker method type, and the "interesting" method maker
       arguments are listed, in that order.

       The "..." in the method maker arguments is meant to indicate that arguments have been
       omitted.  Arguments that are common to all foreign key method types are routinely omitted
       from the method map for the sake of brevity.

       The purpose of documenting the method map is to answer the question, "What kind of
       method(s) will be created by this foreign key object for a given method type?"  Given the
       method map, it's possible to read the documentation for each method maker class to
       determine how methods of the specified type behave when passed the listed arguments.

       Remember, the existence and behavior of the method map is really implementation detail.  A
       foreign key object is free to implement the public method-making interface however it
       wants, without regard to any conceptual or actual method map.

CLASS METHODS

       default_auto_method_types [TYPES]
           Get or set the default list of auto_method_types.  TYPES should be a list of foreign
           key method types.  Returns the list of default foreign key method types (in list
           context) or a reference to an array of the default foreign key method types (in scalar
           context).  The default list contains the "get_set_on_save" and "delete_on_save"
           foreign key method types.

OBJECT METHODS

       available_method_types
           Returns the full list of foreign key method types supported by this class.

       auto_method_types [TYPES]
           Get or set the list of foreign key method types that are automatically created when
           make_methods is called without an explicit list of foreign key method types.  The
           default list is determined by the default_auto_method_types class method.

       build_method_name_for_type TYPE
           Return a method name for the foreign key method type TYPE.  The default implementation
           returns the following.

           For the method types "get_set", "get_set_now", and "get_set_on_save", the foreign
           key's name is returned.

           For the method types "delete_now" and "delete_on_save", the foreign key's name
           prefixed with "delete_" is returned.

           Otherwise, undef is returned.

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

       column_map [HASH | HASHREF]
           This is an alias for the key_columns method.

       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 hash that maps local column names to foreign column names in the table
           referenced by the foreign key.  Returns a reference to a hash in scalar context, or a
           list of key/value pairs in list context.

       make_methods PARAMS
           Create object method used to manipulate object referenced by the foreign key.  Any
           applicable column triggers are also added.  PARAMS are name/value pairs.  Valid PARAMS
           are:

           "preserve_existing BOOL"
               Boolean flag that indicates whether or not to preserve existing methods in the
               case of a name conflict.

           "replace_existing BOOL"
               Boolean flag that indicates whether or not to replace existing methods in the case
               of a name conflict.

           "target_class CLASS"
               The class in which to make the method(s).  If omitted, it defaults to the calling
               class.

           "types ARRAYREF"
               A reference to an array of foreign key method types to be created.  If omitted, it
               defaults to the list of foreign key method types returned by auto_method_types.

           If any of the methods could not be created for any reason, a fatal error will occur.

       methods MAP
           Set the list of auto_method_types and method names all at once.  MAP should be a
           reference to a hash whose keys are method types and whose values are either undef or
           method names.  If a value is undef, then the method name for that method type will be
           generated by calling build_method_name_for_type|/build_method_name_for_type, as usual.
           Otherwise, the specified method name will be used.

       method_name TYPE [, NAME]
           Get or set the name of the relationship method of type TYPE.

       method_types [TYPES]
           This method is an alias for the auto_method_types method.

       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.

       referential_integrity [BOOL]
           Get or set the boolean value that determines what happens when the local key columns
           have defined values, but the object they point to is not found.  If true, a fatal
           error will occur when the methods that fetch objects through this foreign key are
           called.  If false, then the methods will simply return undef.  The default is true.

       rel_type [TYPE]
           This method is an alias for the relationship_type method described below.

       relationship_type [TYPE]
           Get or set the relationship type represented by this foreign key.  Valid values for
           TYPE are "one to one" and "many to one".

       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.

       soft [BOOL]
           This method is the mirror image of the referential_integrity method.   Passing a true
           is the same thing as setting referential_integrity to false, and vice versa.
           Similarly, the return value is the logical negation of referential_integrity.

       type
           Returns "foreign key".

       with_column_triggers [BOOL]
           Get or set a boolean value that indicates whether or not triggers should be added to
           the key columns in an attempt to keep foreign objects and foreign key columns in sync.
           Defaults to false.

PROTECTED API

       These methods are not part of the public interface, but are supported for use by
       subclasses.  Put another way, given an unknown object that "isa"
       Rose::DB::Object::Metadata::ForeignKey, there should be no expectation that the following
       methods exist.  But subclasses, which know the exact class from which they inherit, are
       free to use these methods in order to implement the public API described above.

       method_maker_arguments TYPE
           Returns a hash (in list context) or reference to a hash (in scalar context) of
           name/value arguments that will be passed to the method_maker_class when making the
           foreign key method type TYPE.

       method_maker_class TYPE [, CLASS]
           If CLASS is passed, the name of the Rose::Object::MakeMethods-derived class used to
           create the object method of type TYPE is set to CLASS.

           Returns the name of the Rose::Object::MakeMethods-derived class used to create the
           object method of type TYPE.

       method_maker_type TYPE [, NAME]
           If NAME is passed, the name of the method maker method type for the foreign key method
           type TYPE is set to NAME.

           Returns the method maker method type for the foreign key method type TYPE.

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

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.