1Rose::DB::Object::MetadUastear::CRoenltartiibountRseohdsiepP:(e:3rD)lB:D:oOcbujmeecntt:a:tMieotnadata::Relationship(3)
2
6 Rose::DB::Object::Metadata::Relationship - Base class for table
7 relationship metadata objects.
8
10 package MyRelationshipType;
11 use Rose::DB::Object::Metadata::Relationship;
13 our @ISA = qw(Rose::DB::Object::Metadata::Relationship);
14 ...
15
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 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 "get"
32 A method that returns one or more objects from the related table.
33 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 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 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 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 • The relationship method type (e.g., "get")
58 • The method maker class (e.g.,
60 Rose::DB::Object::MakeMethods::Generic)
61 • The method maker method type (e.g., object_by_key)
63 • The method maker arguments (e.g., "interface => 'get'")
65 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 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 "get_set"
77 Rose::DB::Object::MakeMethods::Generic, scalar, "interface =>
78 'get_set', ..."
79 "get"
81 Rose::DB::Object::MakeMethods::Generic, object_by_key, ...
82 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 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 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 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 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
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
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
128 available_method_types
129 Returns the full list of relationship method types supported by
130 this class.
131 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 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 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 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 Relationship subclasses must override this method and return an
156 appropriate value.
157 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 "preserve_existing BOOL"
164 Boolean flag that indicates whether or not to preserve existing
165 methods in the case of a name conflict.
166 "replace_existing BOOL"
168 Boolean flag that indicates whether or not to replace existing
169 methods in the case of a name conflict.
170 "target_class CLASS"
172 The class in which to make the method(s). If omitted, it
173 defaults to the calling class.
174 "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 If any of the methods could not be created for any reason, a fatal
181 error will occur.
182 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 method_types [TYPES]
192 This method is an alias for the auto_method_types method.
193 method_name TYPE [, NAME]
195 Get or set the name of the relationship method of type TYPE.
196 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 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
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 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 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 Returns the name of the Rose::Object::MakeMethods-derived class
226 used to create the object method of type TYPE.
227 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 Returns the method maker method type for the relationship method
233 type TYPE.
234
236 John C. Siracusa (siracusa@gmail.com)
237
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.
242perl v5.38.0 20R2o3s-e0:7:-D2B1::Object::Metadata::Relationship(3)