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.

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:

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.

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.

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.

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.

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.

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.

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.