[svn:dbi] r14092 - dbi/trunk/lib/DBD/File

Author: REHSACK
Date: Tue Jun  1 13:14:34 2010
New Revision: 14092

Modified:
   dbi/trunk/lib/DBD/File/Developers.pod

Log:
Adding more method description to the DBD::File developers
documentation (some more completition needed).


Modified: dbi/trunk/lib/DBD/File/Developers.pod
==============================================================================
--- dbi/trunk/lib/DBD/File/Developers.pod	(original)
+++ dbi/trunk/lib/DBD/File/Developers.pod	Tue Jun  1 13:14:34 2010
@@ -217,20 +217,51 @@
 
 =item bind_param
 
+Common routine to bind placeholders to a statement for execution. It's
+dangerous to override this method without detailed knowledge about the
+DBD::File internal storage structure.
+
 =item execute
 
+Executes previously prepared statements (with placeholders, if any).
+
 =item finish
 
+Finishes a statement handle, discards all buffered results. The prepared
+statement isn't discards to allow the statement can be executed multiple
+times.
+
 =item fetch
 
+Fetches next row from last execute results. This method may be rewritten
+in a later version and if it's overwritten in a derived class, the derived
+implementation shouldn't rely on the storage details.
+
 =item fetchrow_arrayref
 
+Alias for C<< fetch >>.
+
 =item FETCH
 
+Fetches statement handle attributes. Supported attributes (for full overview
+see L<DBI/Statement Handle Attributes>) are C<< NAME >> and C<< NULLABLE >>.
+Each column is returned being C<< NULLABLE >> which might be wrong depending
+on derived backend storage. If the statement handle has private attributes,
+they can be fetched using this method, too. B<Note> that statement attributes
+are not associated to any table used in this statement.
+
+This method usually requires being extended in a derived implementation.
+See L<DBD::CSV> or L<DBD::DBM> for some example.
+
 =item STORE
 
+Allowes storing of statement private attributes.
+
 =item rows
 
+Returns the number of rows affected by the last execute. This method might
+return C<< undef >>.
+
 =back
 
 =head2 DBD::File::Statement
@@ -241,6 +272,28 @@
 
 =item open_table
 
+Implements the open_table method required by L<SQL::Statement> and
+L<DBI::SQL::Nano>. All real action for opening the file(s) belonging to the
+table is handled and parametrized in DBD::File::Table. Unless you intend
+to add anything to the following implementation, an empty DBD::XXX::Statement
+package satisfies DBD::File.
+
+  sub open_table ($$$$$)
+  {
+      my ($self, $data, $table, $createMode, $lockMode) = @_;
+
+      my $class = ref $self;
+      $class =~ s/::Statement/::Table/;
+
+      my $flags = {
+  	  createMode	=> $createMode,
+	  lockMode	=> $lockMode,
+	  };
+      $self->{command} eq "DROP" and $flags->{dropMode} = 1;
+
+      return $class->new ($data, { table => $table }, $flags);
+      } # open_table
+
 =back
 
 =head2 DBD::File::Table
@@ -252,12 +305,42 @@
 
 =item file2table
 
+This method tries to match between a file name and the fitting table name.
+It's called with a rudimentarily filled meta structure for the resulting
+table containg at least following attributes: C<< f_ext >>, C<< f_dir >>,
+C<< f_lockfile >> and C<< sql_identifier_case >>.
+
+It fills following attributes in the meta structure: C<< f_fqfn >>,
+C<< f_fqbn >>, C<< f_fqln >> and C<< table_name >> if the mapping job could
+be finished successfully. The table name is returned in this case - but
+I<undef> otherwise.
+
 =item bootstrap_table_meta
 
+Initializes a table meta structure rudimentarily. Can be safely overwritten
+in derived classed, as long as the C<< SUPER >> method is called at the end
+of the overwritten method.
+
+It copies following attributes from the database into the table meta data
+C<< f_dir >>, C<< f_ext >>, C<< f_encoding >>, C<< f_lock >>, C<< f_schema >>,
+C<< f_lockfile >> and C<< sql_identifier_case >> and make them sticky to the
+table this way.
+
+This method is called before it's tried to map between file name and table
+name to ensure right directory, extension etc. is used.
+
 =item init_table_meta
 
+Initializes more attributes of the table meta data - usually more expensive
+ones (e.g. those which requires class instantiations) - when the file name
+and the table name could mapped.
+
 =item get_table_meta
 
+Delivers the table meta data. If there are none for the required table, it's
+tried to initializes new ones. When it fails, nothing is returned. On
+success, the name of the table and the meta data structure is returned.
+
 =item open_file
 
 =item new