192 lines
4.9 KiB
Plaintext
192 lines
4.9 KiB
Plaintext
=head1 NAME
|
|
|
|
DBD::File::HowTo - Guide to create DBD::File based driver
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
perldoc DBD::File::HowTo
|
|
perldoc DBI
|
|
perldoc DBI::DBD
|
|
perldoc DBD::File::Developers
|
|
perldoc DBI::DBD::SqlEngine::Developers
|
|
perldoc DBI::DBD::SqlEngine
|
|
perldoc SQL::Eval
|
|
perldoc DBI::DBD::SqlEngine::HowTo
|
|
perldoc SQL::Statement::Embed
|
|
perldoc DBD::File
|
|
perldoc DBD::File::HowTo
|
|
perldoc DBD::File::Developers
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This document provides a step-by-step guide, how to create a new
|
|
C<DBD::File> based DBD. It expects that you carefully read the L<DBI>
|
|
documentation and that you're familiar with L<DBI::DBD> and had read and
|
|
understood L<DBD::ExampleP>.
|
|
|
|
This document addresses experienced developers who are really sure that
|
|
they need to invest time when writing a new DBI Driver. Writing a DBI
|
|
Driver is neither a weekend project nor an easy job for hobby coders
|
|
after work. Expect one or two man-month of time for the first start.
|
|
|
|
Those who are still reading, should be able to sing the rules of
|
|
L<DBI::DBD/CREATING A NEW DRIVER>.
|
|
|
|
Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read
|
|
L<DBI::DBD::SqlEngine::HowTo> before continuing here.
|
|
|
|
=head1 CREATING DRIVER CLASSES
|
|
|
|
Do you have an entry in DBI's DBD registry? For this guide, a prefix of
|
|
C<foo_> is assumed.
|
|
|
|
=head2 Sample Skeleton
|
|
|
|
package DBD::Foo;
|
|
|
|
use strict;
|
|
use warnings;
|
|
use vars qw(@ISA $VERSION);
|
|
use base qw(DBD::File);
|
|
|
|
use DBI ();
|
|
|
|
$VERSION = "0.001";
|
|
|
|
package DBD::Foo::dr;
|
|
|
|
use vars qw(@ISA $imp_data_size);
|
|
|
|
@ISA = qw(DBD::File::dr);
|
|
$imp_data_size = 0;
|
|
|
|
package DBD::Foo::db;
|
|
|
|
use vars qw(@ISA $imp_data_size);
|
|
|
|
@ISA = qw(DBD::File::db);
|
|
$imp_data_size = 0;
|
|
|
|
package DBD::Foo::st;
|
|
|
|
use vars qw(@ISA $imp_data_size);
|
|
|
|
@ISA = qw(DBD::File::st);
|
|
$imp_data_size = 0;
|
|
|
|
package DBD::Foo::Statement;
|
|
|
|
use vars qw(@ISA);
|
|
|
|
@ISA = qw(DBD::File::Statement);
|
|
|
|
package DBD::Foo::Table;
|
|
|
|
use vars qw(@ISA);
|
|
|
|
@ISA = qw(DBD::File::Table);
|
|
|
|
1;
|
|
|
|
Tiny, eh? And all you have now is a DBD named foo which will be able to
|
|
deal with temporary tables, as long as you use L<SQL::Statement>. In
|
|
L<DBI::SQL::Nano> environments, this DBD can do nothing.
|
|
|
|
=head2 Start over
|
|
|
|
Based on L<DBI::DBD::SqlEngine::HowTo>, we're now having a driver which
|
|
could do basic things. Of course, it should now derive from DBD::File
|
|
instead of DBI::DBD::SqlEngine, shouldn't it?
|
|
|
|
DBD::File extends DBI::DBD::SqlEngine to deal with any kind of files.
|
|
In principle, the only extensions required are to the table class:
|
|
|
|
package DBD::Foo::Table;
|
|
|
|
sub bootstrap_table_meta
|
|
{
|
|
my ( $self, $dbh, $meta, $table ) = @_;
|
|
|
|
# initialize all $meta attributes which might be relevant for
|
|
# file2table
|
|
|
|
return $self->SUPER::bootstrap_table_meta($dbh, $meta, $table);
|
|
}
|
|
|
|
sub init_table_meta
|
|
{
|
|
my ( $self, $dbh, $meta, $table ) = @_;
|
|
|
|
# called after $meta contains the results from file2table
|
|
# initialize all missing $meta attributes
|
|
|
|
$self->SUPER::init_table_meta( $dbh, $meta, $table );
|
|
}
|
|
|
|
In case C<DBD::File::Table::open_file> doesn't open the files as the driver
|
|
needs that, override it!
|
|
|
|
sub open_file
|
|
{
|
|
my ( $self, $meta, $attrs, $flags ) = @_;
|
|
# ensure that $meta->{f_dontopen} is set
|
|
$self->SUPER::open_file( $meta, $attrs, $flags );
|
|
# now do what ever needs to be done
|
|
}
|
|
|
|
Combined with the methods implemented using the L<SQL::Statement::Embed>
|
|
guide, the table is full working and you could try a start over.
|
|
|
|
=head2 User comfort
|
|
|
|
C<DBD::File> since C<0.39> consolidates all persistent meta data of a table
|
|
into a single structure stored in C<< $dbh->{f_meta} >>. With C<DBD::File>
|
|
version C<0.41> and C<DBI::DBD::SqlEngine> version C<0.05>, this
|
|
consolidation moves to L<DBI::DBD::SqlEngine>. It's still the
|
|
C<< $dbh->{$drv_prefix . "_meta"} >> attribute which cares, so what you
|
|
learned at this place before, is still valid.
|
|
|
|
sub init_valid_attributes
|
|
{
|
|
my $dbh = $_[0];
|
|
|
|
$dbh->SUPER::init_valid_attributes ();
|
|
|
|
$dbh->{foo_valid_attrs} = { ... };
|
|
$dbh->{foo_readonly_attrs} = { ... };
|
|
|
|
$dbh->{foo_meta} = "foo_tables";
|
|
|
|
return $dbh;
|
|
}
|
|
|
|
See updates at L<DBI::DBD::SqlEngine::HowTo/User comfort>.
|
|
|
|
=head2 Testing
|
|
|
|
Now you should have your own DBD::File based driver. Was easy, wasn't it?
|
|
But does it work well? Prove it by writing tests and remember to use
|
|
dbd_edit_mm_attribs from L<DBI::DBD> to ensure testing even rare cases.
|
|
|
|
=head1 AUTHOR
|
|
|
|
This guide is written by Jens Rehsack. DBD::File is written by Jochen
|
|
Wiedmann and Jeff Zucker.
|
|
|
|
The module DBD::File is currently maintained by
|
|
|
|
H.Merijn Brand < h.m.brand at xs4all.nl > and
|
|
Jens Rehsack < rehsack at googlemail.com >
|
|
|
|
=head1 COPYRIGHT AND LICENSE
|
|
|
|
Copyright (C) 2010 by H.Merijn Brand & Jens Rehsack
|
|
|
|
All rights reserved.
|
|
|
|
You may freely distribute and/or modify this module under the terms of
|
|
either the GNU General Public License (GPL) or the Artistic License, as
|
|
specified in the Perl README file.
|
|
|
|
=cut
|