1Rose::DB::Object::MetadUastear::CRoenltartiibountRseohdsiepP:(e:3rD)lB:D:oOcbujmeecntt:a:tMieotnadata::Relationship(3)
2
3
4

NAME

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

SYNOPSIS

10         package MyRelationshipType;
11
12         use Rose::DB::Object::Metadata::Relationship;
13         our @ISA = qw(Rose::DB::Object::Metadata::Relationship);
14         ...
15

DESCRIPTION

17       This is the base class for objects that store and manipulate database
18       table relationship metadata.  Relationship metadata objects are
19       responsible for creating object methods that fetch and/or manipulate
20       objects from related tables.  See the Rose::DB::Object::Metadata
21       documentation for more information.
22
23   MAKING METHODS
24       A Rose::DB::Object::Metadata::Relationship-derived object is
25       responsible for creating object methods that manipulate objects in
26       related tables.  Each relationship object can make zero or more methods
27       for each available relationship method type.  A relationship method
28       type describes the purpose of a method.  The default list of
29       relationship method types contains only one type:
30
31       "get"
32           A method that returns one or more objects from the related table.
33
34       Methods are created by calling make_methods.  A list of method types
35       can be passed to the call to make_methods.  If absent, the list of
36       method types is determined by the auto_method_types method.  A list of
37       all possible method types is available through the
38       available_method_types method.
39
40       These methods make up the "public" interface to relationship method
41       creation.  There are, however, several "protected" methods which are
42       used internally to implement the methods described above.  (The word
43       "protected" is used here in a vaguely C++ sense, meaning "accessible to
44       subclasses, but not to the public.")  Subclasses will probably find it
45       easier to override and/or call these protected methods in order to
46       influence the behavior of the "public" method maker methods.
47
48       A Rose::DB::Object::Metadata::Relationship object delegates method
49       creation to a  Rose::Object::MakeMethods-derived class.  Each
50       Rose::Object::MakeMethods-derived class has its own set of method
51       types, each of which takes it own set of arguments.
52
53       Using this system, four pieces of information are needed to create a
54       method on behalf of a Rose::DB::Object::Metadata::Relationship-derived
55       object:
56
57       •   The relationship method type (e.g., "get")
58
59       •   The method maker class (e.g.,
60           Rose::DB::Object::MakeMethods::Generic)
61
62       •   The method maker method type (e.g., object_by_key)
63
64       •   The method maker arguments (e.g., "interface => 'get'")
65
66       This information can be organized conceptually into a "method map" that
67       connects a relationship method type to a method maker class and,
68       finally, to one particular method type within that class, and its
69       arguments.
70
71       There is no default method map for the
72       Rose::DB::Object::Metadata::Relationship base class, but here is the
73       method map from Rose::DB::Object::Metadata::Relationship::OneToOne as
74       an example:
75
76       "get_set"
77           Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
78           'get_set', ..."
79
80       "get"
81           Rose::DB::Object::MakeMethods::Generic, object_by_key, ...
82
83       Each item in the map is a relationship method type.  For each
84       relationship method type, the method maker class, the method maker
85       method type, and the "interesting" method maker arguments are listed,
86       in that order.
87
88       The "..." in the method maker arguments is meant to indicate that
89       arguments have been omitted.  Arguments that are common to all
90       relationship method types are routinely omitted from the method map for
91       the sake of brevity.  If there are no "interesting" method maker
92       arguments, then "..." may appear by itself, as shown above.
93
94       The purpose of documenting the method map is to answer the question,
95       "What kind of method(s) will be created by this relationship object for
96       a given method type?"  Given the method map, it's possible to read the
97       documentation for each method maker class to determine how methods of
98       the specified type behave when passed the listed arguments.
99
100       To this end, each Rose::DB::Object::Metadata::Relationship-derived
101       class in the Rose::DB::Object module distribution will list its method
102       map in its documentation.  This is a concise way to document the
103       behavior that is specific to each relationship class, while omitting
104       the common functionality (which is documented here, in the relationship
105       base class).
106
107       Remember, the existence and behavior of the method map is really
108       implementation detail.  A relationship object is free to implement the
109       public method-making interface however it wants, without regard to any
110       conceptual or actual method map.  It must then, of course, document
111       what kinds of methods it makes for each of its method types, but it
112       does not have to use a method map to do so.
113

CLASS METHODS

115       default_auto_method_types [TYPES]
116           Get or set the default list of auto_method_types.  TYPES should be
117           a list of relationship method types.  Returns the list of default
118           relationship method types (in list context) or a reference to an
119           array of the default relationship method types (in scalar context).
120           The default list is empty.
121

CONSTRUCTOR

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

OBJECT METHODS

128       available_method_types
129           Returns the full list of relationship method types supported by
130           this class.
131
132       auto_method_types [TYPES]
133           Get or set the list of relationship method types that are
134           automatically created when make_methods is called without an
135           explicit list of relationship method types.  The default list is
136           determined by the default_auto_method_types class method.
137
138       build_method_name_for_type TYPE
139           Return a method name for the relationship method type TYPE.
140           Subclasses must override this method.  The default implementation
141           causes a fatal error if called.
142
143       class [CLASS]
144           Get or set the name of the Rose::DB::Object-derived class that
145           fronts the foreign table referenced by this relationship.
146
147       is_singular
148           Returns true of the relationship may refer to more than one related
149           object, false otherwise.  For example, this method returns true for
150           "is_singular" in
151           Rose::DB::Object::Metadata::Relationship::OneToMany objects, but
152           false for "is_singular" in
153           Rose::DB::Object::Metadata::Relationship::ManyToOne objects.
154
155           Relationship subclasses must override this method and return an
156           appropriate value.
157
158       make_methods PARAMS
159           Create object method used to manipulate objects in related tables.
160           Any applicable column triggers are also added.  PARAMS are
161           name/value pairs.  Valid PARAMS are:
162
163           "preserve_existing BOOL"
164               Boolean flag that indicates whether or not to preserve existing
165               methods in the case of a name conflict.
166
167           "replace_existing BOOL"
168               Boolean flag that indicates whether or not to replace existing
169               methods in the case of a name conflict.
170
171           "target_class CLASS"
172               The class in which to make the method(s).  If omitted, it
173               defaults to the calling class.
174
175           "types ARRAYREF"
176               A reference to an array of relationship method types to be
177               created.  If omitted, it defaults to the list of relationship
178               method types returned by auto_method_types.
179
180           If any of the methods could not be created for any reason, a fatal
181           error will occur.
182
183       methods MAP
184           Set the list of auto_method_types and method names all at once.
185           MAP should be a reference to a hash whose keys are method types and
186           whose values are either undef or method names.  If a value is
187           undef, then the method name for that method type will be generated
188           by calling build_method_name_for_type, as usual.  Otherwise, the
189           specified method name will be used.
190
191       method_types [TYPES]
192           This method is an alias for the auto_method_types method.
193
194       method_name TYPE [, NAME]
195           Get or set the name of the relationship method of type TYPE.
196
197       name [NAME]
198           Get or set the name of the relationship.  This name must be unique
199           among all other relationships for a given Rose::DB::Object-derived
200           class.
201
202       type
203           Returns a string describing the type of relationship.  Subclasses
204           must override this method.  The default implementation causes a
205           fatal error if called.
206

PROTECTED API

208       These methods are not part of the public interface, but are supported
209       for use by subclasses.  Put another way, given an unknown object that
210       "isa" Rose::DB::Object::Metadata::Relationship, there should be no
211       expectation that the following methods exist.  But subclasses, which
212       know the exact class from which they inherit, are free to use these
213       methods in order to implement the public API described above.
214
215       method_maker_arguments TYPE
216           Returns a hash (in list context) or reference to a hash (in scalar
217           context) of name/value arguments that will be passed to the
218           method_maker_class when making the relationship method type TYPE.
219
220       method_maker_class TYPE [, CLASS]
221           If CLASS is passed, the name of the
222           Rose::Object::MakeMethods-derived class used to create the object
223           method of type TYPE is set to CLASS.
224
225           Returns the name of the Rose::Object::MakeMethods-derived class
226           used to create the object method of type TYPE.
227
228       method_maker_type TYPE [, NAME]
229           If NAME is passed, the name of the method maker method type for the
230           relationship method type TYPE is set to NAME.
231
232           Returns the method maker method type for the relationship method
233           type TYPE.
234

AUTHOR

236       John C. Siracusa (siracusa@gmail.com)
237

LICENSE

239       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
240       program is free software; you can redistribute it and/or modify it
241       under the same terms as Perl itself.
242
243
244
245perl v5.34.0                      20R2o1s-e0:7:-D2B2::Object::Metadata::Relationship(3)
Impressum