my $cd = $millennium_cds_rs->next; # SELECT ... FROM cds JOIN artists ...
my $cd_artist_name = $cd->artist->name; # Already has the data so no 2nd query
- # new() makes a DBIx::Class::Row object but doesnt insert it into the DB.
+ # new() makes a Result object but doesnt insert it into the DB.
# create() is the same as new() then insert().
my $new_cd = $schema->resultset('CD')->new({ title => 'Spoon' });
$new_cd->artist($cd->artist);
=back
+A better overview of the methods found in a Result class can be found
+in L<DBIx::Class::Manual::ResultClass>.
+
=head1 AUTHOR AND CONTRIBUTORS
See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
=head1 ROW-LEVEL OPERATIONS
-=head2 Retrieving a row object's Schema
+=head2 Retrieving a result object's Schema
-It is possible to get a Schema object from a row object like so:
+It is possible to get a Schema object from a result object like so:
my $schema = $cd->result_source->schema;
# use the schema as normal:
Alternatively you can use L<DBIx::Class::DynamicSubclass> that implements
exactly the above functionality.
-=head2 Skip row object creation for faster results
+=head2 Skip result object creation for faster results
DBIx::Class is not built for speed, it's built for convenience and
ease of use, but sometimes you just need to get the data, and skip the
=head2 Creating a result set from a set of rows
-Sometimes you have a (set of) row objects that you want to put into a
+Sometimes you have a (set of) result objects that you want to put into a
resultset without the need to hit the DB again. You can do that by using the
L<set_cache|DBIx::Class::Resultset/set_cache> method:
=item *
Use L<populate|DBIx::Class::ResultSet/populate> in void context to insert data
-when you don't need the resulting L<DBIx::Class::Row> objects, if possible, but
-see the caveats.
+when you don't need the resulting L<result|DBIx::Class::Manual::ResultClass> objects,
+if possible, but see the caveats.
When inserting many rows, for best results, populate a large number of rows at a
time, but not so large that the table is locked for an unacceptably long time.
=item .. insert a row with an auto incrementing primary key?
This happens automatically. After
-L<creating|DBIx::Class::ResultSet/create> a row object, the primary
+L<creating|DBIx::Class::ResultSet/create> a result object, the primary
key value created by your database can be fetched by calling C<id> (or
the access of your primary key column) on the object.
if you create a resultset using C<search> in scalar context, no query
is executed. You can create further resultset refinements by calling
search again or relationship accessors. The SQL query is only run when
-you ask the resultset for an actual row object.
+you ask the resultset for an actual result object.
=item How do I deal with tables that lack a primary key?
=item How do I reduce the overhead of database queries?
You can reduce the overhead of object creation within L<DBIx::Class>
-using the tips in L<DBIx::Class::Manual::Cookbook/"Skip row object creation for faster results">
+using the tips in L<DBIx::Class::Manual::Cookbook/"Skip result object creation for faster results">
and L<DBIx::Class::Manual::Cookbook/"Get raw data for blindingly fast results">
=item How do I override a run time method (e.g. a relationship accessor)?
=head2 Result class
A Result class defines both a source of data (usually one per table),
-and the methods that will be available in the L</Row> objects created
-using that source.
+and the methods that will be available in the L</Result> objects
+created using that source.
One Result class is needed per data source (table, view, query) used
in your application, they should inherit from L<DBIx::Class::Core>.
+See also: L<DBIx::Class::Manual::ResultClass>
+
=head2 ResultSource
ResultSource objects represent the source of your data, these are
=head2 Record
-See Row.
+See Result.
=head2 Row
-Row objects contain your actual data. They are returned from ResultSet objects.
+See Result.
+
+=head2 Result
+
+Result objects contain your actual data. They are returned from
+ResultSet objects. These are sometimes (incorrectly) called
+row objects, including older versions of the DBIC documentation.
+
+See also: L<DBIx::Class::Manual::ResultClass>
=head2 Object
-See Row.
+See Result.
=head2 join
+See Join.
+
=head2 prefetch
+Similiar to a join, except the related result objects are fetched and
+cached for future use, instead of used directly from the ResultSet. This
+allows you to jump to different relationships within a Result without
+worrying about generating a ton of extra SELECT statements.
=head1 SQL TERMS
+=head2 CRUD
+
+Create, Read, Update, Delete. A general concept of something that can
+do all four operations (INSERT, SELECT, UPDATE, DELETE), usually at a
+row-level.
+
=head2 Join
This is an SQL keyword, it is used to link multiple tables in one SQL
=head2 Related data
In SQL, related data actually refers to data that are normalised into
-the same table. (Yes. DBIC does mis-use this term).
+the same table. (Yes. DBIC does mis-use this term.)
+
+=head1 AUTHOR AND CONTRIBUTORS
+
+See L<AUTHOR|DBIx::Class/AUTHOR> and L<CONTRIBUTORS|DBIx::Class/CONTRIBUTORS> in DBIx::Class
+
+=head1 LICENSE
+
+You may distribute this code under the same terms as Perl itself.
=head2 Search results are returned as Rows
Rows of the search from the database are blessed into
-L<DBIx::Class::Row> objects.
+L<Result|DBIx::Class::Manual::ResultClass> objects.
=head1 SETTING UP DBIx::Class
=item *
+L<$obj|DBIx::Class> - Reference to the source class or object definition
+
+All arguments and return values should provide a link to the object's
+class documentation or definition, even if it's the same class as the current
+documentation. For example:
+
+ ## Correct, if stated within DBIx::Class::ResultSet
+ L<$resultset|/new>
+
+ ## Correct, if stated outside DBIx::Class::ResultSet
+ L<$resultset|DBIx::Class::ResultSet>
+
+=item *
+
? - Optional, should be placed after the argument type and name.
## Correct
=back
-The second item starts with the text "Return value:". The remainder of
-the line is either the text "undefined", a text describing the result of
-the method, or a variable with a descriptive name.
+The second item starts with the text "Return Value:". The remainder of
+the line is either the text "not defined" or a variable with a descriptive
+name.
## Good examples
- =item Return value: undefined
- =item Return value: A schema object
- =item Return value: $classname
+ =item Return Value: not defined
+ =item Return Value: L<$schema|DBIx::Class::Schema>
+ =item Return Value: $classname
## Bad examples
- =item Return value: The names
+ =item Return Value: The names
-"undefined" means the method does not deliberately return a value, and
-the caller should not use or rely on anything it does return. (Perl
+"not defined" means the method does not deliberately return a value, and
+the caller should not use or rely on anything it does return. (Perl
functions always return something, usually the result of the last code
-statement, if there is no explicit return statement.)
+statement, if there is no explicit return statement.) This is different
+than specifying "undef", which means that it explicitly returns undef,
+though usually this is used an alternate return (like C<$obj | undef>).
=item *
-The argument list is followed by a single paragraph describing what
+The argument/return list is followed by a single paragraph describing what
the method does.
=item *
=item *
-The argument list is followed by some examples of how to use the
+The argument/return list is followed by some examples of how to use the
method, using its various types of arguments.
The examples can also include ways to use the results if
This issue is due to perl doing an exhaustive search of blessed objects
under certain circumstances. The problem shows up as performance
-degradation exponential to the number of L<DBIx::Class> row objects in
+degradation exponential to the number of L<DBIx::Class> result objects in
memory, so can be unnoticeable with certain data sets, but with huge
performance impacts on other datasets.
It has been observed, using L<DBD::ODBC>, that creating a L<DBIx::Class::Row>
object which includes a column of data type TEXT/BLOB/etc. will allocate
LongReadLen bytes. This allocation does not leak, but if LongReadLen
-is large in size, and many such row objects are created, e.g. as the
+is large in size, and many such result objects are created, e.g. as the
output of a ResultSet query, the memory footprint of the Perl interpreter
can grow very large.
'=head2 req_group_list',
'=over',
'=item Arguments: none',
- '=item Returns: \%list_of_requirement_groups',
+ '=item Return Value: \%list_of_requirement_groups',
'=back',
<<'EOD',
This method should be used by DBIx::Class packagers, to get a hashref of all
'=head2 req_list_for',
'=over',
'=item Arguments: $group_name',
- '=item Returns: \%list_of_module_version_pairs',
+ '=item Return Value: \%list_of_module_version_pairs',
'=back',
<<'EOD',
This method should be used by DBIx::Class extension authors, to determine the
'=head2 req_ok_for',
'=over',
'=item Arguments: $group_name',
- '=item Returns: 1|0',
+ '=item Return Value: 1|0',
'=back',
<<'EOD',
Returns true or false depending on whether all modules required by
'=head2 req_missing_for',
'=over',
'=item Arguments: $group_name',
- '=item Returns: $error_message_string',
+ '=item Return Value: $error_message_string',
'=back',
<<"EOD",
Returns a single line string suitable for inclusion in larger error messages.
'=head2 req_errorlist_for',
'=over',
'=item Arguments: $group_name',
- '=item Returns: \%list_of_loaderrors_per_module',
+ '=item Return Value: \%list_of_loaderrors_per_module',
'=back',
<<'EOD',
Returns a hashref containing the actual errors that occured while attempting
return defined $lsib ? $lsib : 0;
}
-# an optimized method to get the last sibling position value without inflating a row object
+# an optimized method to get the last sibling position value without inflating a result object
sub _last_sibling_posval {
my $self = shift;
my $position_column = $self->position_column;
if (@missing && $self->in_storage) {
$self->throw_exception (
- 'Unable to uniquely identify row object with missing PK columns: '
+ 'Unable to uniquely identify result object with missing PK columns: '
. join (', ', @missing )
);
}
=head2 ID
-Returns a unique id string identifying a row object by primary key.
+Returns a unique id string identifying a result object by primary key.
Used by L<DBIx::Class::CDBICompat::LiveObjectIndex> and
L<DBIx::Class::ObjectCache>.
if (@undef && $self->in_storage) {
$self->throw_exception (
- 'Unable to construct row object identity condition due to NULL PK columns: '
+ 'Unable to construct result object identity condition due to NULL PK columns: '
. join (', ', @undef)
);
}
L<DBIx::Class::Manual::Glossary/"Row"> objects that represent the items
of your table. From L<DBIx::Class::Manual::Glossary/"ResultSet"> objects,
the relationships can be searched using the "search_related" method.
-In list context, each returns a list of Row objects for the related class,
+In list context, each returns a list of Result objects for the related class,
in scalar context, a new ResultSet representing the joined tables is
returned. Thus, the calls can be chained to produce complex queries.
Since the database is not actually queried until you attempt to retrieve
=item accessor_name
This argument is the name of the method you can call on a
-L<DBIx::Class::Row> object to retrieve the instance of the foreign
+L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
class matching this relationship. This is often called the
C<relation(ship) name>.
=over 4
-=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?
+=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
=back
=item accessor_name
This argument is the name of the method you can call on a
-L<DBIx::Class::Row> object to retrieve a resultset of the related
-class restricted to the ones related to the row object. In list
-context it returns the row objects. This is often called the
+L<Result|DBIx::Class::Manual::ResultClass> object to retrieve a resultset of the related
+class restricted to the ones related to the result object. In list
+context it returns the result objects. This is often called the
C<relation(ship) name>.
Use this accessor_name in L<DBIx::Class::ResultSet/join>
=over 4
-=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?
+=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
=back
=item accessor_name
This argument is the name of the method you can call on a
-L<DBIx::Class::Row> object to retrieve the instance of the foreign
+L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
class matching this relationship. This is often called the
C<relation(ship) name>.
=over 4
-=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, \%attrs?
+=item Arguments: $accessor_name, $related_class, $their_fk_column|\%cond|\@cond|\&cond?, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
=back
=item accessor_name
This argument is the name of the method you can call on a
-L<DBIx::Class::Row> object to retrieve the instance of the foreign
+L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the instance of the foreign
class matching this relationship. This is often called the
C<relation(ship) name>.
=over 4
-=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, \%attrs?
+=item Arguments: $accessor_name, $link_rel_name, $foreign_rel_name, L<\%attrs?|DBIx::Class::ResultSet/ATTRIBUTES>
=back
=item accessor_name
This argument is the name of the method you can call on a
-L<DBIx::Class::Row> object to retrieve the rows matching this
+L<Result|DBIx::Class::Manual::ResultClass> object to retrieve the rows matching this
relationship.
On a many_to_many, unlike other relationships, this cannot be used in
DBIx::Class is faster than older ORMs like Class::DBI but it still isn't
designed primarily for speed. Sometimes you need to quickly retrieve the data
-from a massive resultset, while skipping the creation of fancy row objects.
+from a massive resultset, while skipping the creation of fancy result objects.
Specifying this class as a C<result_class> for a resultset will change C<< $rs->next >>
to return a plain data hash-ref (or a list of such hash-refs if C<< $rs->all >> is used).
there are none).
Much like L<DBIx::Class::ResultSet/all> but returns values rather
-than row objects.
+than result objects.
=cut
=item Arguments: none
-=item Return Value: $resultset
+=item Return Value: L<$resultset|DBIx::Class::ResultSet>
=back
=item Arguments: none
-=item Return Value: $resultset
+=item Return Value: L<$resultset|DBIx::Class::ResultSet>
=back
=item Arguments: none
-=item Return Value: $resultset
+=item Return Value: L<$resultset|DBIx::Class::ResultSet>
=back
=item Arguments: $function
-=item Return Value: $resultset
+=item Return Value: L<$resultset|DBIx::Class::ResultSet>
=back
$schema->source($source_name);
-=item From a Row object:
+=item From a Result object:
$row->result_source;
=item Arguments: @columns
-=item Return value: The ResultSource object
+=item Return Value: L<$result_source|/new>
=back
calls of this method will add more columns, not replace them.
The column names given will be created as accessor methods on your
-L<DBIx::Class::Row> objects. You can change the name of the accessor
+L<Result|DBIx::Class::Manual::ResultClass> objects. You can change the name of the accessor
by supplying an L</accessor> in the column_info hash.
If a column name beginning with a plus sign ('+col1') is provided, the
=item Arguments: $colname, \%columninfo?
-=item Return value: 1/0 (true/false)
+=item Return Value: 1/0 (true/false)
=back
=item Arguments: $colname
-=item Return value: 1/0 (true/false)
+=item Return Value: 1/0 (true/false)
=back
=item Arguments: $colname
-=item Return value: Hashref of info
+=item Return Value: Hashref of info
=back
=over
-=item Arguments: None
+=item Arguments: none
-=item Return value: Ordered list of column names
+=item Return Value: Ordered list of column names
=back
=item Arguments: \@colnames ?
-=item Return value: Hashref of column name/info pairs
+=item Return Value: Hashref of column name/info pairs
=back
=item Arguments: @colnames
-=item Return value: undefined
+=item Return Value: not defined
=back
=item Arguments: $colname
-=item Return value: undefined
+=item Return Value: not defined
=back
=item Arguments: @cols
-=item Return value: undefined
+=item Return Value: not defined
=back
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: Ordered list of primary column names
+=item Return Value: Ordered list of primary column names
=back
=item Arguments: $sequence_name
-=item Return value: undefined
+=item Return Value: not defined
=back
=item Arguments: $name?, \@colnames
-=item Return value: undefined
+=item Return Value: not defined
=back
=item Arguments: @constraints
-=item Return value: undefined
+=item Return Value: not defined
=back
=item Arguments: \@colnames
-=item Return value: Constraint name
+=item Return Value: Constraint name
=back
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: Hash of unique constraint data
+=item Return Value: Hash of unique constraint data
=back
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: Unique constraint names
+=item Return Value: Unique constraint names
=back
=item Arguments: $constraintname
-=item Return value: List of constraint columns
+=item Return Value: List of constraint columns
=back
=item Arguments: $callback_name | \&callback_code
-=item Return value: $callback_name | \&callback_code
+=item Return Value: $callback_name | \&callback_code
=back
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: $resultset
+=item Return Value: L<$resultset|DBIx::Class::ResultSet>
=back
=item Arguments: $classname
-=item Return value: $classname
+=item Return Value: $classname
=back
=item Arguments: \%attrs
-=item Return value: \%attrs
+=item Return Value: \%attrs
=back
=over 4
-=item Arguments: None
+=item Arguments: none
=item Result value: $name
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: FROM clause
+=item Return Value: FROM clause
=back
=over 4
-=item Arguments: $schema
+=item Arguments: L<$schema?|DBIx::Class::Schema>
-=item Return value: A schema object
+=item Return Value: L<$schema|DBIx::Class::Schema>
=back
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: A Storage object
+=item Return Value: L<$storage|DBIx::Class::Storage>
=back
$source->storage->debug(1);
-Returns the storage handle for the current schema.
-
-See also: L<DBIx::Class::Storage>
+Returns the L<storage handle|DBIx::Class::Storage> for the current schema.
=cut
=over 4
-=item Arguments: $relname, $related_source_name, \%cond, [ \%attrs ]
+=item Arguments: $rel_name, $related_source_name, \%cond, \%attrs?
-=item Return value: 1/true if it succeeded
+=item Return Value: 1/true if it succeeded
=back
- $source->add_relationship('relname', 'related_source', $cond, $attrs);
+ $source->add_relationship('rel_name', 'related_source', $cond, $attrs);
L<DBIx::Class::Relationship> describes a series of methods which
create pre-defined useful types of relationships. Look there first
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: List of relationship names
+=item Return Value: L<@rel_names|DBIx::Class::Relationship>
=back
=over 4
-=item Arguments: $relname
+=item Arguments: L<$rel_name|DBIx::Class::Relationship>
-=item Return value: Hashref of relation data,
+=item Return Value: L<\%rel_data|DBIx::Class::Relationship::Base/add_relationship>
=back
Returns a hash of relationship information for the specified relationship
-name. The keys/values are as specified for L</add_relationship>.
+name. The keys/values are as specified for L<DBIx::Class::Relationship::Base/add_relationship>.
=cut
=over 4
-=item Arguments: $rel
+=item Arguments: L<$rel_name|DBIx::Class::Relationship>
-=item Return value: 1/0 (true/false)
+=item Return Value: 1/0 (true/false)
=back
=over 4
-=item Arguments: $relname
+=item Arguments: L<$rel_name|DBIx::Class::Relationship>
-=item Return value: Hashref of relationship data
+=item Return Value: L<\%rel_data|DBIx::Class::Relationship::Base/add_relationship>
=back
# having already been inserted. Takes the name of the relationship and a
# hashref of columns of the related object.
sub _pk_depends_on {
- my ($self, $relname, $rel_data) = @_;
+ my ($self, $rel_name, $rel_data) = @_;
- my $relinfo = $self->relationship_info($relname);
+ my $relinfo = $self->relationship_info($rel_name);
# don't assume things if the relationship direction is specified
return $relinfo->{attrs}{is_foreign_key_constraint}
# assume anything that references our PK probably is dependent on us
# rather than vice versa, unless the far side is (a) defined or (b)
# auto-increment
- my $rel_source = $self->related_source($relname);
+ my $rel_source = $self->related_source($rel_name);
foreach my $p ($self->primary_columns) {
if (exists $keyhash->{$p}) {
# list of non-triviail values (notmally conditions) returned as a part
# of a joinfree condition hash
sub _resolve_condition {
- my ($self, $cond, $as, $for, $relname) = @_;
+ my ($self, $cond, $as, $for, $rel_name) = @_;
my $obj_rel = !!blessed $for;
self_alias => $obj_rel ? $as : $for,
foreign_alias => $relalias,
self_resultsource => $self,
- foreign_relname => $relname || ($obj_rel ? $as : $for),
+ foreign_relname => $rel_name || ($obj_rel ? $as : $for),
self_rowobj => $obj_rel ? $for : undef
});
# FIXME sanity check until things stabilize, remove at some point
$self->throw_exception (
- "A join-free condition returned for relationship '$relname' without a row-object to chain from"
+ "A join-free condition returned for relationship '$rel_name' without a row-object to chain from"
) unless $obj_rel;
# FIXME another sanity check
first { $_ !~ /^\Q$relalias.\E.+/ } keys %$joinfree_cond
) {
$self->throw_exception (
- "The join-free condition returned for relationship '$relname' must be a hash "
+ "The join-free condition returned for relationship '$rel_name' must be a hash "
.'reference with all keys being valid columns on the related result source'
);
}
}
# see which parts of the joinfree cond are conditionals
- my $relcol_list = { map { $_ => 1 } $self->related_source($relname)->columns };
+ my $relcol_list = { map { $_ => 1 } $self->related_source($rel_name)->columns };
for my $c (keys %$joinfree_cond) {
my ($colname) = $c =~ /^ (?: \Q$relalias.\E )? (.+)/x;
elsif (ref $cond eq 'ARRAY') {
my (@ret, $crosstable);
for (@$cond) {
- my ($cond, $crosstab) = $self->_resolve_condition($_, $as, $for, $relname);
+ my ($cond, $crosstab) = $self->_resolve_condition($_, $as, $for, $rel_name);
push @ret, $cond;
$crosstable ||= $crosstab;
}
return wantarray ? (\@ret, $crosstable) : \@ret;
}
else {
- $self->throw_exception ("Can't handle condition $cond for relationship '$relname' yet :(");
+ $self->throw_exception ("Can't handle condition $cond for relationship '$rel_name' yet :(");
}
}
=over 4
-=item Arguments: $relname
+=item Arguments: $rel_name
-=item Return value: $source
+=item Return Value: $source
=back
=over 4
-=item Arguments: $relname
+=item Arguments: $rel_name
-=item Return value: $classname
+=item Return Value: $classname
=back
=over 4
-=item Arguments: None
+=item Arguments: none
-=item Return value: $source_handle
+=item Return Value: L<$source_handle|DBIx::Class::ResultSourceHandle>
=back
=item Arguments: 1/0 (default: 0)
-=item Return value: 1/0
+=item Return Value: 1/0
=back
This class is responsible for defining and doing basic operations on rows
derived from L<DBIx::Class::ResultSource> objects.
-Row objects are returned from L<DBIx::Class::ResultSet>s using the
+Result objects are returned from L<DBIx::Class::ResultSet>s using the
L<create|DBIx::Class::ResultSet/create>, L<find|DBIx::Class::ResultSet/find>,
L<next|DBIx::Class::ResultSet/next> and L<all|DBIx::Class::ResultSet/all> methods,
as well as invocations of 'single' (
L<belongs_to|DBIx::Class::Relationship/belongs_to>,
L<has_one|DBIx::Class::Relationship/has_one> or
L<might_have|DBIx::Class::Relationship/might_have>)
-relationship accessors of L<DBIx::Class::Row> objects.
+relationship accessors of L<Result|DBIx::Class::Manual::ResultClass> objects.
=head1 NOTE
L<DBIx::Class::Row>. Therefore, while many of the methods available to a
L<DBIx::Class::Core>-derived Result class are described in the following
documentation, it does not detail all of the methods available to Result
-objects. Refer to L<DBIx::Class::Core> for more info.
+objects. Refer to L<DBIx::Class::Manual::ResultClass> for more info.
=head1 METHODS
=item Arguments: \%attrs or \%colsandvalues
-=item Returns: A DBIx::Class::Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
-While you can create a new row object by calling C<new> directly on
+While you can create a new result object by calling C<new> directly on
this class, you are better off calling it on a
L<DBIx::Class::ResultSet> object.
=item Arguments: $value?
-=item Returns: $value
+=item Return Value: $value
=back
=item Arguments: none
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
it isn't already in there. Returns the object itself. To insert an
entirely new row into the database, use L<DBIx::Class::ResultSet/create>.
-To fetch an uninserted row object, call
+To fetch an uninserted result object, call
L<new|DBIx::Class::ResultSet/new> on a resultset.
This will also insert any uninserted, related objects held inside this
=item Arguments: none or 1|0
-=item Returns: 1|0
+=item Return Value: 1|0
=back
L<DBIx::Class::ResultSet/create> or L<DBIx::Class::ResultSet/insert>
are used.
-Creating a row object using L<DBIx::Class::ResultSet/new>, or calling
+Creating a result object using L<DBIx::Class::ResultSet/new>, or calling
L</delete> on one, sets it to false.
=cut
=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</in_storage>.
This method issues an SQL UPDATE query to commit any changes to the
$row->update({ last_modified => \'NOW()' });
The update will pass the values verbatim into SQL. (See
-L<SQL::Abstract> docs). The values in your Row object will NOT change
+L<SQL::Abstract> 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</discard_changes>
after the update.
=item Arguments: none
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
rows.
If you delete an object within a txn_do() (see L<DBIx::Class::Storage/txn_do>)
-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
=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<has_column|DBIx::Class::ResultSource/has_column>.
-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<inflated value|DBIx::Class::InflateColumn> has been set, it
=item Arguments: $columnname
-=item Returns: 0|1
+=item Return Value: 0|1
=back
=item Arguments: none
-=item Returns: A hash of columnname, value pairs.
+=item Return Value: A hash of columnname, value pairs.
=back
=item Arguments: none
-=item Returns: A hash of column, value pairs
+=item Return Value: A hash of column, value pairs
=back
=item Arguments: $columnname
-=item Returns: undefined
+=item Return Value: not defined
=back
=item Arguments: none
-=item Returns: A hash of column, object|value pairs
+=item Return Value: A hash of column, object|value pairs
=back
=item Arguments: $columnname, $value
-=item Returns: $value
+=item Return Value: $value
=back
=item Arguments: \%columndata
-=item Returns: The Row object
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass>
=back
=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
=item Arguments: \%replacementdata
-=item Returns: The Row object copy
+=item Return Value: L<$result|DBIx::Class::Manual::ResultClass> copy
=back
=item Arguments: $columnname, $value
-=item Returns: The value sent to storage
+=item Return Value: The value sent to storage
=back
method is used internally by L</set_column> 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
=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<DBIx::Class::ResultSet> 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.
=item Arguments: none
-=item Returns: Result of update or insert operation
+=item Return Value: Result of update or insert operation
=back
=item Arguments: none
-=item Returns: 0|1 or @columnnames
+=item Return Value: 0|1 or @columnnames
=back
=item Arguments: $columname
-=item Returns: 0|1
+=item Return Value: 0|1
=back
=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
=item Arguments: $columnname, \%columninfo
-=item Returns: undefined
+=item Return Value: not defined
=back
=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
). 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</discard_changes> instead.
The \%attrs argument should be compatible with
=item Arguments: none or $attrs
-=item Returns: self (updates object in-place)
+=item Return Value: self (updates object in-place)
=back
=item Arguments: $storage_type|{$storage_type, \%args}
-=item Return value: $storage_type|{$storage_type, \%args}
+=item Return Value: $storage_type|{$storage_type, \%args}
=item Default value: DBIx::Class::Storage::DBI
=item Arguments: $code_reference
-=item Return value: $code_reference
+=item Return Value: $code_reference
=item Default value: None
=over 4
-=item Arguments: $source_name
+=item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>
-=item Return Value: $resultset
+=item Return Value: L<$resultset|DBIx::Class::ResultSet>
=back
=cut
sub resultset {
- my ($self, $moniker) = @_;
+ my ($self, $source_name) = @_;
$self->throw_exception('resultset() expects a source name')
- unless defined $moniker;
- return $self->source($moniker)->resultset;
+ unless defined $source_name;
+ return $self->source($source_name)->resultset;
}
=head2 sources
=over 4
-=item Return Value: @source_names
+=item Return Value: L<@source_names|DBIx::Class::ResultSource/source_name>
=back
=over 4
-=item Arguments: $source_name
+=item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>
-=item Return Value: $result_source
+=item Return Value: L<$result_source|DBIx::Class::ResultSource>
=back
$self->throw_exception("source() expects a source name")
unless @_;
- my $moniker = shift;
+ my $source_name = shift;
my $sreg = $self->source_registrations;
- return $sreg->{$moniker} if exists $sreg->{$moniker};
+ return $sreg->{$source_name} if exists $sreg->{$source_name};
# if we got here, they probably passed a full class name
- my $mapped = $self->class_mappings->{$moniker};
- $self->throw_exception("Can't find source for ${moniker}")
+ my $mapped = $self->class_mappings->{$source_name};
+ $self->throw_exception("Can't find source for ${source_name}")
unless $mapped && exists $sreg->{$mapped};
return $sreg->{$mapped};
}
=over 4
-=item Arguments: $source_name
+=item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>
=item Return Value: $classname
=cut
sub class {
- my ($self, $moniker) = @_;
- return $self->source($moniker)->result_class;
+ my ($self, $source_name) = @_;
+ return $self->source($source_name)->result_class;
}
=head2 txn_do
=over 4
-=item Arguments: $source_name, \@data;
+=item Arguments: L<$source_name|DBIx::Class::ResultSource/source_name>, \@data;
-=item Return value: \@$objects | nothing
+=item Return Value: L<\@$results|DBIx::Class::Manual::ResultClass> | undef
=back
references in a column in one row, and not in another will probably not work.
Otherwise, each set of data is inserted into the database using
-L<DBIx::Class::ResultSet/create>, and a arrayref of the resulting row
+L<DBIx::Class::ResultSet/create>, and an arrayref of the Result
objects is returned.
e.g.
# my ($self, $target, $base) = @_;
# my $schema = $self->clone;
-# foreach my $moniker ($schema->sources) {
-# my $source = $schema->source($moniker);
-# my $target_class = "${target}::${moniker}";
+# foreach my $source_name ($schema->sources) {
+# my $source = $schema->source($source_name);
+# my $target_class = "${target}::${source_name}";
# $self->inject_base(
# $target_class => $source->result_class, ($base ? $base : ())
# );
# $source->result_class($target_class);
# $target_class->result_source_instance($source)
# if $target_class->can('result_source_instance');
-# $schema->register_source($moniker, $source);
+# $schema->register_source($source_name, $source);
# }
# return $schema;
# }
use warnings qw/redefine/;
no strict qw/refs/;
- foreach my $moniker ($self->sources) {
- my $orig_source = $self->source($moniker);
+ foreach my $source_name ($self->sources) {
+ my $orig_source = $self->source($source_name);
- my $target_class = "${target}::${moniker}";
+ my $target_class = "${target}::${source_name}";
$self->inject_base($target_class, $orig_source->result_class, ($base || ()) );
# register_source examines result_class, and then returns us a clone
- my $new_source = $schema->register_source($moniker, bless
+ my $new_source = $schema->register_source($source_name, bless
{ %$orig_source, result_class => $target_class },
ref $orig_source,
);
$self->class_mappings({ %{$from->class_mappings} });
$self->source_registrations({ %{$from->source_registrations} });
- foreach my $moniker ($from->sources) {
- my $source = $from->source($moniker);
+ foreach my $source_name ($from->sources) {
+ my $source = $from->source($source_name);
my $new = $source->new($source);
# we use extra here as we want to leave the class_mappings as they are
# but overwrite the source_registrations entry with the new source
- $self->register_extra_source($moniker => $new);
+ $self->register_extra_source($source_name => $new);
}
if ($from->storage) {
=item Arguments: See L<DBIx::Class::Storage::DBI/deployment_statements>
-=item Return value: $listofstatements
+=item Return Value: $listofstatements
=back
=item Arguments: $database-type, $version, $directory, $preversion
-=item Return value: $normalised_filename
+=item Return Value: $normalised_filename
=back
=over 4
-=item Arguments: $moniker, $component_class
+=item Arguments: $source_name, $component_class
=back
Registers a class which isa DBIx::Class::ResultSourceProxy. Equivalent to
calling:
- $schema->register_source($moniker, $component_class->result_source_instance);
+ $schema->register_source($source_name, $component_class->result_source_instance);
=cut
sub register_class {
- my ($self, $moniker, $to_register) = @_;
- $self->register_source($moniker => $to_register->result_source_instance);
+ my ($self, $source_name, $to_register) = @_;
+ $self->register_source($source_name => $to_register->result_source_instance);
}
=head2 register_source
=over 4
-=item Arguments: $moniker, $result_source
+=item Arguments: $source_name, L<$result_source|DBIx::Class::ResultSource>
=back
This method is called by L</register_class>.
Registers the L<DBIx::Class::ResultSource> in the schema with the given
-moniker.
+source name.
=cut
=over 4
-=item Arguments: $moniker
+=item Arguments: $source_name
=back
-Removes the L<DBIx::Class::ResultSource> from the schema for the given moniker.
+Removes the L<DBIx::Class::ResultSource> from the schema for the given source name.
=cut
=over 4
-=item Arguments: $moniker, $result_source
+=item Arguments: $source_name, L<$result_source|DBIx::Class::ResultSource>
=back
sub register_extra_source { shift->_register_source(@_, { extra => 1 }) }
sub _register_source {
- my ($self, $moniker, $source, $params) = @_;
+ my ($self, $source_name, $source, $params) = @_;
- $source = $source->new({ %$source, source_name => $moniker });
+ $source = $source->new({ %$source, source_name => $source_name });
$source->schema($self);
weaken $source->{schema} if ref($self);
my %reg = %{$self->source_registrations};
- $reg{$moniker} = $source;
+ $reg{$source_name} = $source;
$self->source_registrations(\%reg);
return $source if $params->{extra};
if (
exists $map{$rs_class}
and
- $map{$rs_class} ne $moniker
+ $map{$rs_class} ne $source_name
and
$rsrc ne $_[2] # orig_source
) {
;
}
- $map{$rs_class} = $moniker;
+ $map{$rs_class} = $source_name;
$self->class_mappings(\%map);
}
my $self = shift;
my $srcs = $self->source_registrations;
- for my $moniker (keys %$srcs) {
+ for my $source_name (keys %$srcs) {
# find first source that is not about to be GCed (someone other than $self
# holds a reference to it) and reattach to it, weakening our own link
#
# which will serve as a signal to not try doing anything else
# however beware - on older perls the exception seems randomly untrappable
# due to some weird race condition during thread joining :(((
- if (ref $srcs->{$moniker} and svref_2object($srcs->{$moniker})->REFCNT > 1) {
+ if (ref $srcs->{$source_name} and svref_2object($srcs->{$source_name})->REFCNT > 1) {
local $@;
eval {
- $srcs->{$moniker}->schema($self);
- weaken $srcs->{$moniker};
+ $srcs->{$source_name}->schema($self);
+ weaken $srcs->{$source_name};
1;
} or do {
$global_phase_destroy = 1;
}
sub _unregister_source {
- my ($self, $moniker) = @_;
+ my ($self, $source_name) = @_;
my %reg = %{$self->source_registrations};
- my $source = delete $reg{$moniker};
+ my $source = delete $reg{$source_name};
$self->source_registrations(\%reg);
if ($source->result_class) {
my %map = %{$self->class_mappings};
if ($self eq $target) {
# Pathological case, largely caused by the docs on early C::M::DBIC::Plain
- foreach my $moniker ($self->sources) {
- my $source = $self->source($moniker);
+ foreach my $source_name ($self->sources) {
+ my $source = $self->source($source_name);
my $class = $source->result_class;
$self->inject_base($class, $base);
$class->mk_classdata(resultset_instance => $source->resultset);
}
$schema->connection(@info);
- foreach my $moniker ($schema->sources) {
- my $source = $schema->source($moniker);
+ foreach my $source_name ($schema->sources) {
+ my $source = $schema->source($source_name);
my $class = $source->result_class;
- #warn "$moniker $class $source ".$source->storage;
+ #warn "$source_name $class $source ".$source->storage;
$class->mk_classdata(result_source_instance => $source);
$class->mk_classdata(resultset_instance => $source->resultset);
$class->mk_classdata(class_resolver => $schema);
=over 4
-=item Returns: a list of version numbers, ordered from lowest to highest
+=item Return Value: a list of version numbers, ordered from lowest to highest
=back
=head1 DESCRIPTION
-This component adds hooks for Storable so that row objects can be
-serialized. It assumes that your row object class (C<result_class>) is
+This component adds hooks for Storable so that result objects can be
+serialized. It assumes that your result object class (C<result_class>) is
the same as your table class, which is the normal situation.
=head1 HOOKS
###
# This would be the point to deflate anything found in $where
# (and leave $attrs->{bind} intact). Problem is - inflators historically
- # expect a row object. And all we have is a resultsource (it is trivial
+ # expect a result object. And all we have is a resultsource (it is trivial
# to extract deflator coderefs via $alias2source above).
#
# I don't see a way forward other than changing the way deflators are
=over 4
-=item Arguments: $schema \@databases, $version, $directory, $preversion, \%sqlt_args
+=item Arguments: $schema, \@databases, $version, $directory, $preversion, \%sqlt_args
=back
=item Arguments: $relname, $join_count
+=item Return Value: $alias
+
=back
L<DBIx::Class> uses L<DBIx::Class::Relationship> names as table aliases in
projects / dbsrgits/DBIx-Class.git / commitdiff