=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);

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.

=head2 _rawInsert

  $obj->_rawInsert;

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">.


=head1 "PROTECTED" METHODS

=head2 _singleInsert

  $obj->_singleInsert;

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 already (this
is the job of the 
L<insert|DBIx::DataModel::Doc::Reference/"insert">
method).  The method calls
L<_rawInsert|DBIx::DataModel::Doc::Reference/"_rawInsert">
for performing the database update, and then makes
sure that the object contains its own key (if not supplied by the
client code, for example when keys are auto-generated by the
database).

In the default implementation, getting the key is done by calling DBI's
L<last_insert_id()|DBI/last_insert_id> whenever necessary. This may or
may not be meaningful, depending on your database driver.  The four
arguments required by C<last_insert_id> are
supplied as follows : catalog and schema names are taken from options
given to C<< Schema->dbh(...) >> (or C<undef> otherwise), table and
column names are taken from the object's database table and 
primary key, as declared in C<< Schema->Table(...) >>.

You may redeclare C<_singleInsert> in your own table classes,
for example if you need to compute a key, or construct it
from other fields. 

The scalar value returned by the method
will in turn be returned by the 
L<insert|DBIx::DataModel::Doc::Reference/"insert">
method; usually this value if the primary key, if that key is on 
one single column.