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 related tables.  See the Rose::DB::Object::Metadata
       documentation for more information.

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

       "get"
           A method that returns one or more objects from the related table.

       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 relationship 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::Relationship 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::Relationship-derived object:

       •   The relationship method type (e.g., "get")

       •   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'")

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

       There is no default method map for the Rose::DB::Object::Metadata::Relationship base
       class, but here is the method map from Rose::DB::Object::Metadata::Relationship::OneToOne
       as an example:

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

       "get"
           Rose::DB::Object::MakeMethods::Generic, object_by_key, ...

       Each item in the map is a relationship method type.  For each relationship 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 relationship method types are routinely omitted
       from the method map for the sake of brevity.  If there are no "interesting" method maker
       arguments, then "..." may appear by itself, as shown above.

       The purpose of documenting the method map is to answer the question, "What kind of
       method(s) will be created by this relationship 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.

       To this end, each Rose::DB::Object::Metadata::Relationship-derived class in the
       Rose::DB::Object module distribution will list its method map in its documentation.  This
       is a concise way to document the behavior that is specific to each relationship class,
       while omitting the common functionality (which is documented here, in the relationship
       base class).

       Remember, the existence and behavior of the method map is really implementation detail.  A
       relationship object is free to implement the public method-making interface however it
       wants, without regard to any conceptual or actual method map.  It must then, of course,
       document what kinds of methods it makes for each of its method types, but it does not have
       to use a method map to do so.

CLASS METHODS

       default_auto_method_types [TYPES]
           Get or set the default list of 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 is empty.

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

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

       auto_method_types [TYPES]
           Get or set the list of relationship method types that are automatically created when
           make_methods is called without an explicit list of relationship 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 relationship method type TYPE.  Subclasses must override
           this method.  The default implementation causes a fatal error if called.

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

       is_singular
           Returns true of the relationship may refer to more than one related object, false
           otherwise.  For example, this method returns true for "is_singular" in
           Rose::DB::Object::Metadata::Relationship::OneToMany objects, but false for
           "is_singular" in Rose::DB::Object::Metadata::Relationship::ManyToOne objects.

           Relationship subclasses must override this method and return an appropriate value.

       make_methods PARAMS
           Create object method used to manipulate objects in related tables.  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 relationship method types to be created.  If omitted,
               it defaults to the list of relationship 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, as usual.  Otherwise, the specified
           method name will be used.

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

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

       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.  Subclasses must override this
           method.  The default implementation causes a fatal error if called.

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::Relationship, 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
           relationship 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 relationship
           method type TYPE is set to NAME.

           Returns the method maker method type for the relationship 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.

perl v5.20.2                                2015-03-Rose::DB::Object::Metadata::Relationship(3pm)