=head1 NAME

DBIx::DataModel::Doc::Internals - Description of the internal structure


=head1 DOCUMENTATION CONTEXT

This chapter is part of the C<DBIx::DataModel> manual.


=over

=item * 

L<SYNOPSIS AND DESCRIPTION|DBIx::DataModel>

=item * 

L<DESIGN|DBIx::DataModel::Doc::Design>

=item * 

L<QUICKSTART|DBIx::DataModel::Doc::Quickstart>

=item *

L<REFERENCE|DBIx::DataModel::Doc::Reference>

=item *

L<MISC|DBIx::DataModel::Doc::Misc>

=item *

INTERNALS

=item *

L<GLOSSARY|DBIx::DataModel::Doc::Glossary>

=back


This chapter documents some details that normally should not be
relevant to clients; you only want to read about them if you
intend to extend the framework.



=head1 PRIVATE METHODS

=head2 _setClassData

  DBIx::DataModel::Base->_setClassData($subclass, $data_ref);


=head2 _createPackage

  DBIx::DataModel::Schema->_createPackage($pckName, $isa_arrayref);

Creates a new Perl package of name C<$pckName> that inherits from
C<@$isa_arrayref>. Raises an exception if the package name already
exists.

=head2 _defineMethod

  DBIx::DataModel::Schema
    ->_defineMethod($pckName, $methName, $coderef, $silent);

Defines a new method in package C<$pckName>, bound to C<$coderef>;
or undefines a method if C<$coderef> is C<undef>.
Raises an exception if the method name already
exists in that package.
Generates a warning if the method name already
exists in a parent class, unless the optional C<$silent> 
argument is true.

=head2 _rawInsert

  $obj->_rawInsert(%options);

Internal implementation for insertions into the database :
takes keys and values within C<%$obj>, generates SQL for 
insertion of those values into C<< $obj->dbTable >>,
and executes it. Never called directly, but used by the protected method
L<_singleInsert|DBIx::DataModel::Doc::Reference/"_singleInsert">.

The optional C<%options> argument can contain one single key : C<-returning>.
If that option is present, and the value is either a scalar or an arrayref, 
then it will be passed as an option to L<SQL::Abstract/insert>, and the
returned value(s) will be fetched from the sth and returned to the caller.


=head1 "PROTECTED" METHODS

=head2 _singleInsert

  $obj->_singleInsert(%options);

Implementation for inserting a record into the
database; should never be called directly, but is used as 
a backend by the 
L<insert|DBIx::DataModel::Doc::Reference/"insert">
method. 

This method receives an object blessed into some table class; the
object hash should only contain keys and values to be directly
inserted into the database, i.e. the C<noUpdateColumns> and all
references to foreign objects should have been removed (
normally the
L<insert|DBIx::DataModel::Doc::Reference/"insert">
method has already done that job).  
The C<_singleInsert> method calls L</"_rawInsert">
for performing the database update, and then makes
sure that the object contains its own key, calling
DBI's L<last_insert_id()|DBI/last_insert_id> if necessary,
as explained in the L<insert|DBIx::DataModel::Doc::Reference/"insert">
documentation.

You may redeclare C<_singleInsert> in your own table classes,
for example if you need to compute a key by other means, like
constructing it from other fields, or generating it from
a random number. 

The return value from C<_singleInsert> depends on C<%options> :

=over

=item *

if C<< $options{-returning} >> is a scalar or arrayref,
that option is passed to C<_rowInsert>,  then 
to L<SQL::Abstract/insert> and finally to the SQL level 
(INSERT ... RETURNING ...);  whatever is returned from the 
database gets transmitted back to the caller.

=item *

if C<< $options{-returning} >> is a hashref, the 
return value is also a hashref, containing the column
name(s) and value(s) of the primary key for that record

=item *

if C<< $options{-returning} >> is absent, the
return value is the list of values of the primary key
for that record.

=back



