cascade results from the CPAN

DBIx-DataModel

=item name

Optional name for the association (otherwise an implicit name
will be built by default from the concatenation of the role names).

=item kind

A string describing the association kind, i.e. one of :
C<Association>, C<Aggregation> or C<Composition>.
See L</Composition()> below for the additional semantics associated
with compositions.

=back

The association also creates instances of 
L<DBIx::DataModel::Meta::Path> for representing the 
directional paths between those sources.

Only binary associations can be declared; however, it is possible
to define methods joining three or more tables : see
L</define_navigation_method()>.


=head4 Special semantics for compositions


Compositions are associations with some additional semantics. In UML
class diagrams, compositions are pictured with a black diamond on one
side : this side will be called the I<composite> class, while the
other side will be called the I<component> class. In
C<DBIx::DataModel>, the diamond (the composite class) corresponds to
the C<A> association end, and the component class corresponds to the
C<B> end, so the order is important (while for plain associations the
order makes no difference).

In UML, the intended meaning of a composition is that objects of the
component classes cannot exist outside of their composite class. Within
C<DBIx::DataModel>, the special semantics attached to associations
of kind C<Composition> is :

=over

=item *

the multiplicity must be 1-to-n or 1-to-0..1

=item * 

the C<'B'> end of the association (the "component" part) must not 
be component of another association (it can only be component of one
single composite table).

=item *

this association can be used for auto-expanding the composite object
(i.e. automatically fetching all component parts from the database)
-- see L</"expand()"> and L</"auto_expand()">

=item *

this association can be used for cascaded L<inserts|/"insert()"> like

  $source->insert({
    column1 => $val1,
    ...
    $component_name1 => [{$sub_object1}, ...],
    ...
   })

The main record will be inserted in the composite class, and within
the same transaction, subrecords will be inserted into the 
component classes, with foreign keys automatically filled with
appropriate values.


=item *

this association can be used for cascaded deletes : 
the argument to a L<delete|/"delete()"> may contain lists of component records to
be deleted together with the main record of the composite class.


=back

=head3 define_type()

  $meta_schema->define_type(
     name     => $type_name,
     handlers => {
       $handler_name_1 => sub { ... },
       $handler_name_2 => sub { ... },
       ...
       },
   );

This declares a I<type>, which is just a hashref of handler names and
handler bodies (coderefs). The type can then be applied to some
columns in some tables; this is usually done in the Table declaration
(C<column_types> argument), or can be applied later through the
L</define_column_type> method. Unlike tables or associations,
a type does I<not> create a Perl class nor does it create meta-objects;
it is really just a plain hashref.

Handlers receive the column value through C<< $_[0] >>.
If the value is to be modified (for example for scalar
conversions or for inflating values into Perl objects), 
the result should be put back into C<< $_[0] >>.
In addition to the column value, other info is passed to the
handler :

  $handler_body = sub {
    my ($column_value, $obj, $column_name, $handler_name) = @_;
    my $new_val = $obj->compute_new_val($column_value, ...);
    $column_value = $new_val; # WRONG : will be a no-op
    $_[0] = $new_val;         # OK    : value is converted
  }

The second argument C<< $obj >> is the object from where 
C<< $column_value >> was taken -- most probably an instance 
of a Table or Join class.  Use this if you need to read some contextual
information, but avoid modifying C<< $obj >> : you would most
probably get unexpected results or create undesired side-effects.

Other arguments C<< $column_name >> and
C<< $handler_name >> are obvious.

Handler names C<from_DB> and C<to_DB> have a special
meaning : they are called automatically just after reading data from
the database, or just before writing into the database.
Handler name B<validate> is used by the method
L</"has_invalid_columns()">.

The L<DBIx::DataModel/SYNOPSIS> shows some examples of types :
"Date", "Percent", "Multivalue" or "XML".



=head3 define_join()

lib/DBIx/DataModel/Doc/Reference.pod view on Meta::CPAN

key column(s). The way to retrieve such values depends on 
C<returning_through>: when 'FETCH', it performs an additional 
call to C<< $sth->fetchrow_array >>; when 'INOUT', it binds 
inout parameters into the statement. When setting the database handle
through the L</dbh> method, the C<returning_through> option is automatically
set to 'FETCH' if it is a Pg driver, or automatically set to 'INOUT'
if it is an Oracle driver.

=item *

if a dbh option called C<last_insert_id> is found, this is
taken as a callback function, which gets called as

  $dbh_options{last_insert_id}->($dbh, $table_name, $column_name)

=item *

if dbh options called C<catalog> and/or C<schema> are found,
C<DBIx::DataModel> will call 

  $dbh->last_insert_id($dbh_options{catalog}, $dbh_options{schema},
                       $table_name, $column_name)

=item *

otherwise, C<DBIx::DataModel> will call 

  $dbh->last_insert_id(undef, undef, undef, undef)

=back

=head4 Cascaded insert

If the table is a composite class (see L<Composition()|/"Composition">
above), then the component parts may be supplied within the hashref,
in the form of arrayrefs of sub-hashrefs; then these will be inserted
into the database, at the same time as the main record, with join
values automatically filled in.  For example :

   HR::Employee->insert({firstname  => "Johann Sebastian",  
                         lastname   => "Bach",
                         activities => [{d_begin  => '01.01.1695',
        			         d_end    => '18.07.1750',
	        		         dpt_code => 'CPT'}]});

=head4 Insert options

The C<insert()> call may take a list of B<%options> 
specified at the I<end> of the argument list (notice they are
I<not> given as a hashref, but as a mere hash, or list of pairs).
Currently the only supported option is B<-returning>  :

=over

=item *

if the C<-returning> option is set to an empty hashref, the return
value will be a list of hashrefs (one for each inserted record),
containing the column name(s) and value(s) of the primary key for that
record, and possibly containing subhashes or subarrays for other
records created through cascaded inserts. For example:

  my @result = HR->table('Employee'>
                 ->insert({..., activities => [{...}, ...]},
                          ...,
                          -returning => {});
  my $prim_key_first_emp = $result[0]{emp_id};
  my $prim_key_first_act = $result[0]{activities}[0]{act_id};

=item *

if the C<-returning> option is set to any other value, that value is passed
to L<SQL::Abstract::More/insert> and finally to the SQL level 
(INSERT ... RETURNING ...);  whatever is returned from the 
database for each single record gets flattened into a single
list transmitted back to the caller.

  my @result = $statement->insert({...}, ..., 
                                  -returning => $scalar_or_arrayref);


=item *

if the C<-returning> option is absent, values returned by calls to
L<_singleInsert()|DBIx::DataModel::Doc::Internals/"_singleInsert">
are collected into a flattened
array, and then returned by C<insert()>; usually, these are the
primary keys of the inserted records.  If this array contains several
values, and C<insert()> was called from a scalar context, a warning is
issued.

=back

=head4 Reftype checking

If a record contains columns that are arrayrefs or hashrefs, and 
these are not known as "component parts" (see
L</"Cascaded insert"> above), then a warning is generated
and these columns are automatically removed from the record.

An exception to this rule is when the L<SQL::Abstract|SQL::Abstract>
instance associated with the schema has the option
C<< array_datatypes => 1 >> : in that case, columns with arrayrefs
are passed as-is to the C<SQL::Abstract::More> and C<DBI> layers, under the 
assumption that the DBD driver will take appropriate action on
those datatypes.

Another exception is when the value is of shape
C<< [$orig_value, \%datataype] >>, which is interpreted as a 
value together with an SQL datatype; again this is 
passed to the L<SQL::Abstract::More> layer.
An example is shown in the 
L<cookbook|DBIx::DataModel::Doc::Cookbook/"SQL Types">.



=head2 Bimodal methods (methods that can be invoked both as class and as instance methods)

=head3 primary_key()

  my @primary_key_columns = $class->primary_key;

lib/DBIx/DataModel/Doc/Reference.pod view on Meta::CPAN


The C<update> method only updates the columns received
as arguments : it knows nothing about other columns that may sit
in the database. Therefore if you have two concurrent clients
doing

  (client1)  ...->update($id, {c1 => $v1, c2 => $v2});
  (client2)  ...->update($id, {c3 => $v3, c4 => $v4, c5 => $v5});

the final state of record C<$id> in the database is guaranteed to
reflect changes from both clients, because the sets of updated columns
C<('c1', 'c2')> and C<('c3', 'c4', 'c5')>  are disjoint.

Like for inserts, columns with arrayrefs or hashrefs
are automatically removed from the update list (with a warning),
except some special cases as described above for C<insert()>.

In all syntaxes described above, the return value from the C<update()>
method is the number of records updated in the database.


=head3 delete()

  # class method calls
  $source_class->delete(-where => \%condition);
  $source_class->delete({col1 => $val1, ...});
  $source_class->delete(@primary_key);

  # or instance method call
  $source_instance->delete();

Generates a request to the database to delete one or several
records.


As a class method call, the API for this method accepts 
three different syntaxes :


=over 

=item *

the syntax with the C<-where> keyword
closely reflects the SQL syntax of shape 

  DELETE FROM table WHERE ...

This is mostly used for deleting several records simultaneously (bulk
delete). 

=item * 

the second syntax is used for deleting a single
record. A C<-where> clause will be automatically generated
by extracting the primary key column(s) from the record.

If the source is a composite class (see
L<Composition()|/"Composition"> above), and if the record in memory contains
references to lists of component parts, then those will be recursively
deleted together with the main object (cascaded delete). However, if
there are other component parts in the database, not referenced in the
object hashref, then those will not be automatically deleted : in other
words, the C<delete> method does not go by itself to the database to
find all component parts (this is the job of the client
code, or sometimes of the database itself).

=item * 

the third syntax with C<< @primary_key >> is an alternate way to
supply the values for the primary key; it may be more convenient
because you don't need to repeat the name of primary key columns.
Note that C<< $statement->delete(11, 22) >>
does not mean "delete records with keys 11 and 22", but rather
"delete record having primary key (11, 22)"; in other words,
with this syntax you only delete one record at a time. 
With this syntax no cascaded delete
is performed.

=back


When used as an instance method, the only syntax is to call
the C<delete()> method without any arguments :

  $source_instance->delete();

In all syntaxes described above, the return value from the C<delete()>
method is the number of records deleted in the database.



=head1 META-SCHEMA NAVIGATION

=head2 Meta-schema methods

=head3 tables()

  my @meta_tables  = $meta_schema->tables;

Returns all L<DBIx::DataModel::Meta::Source::Table> instances
declared in this C<$meta_schema>.

=head3 Meta::Schema::table()

  my $meta_table   = $meta_schema->table($table_name);

Returns the single instance of L<DBIx::DataModel::Meta::Source::Table> 
with name C<$table_name>, or C<undef>.

=head3 Meta::Schema::db_table()

  my $meta_table   = $meta_schema->db_table($db_table_name);

Returns the single instance of L<DBIx::DataModel::Meta::Source::Table> 
with I<database> name C<$db_table_name>, or C<undef>.


=head3 associations()

  my @associations = $meta_schema->associations;

Returns all L<DBIx::DataModel::Meta::Association> instances
declared in this C<$meta_schema>.

=head3 association()

  my $association  = $meta_schema->associations($association_name);

Returns the single instance of L<DBIx::DataModel::Meta::Source::Association> 
with name C<$association_name>, or C<undef>.


=head3 types()

  my @types        = $meta_schema->types;

( run in 0.710 second using v1.01-cache-2.11-cpan-39bf76dae61 )