/ 
DBI-1.622
River stage four • 958 direct dependents • 2123 total dependents
/ DBD::File::HowTo

NAME

DBD::File::HowTo - Guide to create DBD::File based driver

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

DESCRIPTION

This document provides a step-by-step guide, how to create a new DBD::File based DBD. It expects that you carefully read the DBI documentation and that you're familiar with DBI::DBD and had read and understood 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 "CREATING A NEW DRIVER" in DBI::DBD.

Of course, DBD::File is a DBI::DBD::SqlEngine and you surely read DBI::DBD::SqlEngine::HowTo before continuing here.

CREATING DRIVER CLASSES

Do you have an entry in DBI's DBD registry? For this guide, a prefix of foo_ is assumed.

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 is able to deal with temporary tables, as long as you use SQL::Statement. In DBI::SQL::Nano environments, this DBD can do nothing.

Start over

Based on 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 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 SQL::Statement::Embed guide, the table is full working and you could try a start over.

User comfort

DBD::File since 0.39 consolidates all persistent meta data of a table into a single structure stored in $dbh->{f_meta}. While DBD::File provides only readonly access to this structure, modifications are still allowed.

Primarily DBD::File provides access via setters get_file_meta, set_file_meta and clear_file_meta. Those methods are easily accessible by the users via the $dbh->func () interface provided by DBI. Well, many users don't feel comfortize when calling

# don't require extension for tables cars
$dbh->func ("cars", "f_ext", ".csv", "set_file_meta");

DBD::File will inject a method into your driver to increase the user comfort to allow:

# don't require extension for tables cars
$dbh->foo_set_meta ("cars", "f_ext", ".csv");

Better, but here and there users likes to do:

# don't require extension for tables cars
$dbh->{foo_tables}->{cars}->{f_ext} = ".csv";

This interface is provided when derived DBD's define following in init_valid_attributes (please compare carefully with the example in DBI::DBD::SqlEngine::HowTo):

    sub init_valid_attributes
    {
	my $dbh = $_[0];

	$dbh->SUPER::init_valid_attributes ();

	$dbh->{foo_valid_attrs} = {
	    foo_version 	=> 1,	# contains version of this driver
	    foo_valid_attrs	=> 1,	# contains the valid attributes of foo drivers
	    foo_readonly_attrs	=> 1,	# contains immutable attributes of foo drivers
	    foo_bar		=> 1,	# contains the bar attribute
	    foo_baz		=> 1,   # contains the baz attribute
	    foo_manager		=> 1,	# contains the manager of the driver instance
	    foo_manager_type	=> 1,	# contains the manager class of the driver instance
	    foo_meta            => 1,   # contains the public interface to modify table meta attributes
	};
	$dbh->{foo_readonly_attrs} = {
	    foo_version 	=> 1,	# ensure no-one modifies the driver version
	    foo_valid_attrs	=> 1,	# do not permit to add more valid attributes ...
	    foo_readonly_attrs	=> 1,	# ... or make the immutable mutable
	    foo_manager		=> 1,	# manager is set internally only
	    foo_meta            => 1,   # ensure public interface to modify table meta attributes are immutable
	};

	$dbh->{foo_meta} = "foo_tables";

	return $dbh;
    }

This provides a tied hash in $dbh->{foo_tables} and a tied hash for each table's meta data in $dbh->{foo_tables}->{$table_name}. Modifications on the table meta attributes are done using the table methods:

sub get_table_meta_attr { ... }
sub set_table_meta_attr { ... }

Both methods can adjust the attribute name for compatibility reasons, e.g. when former versions of the DBD allowed different names to be used for the same flag:

    my %compat_map = (
		       abc => 'foo_abc',
		       xyz => 'foo_xyz',
		     );
    __PACKAGE__->register_compat_map( \%compat_map );

If any user modification on a meta attribute needs reinitialization of the meta structure (in case of DBD::File these are the attributes f_file, f_dir, f_ext and f_lockfile), inform DBD::File by doing

    my %reset_on_modify = (
			    foo_xyz => "foo_bar",
			    foo_abc => "foo_bar",
			  );
    __PACKAGE__->register_reset_on_modify( \%reset_on_modify );

The next access to the table meta data will force DBD::File to re-do the entire meta initialization process.

Any further action which needs to be taken can handled in table_meta_attr_changed:

    sub table_meta_attr_changed
    {
	my ($class, $meta, $attrib, $value) = @_;
	...
	$class->SUPER::table_meta_attr_changed ($meta, $attrib, $value);
    }

This is done before the new value is set in $meta, so the attribute changed handler can act depending on the old value.

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 DBI::DBD to ensure testing even rare cases.

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 >

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.