Here's something I sketched out for Harry when we started.
Seems worth repeating to the list.
This is where we're aiming to get to.
Tim
=head1 Parrot DBD Design Notes
These notes for a rough sketch of a class hirearchy based on
that use for the Perl DBI drivers: the DBD's.
=head1 Handle Objects
There are three kinds of handles: Driver, Database, and Statement.
These are often refered to as drh, dbh, and sth respectively.
=head1 Classes
A driver implements a class for each type of handle.
The name of the classes are DBD::<foo>::dr, DBD::<foo>::db,
and DBD::<foo>::st where <foo> if the name of the driver,
e.g., DBD::<foo>::dr.
The DBD library provides base classes for those driver classes.
The hierarchy looks like this:
DBD::_::common
DBD::_::dr
DBD::<foo>::dr
DBD::<bar>::dr
DBD::_::db
DBD::<foo>::db
DBD::<bar>::db
DBD::_::st
DBD::<foo>::st
DBD::<bar>::st
See %DBI::DBI_methods and @Common_IF in DBI.pm
=head2 DBD::_::common class
=item err()
Returns scalar (typically int but can be string) or undef
=item errstr()
Returns scalar (typically string) or undef
=item set_err(err, errstr)
Sets the err and errstr values of the handle
=item new_child(attr)
Create a new handle in the appropriate child class of the calling handle.
The new class is determined by changing the last component of the
calling handles class name. If the last component of the class
name is "dr" then the new class ends in "db", it's it's "db" then
the new class ends in "st". Anything else is an error.
The attr param is ignored for now.
=head2 DBD::_::dr class
=item connect(dsn, user, pass, attr)
Effectively does
$dbh = $drh->new_child(attr) or return;
$dbh->connect(dsn, user, pass) or return;
return $dbh
=head2 DBD::_::db class
=item connect(dsn, user, pass) *DRIVER*
Connects to the database and stores the underlying connection in
the handle object.
=item prepare(statement, attr)
Effectively does
$sth = $dbh->new_child(attr) or return;
$sth->prepare(statement, attr) or return;
return $sth
=item do(statement, attr)
Effectively does
$sth = $dbh->prepare(statement, attr) or return;
$sth->execute() or return;
my $rows = $sth->rows;
$sth->some-method-that-destroys-the-handle
return $rows
=head2 DBD::_::st class
=item prepare(statement, attr) *DRIVER*
Prepares the statement for execution and stores the underlying
information in the handle object. (Initially, and for some drivers
always, this can simply store a copy of the statement string in
handle and postpone any real work till execute() is called.)
If it's a select statement it sets NUM_OF_FIELDS attribute if it can.
=item execute(statement) *DRIVER*
Executes the prepared statement.
If it's a select statement it sets NUM_OF_FIELDS attribute if it
wasn't set by prepare().
Returns an integer row count (which may be meaningless for stetelct
statements)
=item get_row_array()
If the handle object does not already have a row buffer then an
array of NUM_OF_FIELDS elements is allocated.
Increments the row count in the handle.
Returns the array. (The same one on each call).
=item fetch() *DRIVER*
Fetches the next row from the database.
If there are no more rows
then calls finish() and return undef.
If there is a row then it calls get_row_array() and
sets each element of the array to the corresponding field value.
Returns the array.
=item finish()
Discards any pending results from the select statement.
=head1 Driver Summary
A driver only has to implement these few methods:
DBD::<foo>::db::connect()
DBD::<foo>::st::prepare()
DBD::<foo>::st::execute()
DBD::<foo>::st::fetch()
to get something working!
=head1 Leading Issues
Attributes vs properties?
Methods to set/get attribute values.
(Driver needs to be able to bypass the methods in some cases)
Define basic set of attributes for each class
Define object 'structure': what is a handle made of?
(e.g., an Array with elements assigned specific uses?)
Define and document parameter and return types
(method prototypes)
=cut
