[svn:dbi] r15539 - dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine

Author: REHSACK
Date: Fri Dec 21 07:02:54 2012
New Revision: 15539

Modified:
   dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod

Log:
updating doc - primarily for ::dr::connect

Modified: dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod
==============================================================================
--- dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod	(original)
+++ dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine/Developers.pod	Fri Dec 21 07:02:54 2012
@@ -121,12 +121,13 @@
       ...
   }
 
-Similar for C<< data_sources () >> and C<< disconnect_all() >>.
+Similar for C<data_sources ()> and C<disconnect_all()>.
 
-Pure Perl DBI drivers derived from DBI::DBD::SqlEngine do not usually need to
-override any of the methods provided through the DBD::XXX::dr package
-however if you need additional initialization in the connect method
-you may need to.
+Pure Perl DBI drivers derived from DBI::DBD::SqlEngine usually don't need to
+override any of the methods provided through the DBD::XXX::dr package.
+However if you need additional initialization not fitting in
+C<init_valid_attributes()> and C<init_default_attributes()> of you're ::db
+class, the connect method might be the final place to be modified.
 
 =item DBI::DBD::SqlEngine::db
 
@@ -141,12 +142,51 @@
 write DBI drivers based on DBI::DBD::SqlEngine need to override the methods
 C<< set_versions >> and C<< init_valid_attributes >>.
 
+=item DBI::DBD::SqlEngine::TieMeta;
+
+Provides the tie-magic for C<< $dbh->{$drv_pfx . "_meta"} >>. Routes
+C<STORE> through C<< $drv->set_sql_engine_meta() >> and C<FETCH> through
+C<< $drv->get_sql_engine_meta() >>. C<DELETE> is not supported, you have
+to execute a C<DROP TABLE> statement, where applicable.
+
+=item DBI::DBD::SqlEngine::TieTables;
+
+Provides the tie-magic for tables in C<< $dbh->{$drv_pfx . "_meta"} >>.
+Routes C<STORE> though C<< $tblClass->set_table_meta_attr() >> and C<FETCH>
+though C<< $tblClass->get_table_meta_attr() >>. C<DELETE> removes an
+attribute from the I<meta object> retrieved by
+C<< $tblClass->get_table_meta() >>.
+
 =item DBI::DBD::SqlEngine::st
 
 Contains the methods to deal with prepared statement handles. e.g.,
 
   $sth->execute () or die $sth->errstr;
 
+=item DBI::DBD::SqlEngine::TableSource;
+
+Base class for 3rd party table sources:
+
+  $dbh->{sql_table_source} = "DBD::Foo::TableSource";
+
+=item DBI::DBD::SqlEngine::DataSource;
+
+Base class for 3rd party data sources:
+
+  $dbh->{sql_data_source} = "DBD::Foo::DataSource";
+
+=item DBI::DBD::SqlEngine::Statement;
+
+Base class for derived drivers statement engine. Implements C<open_table>.
+
+=item DBI::DBD::SqlEngine::Table;
+
+Contains tailoring between SQL eningine's requirements and
+C<DBI::DBD::SqlEngine> magic for finding the right tables and storage.
+Builds bridges between C<sql_meta> handling of C<DBI::DBD::SqlEngine::db>,
+table initialization for SQL engines and I<meta object>'s attribute
+management for derived drivers.
+
 =back
 
 =head2 DBI::DBD::SqlEngine
@@ -189,6 +229,60 @@
   $DBD::XXX::dr::data_sources_attr = undef;
   $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
 
+=head3 Methods provided by C<< DBI::DBD::SqlEngine::dr >>:
+
+=over 4
+
+=item connect
+
+Supervises the driver bootstrap when calling
+
+  DBI->connect( "dbi:Foo", , , { ... } );
+
+First it instantiates a new driver using C<DBI::_new_dbh>. After that,
+initial bootstrap of the newly instantiated driver is done by
+
+  $dbh->func( 0, "init_default_attributes" );
+
+The first argument (C<0>) signals that this is the very first call to
+C<init_default_attributes>. Modern drivers understands that and doing
+early stage setup here after calling
+
+  package DBD::Foo::db;
+  our @DBD::Foo::db::ISA = qw(DBI::DBD::SqlEngine::db);
+  
+  sub init_default_attributes
+  {
+    my ($dbh, $phase) = @_;
+    $dbh->SUPER::init_default_attributes($phase);
+    ...; # own setup code, maybe separated by phases
+  }
+
+When the C<$phase> argument is passed down until
+C<DBI::DBD::SqlEngine::db::init_default_attributes>, C<connect()> recognizes
+a I<modern> driver and initializes the attributes from I<DSN> and I<$attr>
+arguments passed via C<< DBI->connect( $dsn, $user, $pass, \%attr ) >>.
+
+At the end of the attribute initialization after I<phase 0>, C<connect()>
+invoked C<init_default_attributes> again for I<phase 1>:
+
+  $dbh->func( 1, "init_default_attributes" );
+
+=item data_sources
+
+Returns a list of I<DSN>'s using the C<data_sources> method of the
+class specified in C<< $dbh->{sql_table_source} >> or via C<\%attr>:
+
+  @ary = DBI->data_sources($driver);
+  @ary = DBI->data_sources($driver, \%attr);
+
+=item disconnect_all
+
+C<DBI::DBD::SqlEngine> doesn't have an overall driver cache, so nothing
+happens here at all.
+
+=back
+
 =head2 DBI::DBD::SqlEngine::db
 
 This package defines the database methods, which are called via the DBI

• [svn:dbi] r15539 - dbi/branches/sqlengine/lib/DBI/DBD/SqlEngine by REHSACK