File Coverage

blib/lib/Rose/DB/Object/Metadata/Relationship.pm
Criterion Covered Total %
statement 27 97 27.8
branch 5 58 8.6
condition 2 13 15.3
subroutine 10 19 52.6
pod 3 15 20.0
total 47 202 23.2


line stmt bran cond sub pod time code
1             package Rose::DB::Object::Metadata::Relationship;
2              
3 61     61   486 use strict;
  61         170  
  61         1847  
4              
5 61     61   378 use Carp();
  61         183  
  61         1279  
6              
7 61     61   346 use Rose::DB::Object::Metadata::Util qw(:all);
  61         170  
  61         10664  
8              
9 61     61   546 use Rose::DB::Object::Metadata::MethodMaker;
  61         186  
  61         92086  
10             our @ISA = qw(Rose::DB::Object::Metadata::MethodMaker);
11              
12             our $VERSION = '0.780';
13              
14             __PACKAGE__->add_common_method_maker_argument_names
15             (
16             qw(relationship hash_key)
17             );
18              
19             Rose::Object::MakeMethods::Generic->make_methods
20             (
21             { preserve_existing => 1 },
22             scalar =>
23             [
24             'foreign_key',
25             'deferred_make_method_args',
26             id => { interface => 'get_set_init' },
27             __PACKAGE__->common_method_maker_argument_names,
28             ],
29             );
30              
31 0     0 1 0 sub type { Carp::confess "Override in subclass" }
32              
33 0     0 1 0 sub is_singular { Carp::confess "Override in subclass" }
34              
35 148     148 1 331 sub relationship { $_[0] }
36              
37 8     8 0 25 sub is_ready_to_make_methods { 1 }
38 0     0 0 0 sub sanity_check { 1 }
39              
40             my $Id_Counter = 0;
41              
42 14     14 0 162 sub init_id { ++$Id_Counter }
43              
44             # Some object keys have different names when they appear
45             # in hashref-style relationship specs. This hash maps
46             # between the two in the case where they differ.
47             sub spec_hash_key_map
48             {
49             {
50             # object key spec key
51 7     7 0 29 method_name => 'methods',
52             }
53             }
54              
55             sub spec_hash_method_map
56             {
57             {
58             # object key object method
59 7     7 0 29 _share_db => 'share_db',
60             _key_columns => 'key_columns',
61             }
62             }
63              
64             # Return a hashref-style relationship spec
65             sub spec_hash
66             {
67 7     7 0 23 my($self) = shift;
68              
69 7   50     19 my $key_map = $self->spec_hash_key_map || {};
70 7   50     28 my $method_map = $self->spec_hash_method_map || {};
71              
72 7         24 my %spec = (type => $self->type);
73              
74 7         43 foreach my $key (keys(%$self))
75             {
76 63 100       142 if(exists $key_map->{$key})
    50          
77             {
78 7 50       23 my $spec_key = $key_map->{$key} or next;
79 7         21 $spec{$spec_key} = $self->{$key};
80             }
81             elsif(exists $method_map->{$key})
82             {
83 0 0       0 my $method = $method_map->{$key} or next;
84 0         0 $spec{$method} = $self->$method();
85             }
86             else
87             {
88 56         175 $spec{$key} = $self->{$key};
89             }
90             }
91              
92 7 50       67 return wantarray ? %spec : \%spec;
93             }
94              
95             our $DEFAULT_INLINE_LIMIT = 80;
96              
97             sub perl_hash_definition
98             {
99 0     0 0   my($self, %args) = @_;
100              
101 0           my $meta = $self->parent;
102              
103 0           my $name_padding = $args{'name_padding'};
104              
105 0           my $braces = $args{'braces'};
106 0 0         my $indent = defined $args{'indent'} ? $args{'indent'} :
    0          
107             ($meta ? $meta->default_perl_indent : undef);
108              
109 0 0         my $inline = defined $args{'inline'} ? $args{'inline'} : 0;
110 0 0         my $inline_limit = defined $args{'inline'} ? $args{'inline_limit'} : $DEFAULT_INLINE_LIMIT;
111              
112 0           my %attrs = map { $_ => 1 } $self->perl_relationship_definition_attributes;
  0            
113 0           my %hash = $self->spec_hash;
114              
115 0           my @delete_keys = grep { !$attrs{$_} } keys %hash;
  0            
116 0           delete @hash{@delete_keys};
117              
118 0 0         $hash{'column_map'} = delete $hash{'key_columns'} if(exists $hash{'key_columns'});
119              
120 0           my $max_len = 0;
121 0           my $min_len = -1;
122              
123 0           foreach my $name (keys %hash)
124             {
125 0 0         $max_len = length($name) if(length $name > $max_len);
126 0 0 0       $min_len = length($name) if(length $name < $min_len || $min_len < 0);
127             }
128              
129 0 0 0       if(defined $name_padding && $name_padding > 0)
130             {
131 0           return sprintf('%-*s => ', $name_padding, perl_quote_key($self->name)) .
132             perl_hashref(hash => \%hash,
133             braces => $braces,
134             inline => $inline,
135             inline_limit => $inline_limit,
136             indent => $indent,
137             key_padding => hash_key_padding(\%hash));
138             }
139             else
140             {
141 0           return perl_quote_key($self->name) . ' => ' .
142             perl_hashref(hash => \%hash,
143             braces => $braces,
144             inline => $inline,
145             inline_limit => $inline_limit,
146             indent => $indent,
147             key_padding => hash_key_padding(\%hash));
148             }
149             }
150              
151             sub perl_relationship_definition_attributes
152             {
153 0     0 0   my($self) = shift;
154              
155 0           my @attrs;
156              
157 0           ATTR: foreach my $attr ('type', sort keys %$self)
158             {
159 0 0         if($attr =~ /^(?: id | name | method_name | method_code | auto_method_types |
160             deferred_make_method_args | parent )$/x)
161             {
162 0           next ATTR;
163             }
164              
165 0 0         my $val = $self->can($attr) ? $self->$attr() : next ATTR;
166              
167 0 0         if(!defined $val)
168             {
169 0           next ATTR;
170             }
171              
172 0 0 0       next ATTR if($attr =~ /^_?share_db$/ && $self->share_db);
173              
174 0 0         if($attr =~ /^_(share_db|key_columns)$/)
    0          
175             {
176 0           $attr = $1;
177             }
178             elsif($attr eq 'method_name')
179             {
180 0 0         my $names = $self->{$attr} or next ATTR;
181 0           my $custom = 0;
182              
183 0           while(my($type, $name) = each(%$names))
184             {
185 0 0         if($name ne $self->build_method_name_for_type($type))
186             {
187 0           $custom = 1;
188 0           last;
189             }
190             }
191              
192 0 0         unless($custom)
193             {
194 0           my $def_types = $self->init_auto_method_types;
195              
196 0           TYPE: foreach my $def_type (@$def_types)
197             {
198 0           my $found = 0;
199              
200 0           foreach my $type ($self->auto_method_types)
201             {
202 0 0         if($type eq $def_type)
203             {
204 0           $found++;
205 0           next TYPE;
206             }
207             }
208              
209 0 0         $custom = 1 if($found != @$def_types);
210             }
211             }
212              
213 0 0         next ATTR unless($custom);
214             }
215              
216 0           push(@attrs, $attr);
217             }
218              
219 0           return @attrs;
220             }
221              
222             sub object_has_related_objects
223             {
224 0     0 0   my($self, $object) = @_;
225              
226 0 0         unless($object->isa($self->parent->class))
227             {
228 0           my $class = $self->parent->class;
229 0           Carp::croak "Cannot check for items related through the ", $self->name,
230             " relationship. Object does not inherit from $class: $object";
231             }
232              
233 0           my $related_objects = $object->{$self->hash_key};
234 0           my $ref = ref $related_objects;
235              
236 0 0         if($ref eq 'ARRAY')
237             {
238 0 0         return @{$related_objects} ? $related_objects : 0;
  0            
239             }
240              
241 0 0         return $ref ? [ $related_objects ] : undef;
242             }
243              
244 0     0 0   sub hash_keys_used { shift->hash_key }
245              
246             sub forget_related_objects
247             {
248 0     0 0   my($self, $object) = @_;
249              
250 0           foreach my $key ($self->hash_keys_used)
251             {
252 0           $object->{$key} = undef;
253             }
254             }
255              
256       0 0   sub requires_preexisting_parent_object { } # override in subclass
257              
258             1;
259              
260             __END__
261              
262             =head1 NAME
263              
264             Rose::DB::Object::Metadata::Relationship - Base class for table relationship metadata objects.
265              
266             =head1 SYNOPSIS
267              
268             package MyRelationshipType;
269              
270             use Rose::DB::Object::Metadata::Relationship;
271             our @ISA = qw(Rose::DB::Object::Metadata::Relationship);
272             ...
273              
274             =head1 DESCRIPTION
275              
276             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 L<Rose::DB::Object::Metadata> documentation for more information.
277              
278             =head2 MAKING METHODS
279              
280             A L<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:
281              
282             =over 4
283              
284             =item C<get>
285              
286             A method that returns one or more objects from the related table.
287              
288             =back
289              
290             Methods are created by calling L<make_methods|/make_methods>. A list of method types can be passed to the call to L<make_methods|/make_methods>. If absent, the list of method types is determined by the L<auto_method_types|/auto_method_types> method. A list of all possible method types is available through the L<available_method_types|/available_method_types> method.
291              
292             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.
293              
294             A L<Rose::DB::Object::Metadata::Relationship> object delegates method creation to a L<Rose::Object::MakeMethods>-derived class. Each L<Rose::Object::MakeMethods>-derived class has its own set of method types, each of which takes it own set of arguments.
295              
296             Using this system, four pieces of information are needed to create a method on behalf of a L<Rose::DB::Object::Metadata::Relationship>-derived object:
297              
298             =over 4
299              
300             =item * The B<relationship method type> (e.g., C<get>)
301              
302             =item * The B<method maker class> (e.g., L<Rose::DB::Object::MakeMethods::Generic>)
303              
304             =item * The B<method maker method type> (e.g., L<object_by_key|Rose::DB::Object::MakeMethods::Generic/object_by_key>)
305              
306             =item * The B<method maker arguments> (e.g., C<interface =E<gt> 'get'>)
307              
308             =back
309              
310             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.
311              
312             There is no default method map for the L<Rose::DB::Object::Metadata::Relationship> base class, but here is the method map from L<Rose::DB::Object::Metadata::Relationship::OneToOne> as an example:
313              
314             =over 4
315              
316             =item C<get_set>
317              
318             L<Rose::DB::Object::MakeMethods::Generic>, L<scalar|Rose::DB::Object::MakeMethods::Generic/scalar>, C<interface =E<gt> 'get_set', ...>
319              
320             =item C<get>
321              
322             L<Rose::DB::Object::MakeMethods::Generic>, L<object_by_key|Rose::DB::Object::MakeMethods::Generic/object_by_key>, ...
323              
324             =back
325              
326             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.
327              
328             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.
329              
330             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.
331              
332             To this end, each L<Rose::DB::Object::Metadata::Relationship>-derived class in the L<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).
333              
334             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.
335              
336             =head1 CLASS METHODS
337              
338             =over 4
339              
340             =item B<default_auto_method_types [TYPES]>
341              
342             Get or set the default list of L<auto_method_types|/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.
343              
344             =back
345              
346             =head1 CONSTRUCTOR
347              
348             =over 4
349              
350             =item B<new PARAMS>
351              
352             Constructs a new object based on PARAMS, where PARAMS are
353             name/value pairs. Any object method is a valid parameter name.
354              
355             =back
356              
357             =head1 OBJECT METHODS
358              
359             =over 4
360              
361             =item B<available_method_types>
362              
363             Returns the full list of relationship method types supported by this class.
364              
365             =item B<auto_method_types [TYPES]>
366              
367             Get or set the list of relationship method types that are automatically created when L<make_methods|/make_methods> is called without an explicit list of relationship method types. The default list is determined by the L<default_auto_method_types|/default_auto_method_types> class method.
368              
369             =item B<build_method_name_for_type TYPE>
370              
371             Return a method name for the relationship method type TYPE. Subclasses must override this method. The default implementation causes a fatal error if called.
372              
373             =item B<class [CLASS]>
374              
375             Get or set the name of the L<Rose::DB::Object>-derived class that fronts the foreign table referenced by this relationship.
376              
377             =item B<is_singular>
378              
379             Returns true of the relationship may refer to more than one related object, false otherwise. For example, this method returns true for L<Rose::DB::Object::Metadata::Relationship::OneToMany/is_singular> objects, but false for L<Rose::DB::Object::Metadata::Relationship::ManyToOne/is_singular> objects.
380              
381             Relationship subclasses must override this method and return an appropriate value.
382              
383             =item B<make_methods PARAMS>
384              
385             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:
386              
387             =over 4
388              
389             =item C<preserve_existing BOOL>
390              
391             Boolean flag that indicates whether or not to preserve existing methods in the case of a name conflict.
392              
393             =item C<replace_existing BOOL>
394              
395             Boolean flag that indicates whether or not to replace existing methods in the case of a name conflict.
396              
397             =item C<target_class CLASS>
398              
399             The class in which to make the method(s). If omitted, it defaults to the calling class.
400              
401             =item C<types ARRAYREF>
402              
403             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 L<auto_method_types|/auto_method_types>.
404              
405             =back
406              
407             If any of the methods could not be created for any reason, a fatal error will occur.
408              
409             =item B<methods MAP>
410              
411             Set the list of L<auto_method_types|/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 L<build_method_name_for_type|/build_method_name_for_type>, as usual. Otherwise, the specified method name will be used.
412              
413             =item B<method_types [TYPES]>
414              
415             This method is an alias for the L<auto_method_types|/auto_method_types> method.
416              
417             =item B<method_name TYPE [, NAME]>
418              
419             Get or set the name of the relationship method of type TYPE.
420              
421             =item B<name [NAME]>
422              
423             Get or set the name of the relationship. This name must be unique among all other relationships for a given L<Rose::DB::Object>-derived class.
424              
425             =item B<type>
426              
427             Returns a string describing the type of relationship. Subclasses must override this method. The default implementation causes a fatal error if called.
428              
429             =back
430              
431             =head1 PROTECTED API
432              
433             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" L<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.
434              
435             =over 4
436              
437             =item B<method_maker_arguments TYPE>
438              
439             Returns a hash (in list context) or reference to a hash (in scalar context) of name/value arguments that will be passed to the L<method_maker_class|/method_maker_class> when making the relationship method type TYPE.
440              
441             =item B<method_maker_class TYPE [, CLASS]>
442              
443             If CLASS is passed, the name of the L<Rose::Object::MakeMethods>-derived class used to create the object method of type TYPE is set to CLASS.
444              
445             Returns the name of the L<Rose::Object::MakeMethods>-derived class used to create the object method of type TYPE.
446              
447             =item B<method_maker_type TYPE [, NAME]>
448              
449             If NAME is passed, the name of the method maker method type for the relationship method type TYPE is set to NAME.
450              
451             Returns the method maker method type for the relationship method type TYPE.
452              
453             =back
454              
455             =head1 AUTHOR
456              
457             John C. Siracusa (siracusa@gmail.com)
458              
459             =head1 LICENSE
460              
461             Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is
462             free software; you can redistribute it and/or modify it under the same terms
463             as Perl itself.