1Rose::DB::Object::MetadUastear::CFoonrteriigbnuKteeydR(o3Ps)eer:l:DDBo:c:uOmbejnetcatt:i:oMnetadata::ForeignKey(3)
2
3
4

NAME

6       Rose::DB::Object::Metadata::ForeignKey - Foreign key metadata.
7

SYNOPSIS

9         use Rose::DB::Object::Metadata::ForeignKey;
10
11         $fk = Rose::DB::Object::Metadata::ForeignKey->new(...);
12         $fk->make_methods(...);
13         ...
14

DESCRIPTION

16       Objects of this class store and manipulate metadata for foreign keys in
17       a database table.  It stores information about which columns in the
18       local table map to which columns in the foreign table.
19
20       This class will create methods for "the thing referenced by" the
21       foreign key column(s).  You'll still need accessor method(s) for the
22       foreign key column(s) themselves.
23
24       Both the local table and the foreign table must have
25       Rose::DB::Object-derived classes fronting them.
26
27       Foreign keys can represent both "one to one" and "many to one"
28       relationships.  To choose, set the relationship_type attribute to
29       either "one to one" or "many to one".  The default is "many to one".
30
31   MAKING METHODS
32       A Rose::DB::Object::Metadata::ForeignKey-derived object is responsible
33       for creating object methods that manipulate objects referenced by a
34       foreign key.  Each foreign key object can make zero or more methods for
35       each available foreign key method type.  A foreign key method type
36       describes the purpose of a method.  The default list of foreign key
37       method types contains only one type:
38
39       "get_set"
40           A method that returns the object referenced by the foreign key.
41
42       Methods are created by calling make_methods.  A list of method types
43       can be passed to the call to make_methods.  If absent, the list of
44       method types is determined by the auto_method_types method.  A list of
45       all possible method types is available through the
46       available_method_types method.
47
48       These methods make up the "public" interface to foreign key method
49       creation.  There are, however, several "protected" methods which are
50       used internally to implement the methods described above.  (The word
51       "protected" is used here in a vaguely C++ sense, meaning "accessible to
52       subclasses, but not to the public.")  Subclasses will probably find it
53       easier to override and/or call these protected methods in order to
54       influence the behavior of the "public" method maker methods.
55
56       A Rose::DB::Object::Metadata::ForeignKey object delegates method
57       creation to a  Rose::Object::MakeMethods-derived class.  Each
58       Rose::Object::MakeMethods-derived class has its own set of method
59       types, each of which takes it own set of arguments.
60
61       Using this system, four pieces of information are needed to create a
62       method on behalf of a Rose::DB::Object::Metadata::ForeignKey-derived
63       object:
64
65       •   The foreign key method type (e.g., "get_set")
66
67       •   The method maker class (e.g.,
68           Rose::DB::Object::MakeMethods::Generic)
69
70       •   The method maker method type (e.g., object_by_key)
71
72       •   The method maker arguments (e.g., "interface => 'get_set'")
73
74       This information can be organized conceptually into a "method map" that
75       connects a foreign key method type to a method maker class and,
76       finally, to one particular method type within that class, and its
77       arguments.
78
79       The default method map for Rose::DB::Object::Metadata::ForeignKey is:
80
81       "get_set"
82           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface
83           => 'get_set'" ...
84
85       "get_set_now"
86           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface
87           => 'get_set_now'" ...
88
89       "get_set_on_save"
90           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface
91           => 'get_set_on_save'" ...
92
93       "delete_now"
94           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface
95           => 'delete_now'" ...
96
97       "delete_on_save"
98           Rose::DB::Object::MakeMethods::Generic, object_by_key, "interface
99           => 'delete_on_save'" ...
100
101       Each item in the map is a foreign key method type.  For each foreign
102       key method type, the method maker class, the method maker method type,
103       and the "interesting" method maker arguments are listed, in that order.
104
105       The "..." in the method maker arguments is meant to indicate that
106       arguments have been omitted.  Arguments that are common to all foreign
107       key method types are routinely omitted from the method map for the sake
108       of brevity.
109
110       The purpose of documenting the method map is to answer the question,
111       "What kind of method(s) will be created by this foreign key object for
112       a given method type?"  Given the method map, it's possible to read the
113       documentation for each method maker class to determine how methods of
114       the specified type behave when passed the listed arguments.
115
116       Remember, the existence and behavior of the method map is really
117       implementation detail.  A foreign key object is free to implement the
118       public method-making interface however it wants, without regard to any
119       conceptual or actual method map.
120

CLASS METHODS

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

OBJECT METHODS

131       available_method_types
132           Returns the full list of foreign key method types supported by this
133           class.
134
135       auto_method_types [TYPES]
136           Get or set the list of foreign key method types that are
137           automatically created when make_methods is called without an
138           explicit list of foreign key method types.  The default list is
139           determined by the default_auto_method_types class method.
140
141       build_method_name_for_type TYPE
142           Return a method name for the foreign key method type TYPE.  The
143           default implementation returns the following.
144
145           For the method types "get_set", "get_set_now", and
146           "get_set_on_save", the foreign key's name is returned.
147
148           For the method types "delete_now" and "delete_on_save", the foreign
149           key's name prefixed with "delete_" is returned.
150
151           Otherwise, undef is returned.
152
153       class [CLASS]
154           Get or set the class name of the Rose::DB::Object-derived object
155           that encapsulates rows from the table referenced by the foreign key
156           column(s).
157
158       column_map [HASH | HASHREF]
159           This is an alias for the key_columns method.
160
161       key_column LOCAL [, FOREIGN]
162           If passed a local column name LOCAL, return the corresponding
163           column name in the foreign table.  If passed both a local column
164           name LOCAL and a foreign column name FOREIGN, set the local/foreign
165           mapping and return the foreign column name.
166
167       key_columns [ HASH | HASHREF ]
168           Get or set a hash that maps local column names to foreign column
169           names in the table referenced by the foreign key.  Returns a
170           reference to a hash in scalar context, or a list of key/value pairs
171           in list context.
172
173       make_methods PARAMS
174           Create object method used to manipulate object referenced by the
175           foreign key.  Any applicable column triggers are also added.
176           PARAMS are name/value pairs.  Valid PARAMS are:
177
178           "preserve_existing BOOL"
179               Boolean flag that indicates whether or not to preserve existing
180               methods in the case of a name conflict.
181
182           "replace_existing BOOL"
183               Boolean flag that indicates whether or not to replace existing
184               methods in the case of a name conflict.
185
186           "target_class CLASS"
187               The class in which to make the method(s).  If omitted, it
188               defaults to the calling class.
189
190           "types ARRAYREF"
191               A reference to an array of foreign key method types to be
192               created.  If omitted, it defaults to the list of foreign key
193               method types returned by auto_method_types.
194
195           If any of the methods could not be created for any reason, a fatal
196           error will occur.
197
198       methods MAP
199           Set the list of auto_method_types and method names all at once.
200           MAP should be a reference to a hash whose keys are method types and
201           whose values are either undef or method names.  If a value is
202           undef, then the method name for that method type will be generated
203           by calling build_method_name_for_type|/build_method_name_for_type,
204           as usual.  Otherwise, the specified method name will be used.
205
206       method_name TYPE [, NAME]
207           Get or set the name of the relationship method of type TYPE.
208
209       method_types [TYPES]
210           This method is an alias for the auto_method_types method.
211
212       name [NAME]
213           Get or set the name of the foreign key.  This name must be unique
214           among all other foreign keys for a given Rose::DB::Object-derived
215           class.
216
217       referential_integrity [BOOL]
218           Get or set the boolean value that determines what happens when the
219           local key columns have defined values, but the object they point to
220           is not found.  If true, a fatal error will occur when the methods
221           that fetch objects through this foreign key are called.  If false,
222           then the methods will simply return undef.  The default is true.
223
224       rel_type [TYPE]
225           This method is an alias for the relationship_type method described
226           below.
227
228       relationship_type [TYPE]
229           Get or set the relationship type represented by this foreign key.
230           Valid values for TYPE are "one to one" and "many to one".
231
232       share_db [BOOL]
233           Get or set the boolean flag that determines whether the db
234           attribute of the current object is shared with the foreign object
235           to be fetched.  The default value is true.
236
237       soft [BOOL]
238           This method is the mirror image of the referential_integrity
239           method.   Passing a true is the same thing as setting
240           referential_integrity to false, and vice versa.  Similarly, the
241           return value is the logical negation of referential_integrity.
242
243       type
244           Returns "foreign key".
245
246       with_column_triggers [BOOL]
247           Get or set a boolean value that indicates whether or not triggers
248           should be added to the key columns in an attempt to keep foreign
249           objects and foreign key columns in sync.  Defaults to false.
250

PROTECTED API

252       These methods are not part of the public interface, but are supported
253       for use by subclasses.  Put another way, given an unknown object that
254       "isa" Rose::DB::Object::Metadata::ForeignKey, there should be no
255       expectation that the following methods exist.  But subclasses, which
256       know the exact class from which they inherit, are free to use these
257       methods in order to implement the public API described above.
258
259       method_maker_arguments TYPE
260           Returns a hash (in list context) or reference to a hash (in scalar
261           context) of name/value arguments that will be passed to the
262           method_maker_class when making the foreign key method type TYPE.
263
264       method_maker_class TYPE [, CLASS]
265           If CLASS is passed, the name of the
266           Rose::Object::MakeMethods-derived class used to create the object
267           method of type TYPE is set to CLASS.
268
269           Returns the name of the Rose::Object::MakeMethods-derived class
270           used to create the object method of type TYPE.
271
272       method_maker_type TYPE [, NAME]
273           If NAME is passed, the name of the method maker method type for the
274           foreign key method type TYPE is set to NAME.
275
276           Returns the method maker method type for the foreign key method
277           type TYPE.
278

AUTHOR

280       John C. Siracusa (siracusa@gmail.com)
281

LICENSE

283       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
284       program is free software; you can redistribute it and/or modify it
285       under the same terms as Perl itself.
286
287
288
289perl v5.34.0                      2021R-o0s7e-:2:2DB::Object::Metadata::ForeignKey(3)
Impressum