X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FDBIx%2FClass%2FRow.pm;h=6ee598b992cd5fdffe1ead6d1fac7d2b96265383;hb=a34c76c2391de12c939f22e4dba875374aea1f66;hp=5b350bdc09855a77d3430614deb7f46a4d5f0abb;hpb=50261284a5486d1974adb202eb84e5ed782d3665;p=dbsrgits%2FDBIx-Class.git diff --git a/lib/DBIx/Class/Row.pm b/lib/DBIx/Class/Row.pm index 5b350bd..6ee598b 100644 --- a/lib/DBIx/Class/Row.pm +++ b/lib/DBIx/Class/Row.pm @@ -5,10 +5,9 @@ use warnings; use base qw/DBIx::Class/; -use DBIx::Class::Exception; use Scalar::Util 'blessed'; +use List::Util 'first'; use Try::Tiny; -use namespace::clean; ### ### Internal method @@ -21,7 +20,7 @@ BEGIN { : sub () { 0 }; } -__PACKAGE__->mk_group_accessors('simple' => [result_source => '_result_source']); +use namespace::clean; =head1 NAME @@ -34,14 +33,31 @@ DBIx::Class::Row - Basic row methods This class is responsible for defining and doing basic operations on rows derived from L objects. -Row objects are returned from Ls using the +Result objects are returned from Ls using the L, L, L and L methods, as well as invocations of 'single' ( L, L or L) -relationship accessors of L objects. +relationship accessors of L objects. + +=head1 NOTE + +All "Row objects" derived from a Schema-attached L +object (such as a typical C<< L->L >> call) are actually Result +instances, based on your application's +L. + +L implements most of the row-based communication with the +underlying storage, but a Result class B. +Usually, Result classes inherit from L, which in turn +combines the methods from several classes, one of them being +L. Therefore, while many of the methods available to a +L-derived Result class are described in the following +documentation, it does not detail all of the methods available to Result +objects. Refer to L for more info. =head1 METHODS @@ -55,11 +71,11 @@ relationship accessors of L objects. =item Arguments: \%attrs or \%colsandvalues -=item Returns: A Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back -While you can create a new row object by calling C directly on +While you can create a new result object by calling C directly on this class, you are better off calling it on a L object. @@ -162,21 +178,21 @@ sub new { my $new = bless { _column_data => {} }, $class; - my $source = - delete $attrs->{-result_source} - or - ( $attrs->{-source_handle} and (delete $attrs->{-source_handle})->resolve ) - ; - $new->result_source($source) if $source; - - if (my $related = delete $attrs->{-cols_from_relations}) { - @{$new->{_ignore_at_insert}={}}{@$related} = (); - } - if ($attrs) { $new->throw_exception("attrs must be a hashref") unless ref($attrs) eq 'HASH'; + my $source = delete $attrs->{-result_source}; + if ( my $h = delete $attrs->{-source_handle} ) { + $source ||= $h->resolve; + } + + $new->result_source($source) if $source; + + if (my $col_from_rel = delete $attrs->{-cols_from_relations}) { + @{$new->{_ignore_at_insert}={}}{@$col_from_rel} = (); + } + my ($related,$inflated); foreach my $key (keys %$attrs) { @@ -243,7 +259,7 @@ sub new { next; } } - $new->throw_exception("No such column $key on $class") + $new->throw_exception("No such column '$key' on $class") unless $class->has_column($key); $new->store_column($key => $attrs->{$key}); } @@ -255,6 +271,42 @@ sub new { return $new; } +=head2 $column_accessor + + # Each pair does the same thing + + # (un-inflated, regular column) + my $val = $row->get_column('first_name'); + my $val = $row->first_name; + + $row->set_column('first_name' => $val); + $row->first_name($val); + + # (inflated column via DBIx::Class::InflateColumn::DateTime) + my $val = $row->get_inflated_column('last_modified'); + my $val = $row->last_modified; + + $row->set_inflated_column('last_modified' => $val); + $row->last_modified($val); + +=over + +=item Arguments: $value? + +=item Return Value: $value + +=back + +A column accessor method is created for each column, which is used for +getting/setting the value for that column. + +The actual method name is based on the +L name given during the +L L. Like L, this +will not store the data in the database until L or L +is called on the row. + =head2 insert $row->insert; @@ -263,18 +315,16 @@ sub new { =item Arguments: none -=item Returns: The Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back Inserts an object previously created by L into the database if -it isn't already in there. Returns the object itself. Requires the -object's result source to be set, or the class to have a -result_source_instance method. To insert an entirely new row into -the database, use C (see L). +it isn't already in there. Returns the object itself. To insert an +entirely new row into the database, use L. -To fetch an uninserted row object, call -L on a resultset. +To fetch an uninserted result object, call +L on a resultset. This will also insert any uninserted, related objects held inside this one, see L for more details. @@ -285,8 +335,6 @@ sub insert { my ($self) = @_; return $self if $self->in_storage; my $source = $self->result_source; - $source ||= $self->result_source($self->result_source_instance) - if $self->can('result_source_instance'); $self->throw_exception("No result_source set on this object; can't insert") unless $source; @@ -348,41 +396,29 @@ sub insert { warn "MC $self inserting (".join(', ', $self->get_columns).")\n"; }; + # perform the insert - the storage will return everything it is asked to + # (autoinc primary columns and any retrieve_on_insert columns) my %current_rowdata = $self->get_columns; - - # perform the insert - the storage may return some stuff for us right there - # my $returned_cols = $storage->insert( $source, - \%current_rowdata, + { %current_rowdata }, # what to insert, copy because the storage *will* change it ); for (keys %$returned_cols) { - $self->store_column( - $_, - ( $current_rowdata{$_} = $returned_cols->{$_} ) - ); + $self->store_column($_, $returned_cols->{$_}) + # this ensures we fire store_column only once + # (some asshats like overriding it) + if ( + (!exists $current_rowdata{$_}) + or + (defined $current_rowdata{$_} xor defined $returned_cols->{$_}) + or + (defined $current_rowdata{$_} and $current_rowdata{$_} ne $returned_cols->{$_}) + ); } - # see if any of the pcols still need filling (or re-querying in case of scalarrefs) - my @missing_pri = grep - { ! defined $current_rowdata{$_} or ref $current_rowdata{$_} eq 'SCALAR' } - $self->primary_columns - ; - - if (@missing_pri) { - MULTICREATE_DEBUG and warn "MC $self fetching missing PKs ".join(', ', @missing_pri )."\n"; - - $self->throw_exception( "Missing primary key but Storage doesn't support last_insert_id" ) - unless $storage->can('last_insert_id'); - - my @pri_values = $storage->last_insert_id($self->result_source, @missing_pri); - - $self->throw_exception( "Can't get last insert id" ) - unless (@pri_values == @missing_pri); - - $self->store_column($missing_pri[$_] => $pri_values[$_]) for 0 .. $#missing_pri; - } + delete $self->{_column_data_in_storage}; + $self->in_storage(1); $self->{_dirty_columns} = {}; $self->{related_resultsets} = {}; @@ -416,10 +452,8 @@ sub insert { } } - $self->in_storage(1); - delete $self->{_orig_ident}; - delete $self->{_orig_ident_failreason}; delete $self->{_ignore_at_insert}; + $rollback_guard->commit if $rollback_guard; return $self; @@ -434,7 +468,7 @@ sub insert { =item Arguments: none or 1|0 -=item Returns: 1|0 +=item Return Value: 1|0 =back @@ -443,8 +477,8 @@ not. This is set to true when L, L or L are used. -Creating a row object using L, or calling -L on one, sets it to false. +Creating a result object using L, or +calling L on one, sets it to false. =cut @@ -462,11 +496,11 @@ sub in_storage { =item Arguments: none or a hashref -=item Returns: The Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back -Throws an exception if the row object is not yet in the database, +Throws an exception if the result object is not yet in the database, according to L. This method issues an SQL UPDATE query to commit any changes to the @@ -486,12 +520,12 @@ to C, e.g. ( { %{ $href } } ) If the values passed or any of the column values set on the object contain scalar references, e.g.: - $row->last_modified(\'NOW()'); + $row->last_modified(\'NOW()')->update(); # OR $row->update({ last_modified => \'NOW()' }); The update will pass the values verbatim into SQL. (See -L docs). The values in your Row object will NOT change +L docs). The values in your Result object will NOT change as a result of the update call, if you want the object to be updated with the actual values from the database, call L after the update. @@ -516,14 +550,10 @@ sub update { my %to_update = $self->get_dirty_columns or return $self; - my $ident_cond = $self->{_orig_ident} || $self->ident_condition; $self->throw_exception( "Not in database" ) unless $self->in_storage; - $self->throw_exception($self->{_orig_ident_failreason}) - if ! keys %$ident_cond; - my $rows = $self->result_source->storage->update( - $self->result_source, \%to_update, $ident_cond + $self->result_source, \%to_update, $self->_storage_ident_condition ); if ($rows == 0) { $self->throw_exception( "Can't update ${self}: row not found" ); @@ -532,7 +562,7 @@ sub update { } $self->{_dirty_columns} = {}; $self->{related_resultsets} = {}; - delete $self->{_orig_ident}; + delete $self->{_column_data_in_storage}; return $self; } @@ -544,7 +574,7 @@ sub update { =item Arguments: none -=item Returns: The Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back @@ -568,7 +598,7 @@ main row first> and only then attempts to delete any remaining related rows. If you delete an object within a txn_do() (see L) -and the transaction subsequently fails, the row object will remain marked as +and the transaction subsequently fails, the result object will remain marked as not being in storage. If you know for a fact that the object is still in storage (i.e. by inspecting the cause of the transaction's failure), you can use C<< $obj->in_storage(1) >> to restore consistency between the object and @@ -584,23 +614,20 @@ sub delete { if (ref $self) { $self->throw_exception( "Not in database" ) unless $self->in_storage; - my $ident_cond = $self->{_orig_ident} || $self->ident_condition; - $self->throw_exception($self->{_orig_ident_failreason}) - if ! keys %$ident_cond; - $self->result_source->storage->delete( - $self->result_source, $ident_cond + $self->result_source, $self->_storage_ident_condition ); - delete $self->{_orig_ident}; # no longer identifiable + delete $self->{_column_data_in_storage}; $self->in_storage(undef); } else { - $self->throw_exception("Can't do class delete without a ResultSource instance") - unless $self->can('result_source_instance'); + my $rsrc = try { $self->result_source_instance } + or $self->throw_exception("Can't do class delete without a ResultSource instance"); + my $attrs = @_ > 1 && ref $_[$#_] eq 'HASH' ? { %{pop(@_)} } : {}; my $query = ref $_[0] eq 'HASH' ? $_[0] : {@_}; - $self->result_source_instance->resultset->search(@_)->delete; + $rsrc->resultset->search(@_)->delete; } return $self; } @@ -613,14 +640,14 @@ sub delete { =item Arguments: $columnname -=item Returns: The value of the column +=item Return Value: The value of the column =back Throws an exception if the column name given doesn't exist according -to L. +to L. -Returns a raw column value from the row object, if it has already +Returns a raw column value from the result object, if it has already been fetched from the database or set by an accessor. If an L has been set, it @@ -657,7 +684,7 @@ sub get_column { =item Arguments: $columnname -=item Returns: 0|1 +=item Return Value: 0|1 =back @@ -681,7 +708,7 @@ sub has_column_loaded { =item Arguments: none -=item Returns: A hash of columnname, value pairs. +=item Return Value: A hash of columnname, value pairs. =back @@ -711,7 +738,7 @@ sub get_columns { =item Arguments: none -=item Returns: A hash of column, value pairs +=item Return Value: A hash of column, value pairs =back @@ -736,7 +763,7 @@ sub get_dirty_columns { =item Arguments: $columnname -=item Returns: undefined +=item Return Value: not defined =back @@ -776,7 +803,7 @@ sub make_column_dirty { =item Arguments: none -=item Returns: A hash of column, object|value pairs +=item Return Value: A hash of column, object|value pairs =back @@ -839,7 +866,7 @@ sub _is_column_numeric { =item Arguments: $columnname, $value -=item Returns: $value +=item Return Value: $value =back @@ -849,32 +876,23 @@ the column is marked as dirty for when you next call L. If passed an object or reference as a value, this method will happily attempt to store it, and a later L or L will try and stringify/numify as appropriate. To set an object to be deflated -instead, see L. +instead, see L, or better yet, use L. =cut sub set_column { my ($self, $column, $new_value) = @_; - # if we can't get an ident condition on first try - mark the object as unidentifiable - # (by using an empty hashref) and store the error for further diag - unless ($self->{_orig_ident}) { - try { - $self->{_orig_ident} = $self->ident_condition - } - catch { - $self->{_orig_ident_failreason} = $_; - $self->{_orig_ident} = {}; - }; - } + my $had_value = $self->has_column_loaded($column); + my ($old_value, $in_storage) = ($self->get_column($column), $self->in_storage) + if $had_value; - my $old_value = $self->get_column($column); $new_value = $self->store_column($column, $new_value); my $dirty = $self->{_dirty_columns}{$column} || - $self->in_storage # no point tracking dirtyness on uninserted data + $in_storage # no point tracking dirtyness on uninserted data ? ! $self->_eq_column_values ($column, $old_value, $new_value) : 1 ; @@ -903,6 +921,21 @@ sub set_column { delete $self->{_inflated_column}{$rel}; } } + + if ( + # value change from something (even if NULL) + $had_value + and + # no storage - no storage-value + $in_storage + and + # no value already stored (multiple changes before commit to storage) + ! exists $self->{_column_data_in_storage}{$column} + and + $self->_track_storage_value($column) + ) { + $self->{_column_data_in_storage}{$column} = $old_value; + } } return $new_value; @@ -928,6 +961,13 @@ sub _eq_column_values { } } +# returns a boolean indicating if the passed column should have its original +# value tracked between column changes and commitment to storage +sub _track_storage_value { + my ($self, $col) = @_; + return defined first { $col eq $_ } ($self->primary_columns); +} + =head2 set_columns $row->set_columns({ $col => $val, ... }); @@ -936,7 +976,7 @@ sub _eq_column_values { =item Arguments: \%columndata -=item Returns: The Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back @@ -962,16 +1002,16 @@ sub set_columns { =item Arguments: \%columndata -=item Returns: The Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back Sets more than one column value at once. Any inflated values are deflated and the raw values stored. -Any related values passed as Row objects, using the relation name as a +Any related values passed as Result objects, using the relation name as a key, are reduced to the appropriate foreign key values and stored. If -instead of related row objects, a hashref of column, value data is +instead of related result objects, a hashref of column, value data is passed, will create the related object first then store. Will even accept arrayrefs of data as a value to a @@ -1019,7 +1059,7 @@ sub set_inflated_columns { =item Arguments: \%replacementdata -=item Returns: The Row object copy +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> copy =back @@ -1067,7 +1107,7 @@ sub copy { next unless $rel_info->{attrs}{cascade_copy}; my $resolved = $self->result_source->_resolve_condition( - $rel_info->{cond}, $rel, $new + $rel_info->{cond}, $rel, $new, $rel ); my $copied = $rels_copied->{ $rel_info->{source} } ||= {}; @@ -1090,7 +1130,7 @@ sub copy { =item Arguments: $columnname, $value -=item Returns: The value sent to storage +=item Return Value: The value sent to storage =back @@ -1098,7 +1138,7 @@ Set a raw value for a column without marking it as changed. This method is used internally by L which you should probably be using. -This is the lowest level at which data is set on a row object, +This is the lowest level at which data is set on a result object, extend this method to catch all data setting methods. =cut @@ -1118,14 +1158,14 @@ sub store_column { =over -=item Arguments: $result_source, \%columndata, \%prefetcheddata +=item Arguments: L<$result_source|DBIx::Class::ResultSource>, \%columndata, \%prefetcheddata -=item Returns: A Row object +=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> =back All L methods that retrieve data from the -database and turn it into row objects call this method. +database and turn it into result objects call this method. Extend this method in your Result classes to hook into this process, for example to rebless the result into a different class. @@ -1141,9 +1181,6 @@ L, see L. sub inflate_result { my ($class, $source, $me, $prefetch) = @_; - $source = $source->resolve - if $source->isa('DBIx::Class::ResultSourceHandle'); - my $new = bless { _column_data => $me, _result_source => $source }, ref $class || $class @@ -1151,41 +1188,28 @@ sub inflate_result { foreach my $pre (keys %{$prefetch||{}}) { - my $pre_source = $source->related_source($pre) - or $class->throw_exception("Can't prefetch non-existent relationship ${pre}"); + my @pre_vals; + @pre_vals = (ref $prefetch->{$pre}[0] eq 'ARRAY') + ? @{$prefetch->{$pre}} : $prefetch->{$pre} + if @{$prefetch->{$pre}}; - my $accessor = $source->relationship_info($pre)->{attrs}{accessor} - or $class->throw_exception("No accessor for prefetched $pre"); + my $pre_source = $source->related_source($pre); - my @pre_vals; - if (ref $prefetch->{$pre}[0] eq 'ARRAY') { - @pre_vals = @{$prefetch->{$pre}}; - } - elsif ($accessor eq 'multi') { - $class->throw_exception("Implicit prefetch (via select/columns) not supported with accessor 'multi'"); - } - else { - @pre_vals = $prefetch->{$pre}; - } + my $accessor = $source->relationship_info($pre)->{attrs}{accessor} + or $class->throw_exception("No accessor type declared for prefetched relationship '$pre'"); my @pre_objects; for my $me_pref (@pre_vals) { - # FIXME - this should not be necessary - # the collapser currently *could* return bogus elements with all - # columns set to undef - my $has_def; - for (values %{$me_pref->[0]}) { - if (defined $_) { - $has_def++; - last; - } - } - next unless $has_def; + # FIXME SUBOPTIMAL - the new row parsers can very well optimize + # this away entirely, and *never* return such empty rows. + # For now we maintain inflate_result API backcompat, see + # t/resultset/inflate_result_api.t + next unless defined first { defined $_ } values %{$me_pref->[0]}; - push @pre_objects, $pre_source->result_class->inflate_result( - $pre_source, @$me_pref - ); + push @pre_objects, $pre_source->result_class->inflate_result( + $pre_source, @$me_pref + ); } if ($accessor eq 'single') { @@ -1210,7 +1234,7 @@ sub inflate_result { =item Arguments: none -=item Returns: Result of update or insert operation +=item Return Value: Result of update or insert operation =back @@ -1241,7 +1265,7 @@ sub update_or_insert { =item Arguments: none -=item Returns: 0|1 or @columnnames +=item Return Value: 0|1 or @columnnames =back @@ -1263,7 +1287,7 @@ sub is_changed { =item Arguments: $columname -=item Returns: 0|1 +=item Return Value: 0|1 =back @@ -1282,14 +1306,35 @@ sub is_column_changed { =over -=item Arguments: $result_source_instance +=item Arguments: L<$result_source?|DBIx::Class::ResultSource> -=item Returns: a ResultSource instance +=item Return Value: L<$result_source|DBIx::Class::ResultSource> =back Accessor to the L this object was created from. +=cut + +sub result_source { + $_[0]->throw_exception( 'result_source can be called on instances only' ) + unless ref $_[0]; + + @_ > 1 + ? $_[0]->{_result_source} = $_[1] + + # note this is a || not a ||=, the difference is important + : $_[0]->{_result_source} || do { + my $class = ref $_[0]; + $_[0]->can('result_source_instance') + ? $_[0]->result_source_instance + : $_[0]->throw_exception( + "No result source instance registered for $class, did you forget to call $class->table(...) ?" + ) + } + ; +} + =head2 register_column $column_info = { .... }; @@ -1299,7 +1344,7 @@ Accessor to the L this object was created from. =item Arguments: $columnname, \%columninfo -=item Returns: undefined +=item Return Value: not defined =back @@ -1330,11 +1375,11 @@ sub register_column { =item Arguments: \%attrs -=item Returns: A Row object +=item Return Value: A Result object =back -Fetches a fresh copy of the Row object from the database and returns it. +Fetches a fresh copy of the Result object from the database and returns it. Throws an exception if a proper WHERE clause identifying the database row can not be constructed (i.e. if the original object does not contain its entire @@ -1342,11 +1387,11 @@ entire ). If passed the \%attrs argument, will first apply these attributes to the resultset used to find the row. -This copy can then be used to compare to an existing row object, to +This copy can then be used to compare to an existing result object, to determine if any changes have been made in the database since it was created. -To just update your Row object with any latest changes from the +To just update your Result object with any latest changes from the database, use L instead. The \%attrs argument should be compatible with @@ -1363,15 +1408,10 @@ sub get_from_storage { $resultset = $resultset->search(undef, $attrs); } - my $ident_cond = $self->{_orig_ident} || $self->ident_condition; - - $self->throw_exception($self->{_orig_ident_failreason}) - if ! keys %$ident_cond; - - return $resultset->find($ident_cond); + return $resultset->find($self->_storage_ident_condition); } -=head2 discard_changes ($attrs?) +=head2 discard_changes $row->discard_changes @@ -1379,7 +1419,7 @@ sub get_from_storage { =item Arguments: none or $attrs -=item Returns: self (updates object in-place) +=item Return Value: self (updates object in-place) =back @@ -1428,7 +1468,6 @@ sub discard_changes { } } - =head2 throw_exception See L. @@ -1438,8 +1477,8 @@ See L. sub throw_exception { my $self=shift; - if (ref $self && ref $self->result_source && $self->result_source->schema) { - $self->result_source->schema->throw_exception(@_) + if (ref $self && ref $self->result_source ) { + $self->result_source->throw_exception(@_) } else { DBIx::Class::Exception->throw(@_); @@ -1461,11 +1500,9 @@ sub throw_exception { Returns the primary key(s) for a row. Can't be called as a class method. Actually implemented in L -1; - -=head1 AUTHORS +=head1 AUTHOR AND CONTRIBUTORS -Matt S. Trout +See L and L in DBIx::Class =head1 LICENSE