package DBD::myDriver;
use base qw( DBD::File );
sub driver
{
...
my $drh = $proto->SUPER::driver ($attr);
...
return $drh->{class};
}
sub CLONE { ... }
package DBD::myDriver::dr;
@ISA = qw( DBD::File::dr );
sub data_sources { ... }
...
package DBD::myDriver::db;
@ISA = qw( DBD::File::db );
sub init_valid_attributes { ... }
sub init_default_attributes { ... }
sub set_versions { ... }
sub validate_STORE_attr { my ($dbh, $attrib, $value) = @_; ... }
sub validate_FETCH_attr { my ($dbh, $attrib) = @_; ... }
sub get_myd_versions { ... }
package DBD::myDriver::st;
@ISA = qw( DBD::File::st );
sub FETCH { ... }
sub STORE { ... }
package DBD::myDriver::Statement;
@ISA = qw( DBD::File::Statement );
package DBD::myDriver::Table;
@ISA = qw( DBD::File::Table );
my %reset_on_modify = (
myd_abc => "myd_foo",
myd_mno => "myd_bar",
);
__PACKAGE__->register_reset_on_modify (\%reset_on_modify);
my %compat_map = (
abc => 'foo_abc',
xyz => 'foo_xyz',
);
__PACKAGE__->register_compat_map (\%compat_map);
sub bootstrap_table_meta { ... }
sub init_table_meta { ... }
sub table_meta_attr_changed { ... }
sub open_data { ... }
sub fetch_row { ... }
sub push_row { ... }
sub push_names { ... }
# optimize the SQL engine by add one or more of
sub update_current_row { ... }
# or
sub update_specific_row { ... }
# or
sub update_one_row { ... }
# or
sub insert_new_row { ... }
# or
sub delete_current_row { ... }
# or
sub delete_one_row { ... }
DBI->connect ('DBI:DBM:', undef, undef, {})
# invokes
package DBD::DBM::dr;
@DBD::DBM::dr::ISA = qw( DBD::File::dr );
sub connect ($$;$$$)
{
...
}
Similar for "data_sources" and "disconnect_all".
Pure Perl DBI drivers derived from DBD::File 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.
$sth = $dbh->prepare ("select * from foo");
# returns the f_encoding setting for table foo
$dbh->csv_get_meta ("foo", "f_encoding");
DBD::File provides the typical methods required here. Developers who write DBI drivers based on DBD::File need to override the methods "set_versions" and "init_valid_attributes".
$sth->execute () or die $sth->errstr;
package DBD::DBM;
use base qw( DBD::File );
sub driver
{
my ($class, $attr) = @_;
...
my $drh = $class->SUPER::driver ($attr);
...
return $drh;
}
It is not necessary to implement your own driver method as long as additional initialization (e.g. installing more private driver methods) is not required. You do not need to call "setup_driver" as DBD::File takes care of it.
DBD::File based DBI drivers usually do not need to implement anything here, it is enough to do the basic initialization:
package DBD:XXX::dr; @DBD::XXX::dr::ISA = qw (DBD::File::dr); $DBD::XXX::dr::imp_data_size = 0; $DBD::XXX::dr::data_sources_attr = undef; $DBD::XXX::ATTRIBUTION = "DBD::XXX $DBD::XXX::VERSION by Hans Mustermann";
Methods provided by DBD::File:
The driver prefix is extracted from the attribute name and verified against "$dbh->{$drv_prefix . "valid_attrs"}" (when it exists). If the requested attribute value is not listed as a valid attribute, this method croaks. If the attribute is valid and readonly (listed in "$dbh->{ $drv_prefix . "readonly_attrs" }" when it exists), a real copy of the attribute value is returned. So it's not possible to modify "f_valid_attrs" from outside of DBD::File::db or a derived class.
An example of a valid attributes list can be found in "DBD::File::db::init_valid_attributes".
This method is called at the begin of the "connect ()" phase.
When overriding this method, do not forget to invoke the superior one.
"DBD::File::db::init_valid_attributes" initializes the attributes "f_valid_attrs" and "f_readonly_attrs".
When overriding this method, do not forget to invoke the superior one, preferably before doing anything else. Compatibility table attribute access must be initialized here to allow DBD::File to instantiate the map tie:
# for DBD::CSV
$dbh->{csv_meta} = "csv_tables";
# for DBD::DBM
$dbh->{dbm_meta} = "dbm_tables";
# for DBD::AnyData
$dbh->{ad_meta} = "ad_tables";
"DBD::File::db::init_default_attributes" initializes the attributes "f_dir", "f_meta", "f_meta_map", "f_version".
When the derived implementor class provides the attribute to validate attributes (e.g. "$dbh->{dbm_valid_attrs} = {...};") or the attribute containing the immutable attributes (e.g. "$dbh->{dbm_readonly_attrs} = {...};"), the attributes "drv_valid_attrs", "drv_readonly_attrs", "drv_version" and "drv_meta" are added (when available) to the list of valid and immutable attributes (where "drv_" is interpreted as the driver prefix).
If "drv_meta" is set, an attribute with the name in "drv_meta" is initialized providing restricted read/write access to the meta data of the tables using "DBD::File::TieTables" in the first (table) level and "DBD::File::TieMeta" for the meta attribute level. "DBD::File::TieTables" uses "DBD::DRV::Table::get_table_meta" to initialize the second level tied hash on FETCH/STORE. The "DBD::File::TieMeta" class uses "DBD::DRV::Table::get_table_meta_attr" to FETCH attribute values and "DBD::DRV::Table::set_table_meta_attr" to STORE attribute values. This allows it to map meta attributes for compatibility reasons.
While get_file_meta allows $table or $attr to be a list of tables or attributes to retrieve, get_single_table_meta allows only one table name and only one attribute name. A table name of '.' (single dot) is interpreted as the default table and this will retrieve the appropriate attribute globally from the dbh. This has the same restrictions as "$dbh->{$attrib}".
get_file_meta allows '+' and '*' as wildcards for table names and $table being a regular expression matching against the table names (evaluated without the default table). The table name '*' is all currently known tables, including the default one. The table name '+' is all table names which conform to ANSI file name restrictions (/^[_A-Za-z0-9]+$/).
The table meta information is retrieved using the get_table_meta and get_table_meta_attr methods of the table class of the implementation.
While set_file_meta allows $table to be a list of tables and $attr to be a hash of several attributes to set, set_single_table_meta allows only one table name and only one attribute name/value pair.
The wildcard characters for the table name are the same as for get_file_meta.
The table meta information is updated using the get_table_meta and set_table_meta_attr methods of the table class of the implementation.
This method usually requires extending in a derived implementation. See DBD::CSV or DBD::DBM for some example.
package DBD::File::TableSource::FileSystem;
sub data_sources ($;$)
{
my ($class, $drh, $attrs) = @_;
...
}
sub avail_tables
{
my ($class, $drh) = @_;
...
}
The "data_sources" method is called when the user invokes any of the following:
@ary = DBI->data_sources ($driver); @ary = DBI->data_sources ($driver, \%attr); @ary = $dbh->data_sources (); @ary = $dbh->data_sources (\%attr);
The "avail_tables" method is called when the user invokes any of the following:
@names = $dbh->tables ($catalog, $schema, $table, $type);
$sth = $dbh->table_info ($catalog, $schema, $table, $type);
$sth = $dbh->table_info ($catalog, $schema, $table, $type, \%attr);
$dbh->func ("list_tables");
Every time where an "\%attr" argument can be specified, this "\%attr" object's "sql_table_source" attribute is preferred over the $dbh attribute or the driver default.
package DBD::File::DataSource::Stream;
@DBD::File::DataSource::Stream::ISA = 'DBI::DBD::SqlEngine::DataSource';
sub complete_table_name
{
my ($self, $meta, $file, $respect_case) = @_;
...
}
Clears all meta attributes identifying a file: "f_fqfn", "f_fqbn" and "f_fqln". The table name is set according to $respect_case and "$meta->{sql_identifier_case}" (SQL_IC_LOWER, SQL_IC_UPPER).
package DBD::File::DataSource::Stream;
sub apply_encoding
{
my ($self, $meta, $fn) = @_;
...
}
Applies the encoding from meta information ("$meta->{f_encoding}") to the file handled opened in "open_data".
package DBD::File::DataSource::Stream;
sub open_data
{
my ($self, $meta, $attrs, $flags) = @_;
...
}
Opens ("dup (2)") the file handle provided in "$meta->{f_file}".
package DBD::File::DataSource::Stream;
sub can_flock { ... }
Returns whether "flock (2)" is available or not (avoids retesting in subclasses).
package DBD::File::DataSource::File;
sub complete_table_name ($$;$)
{
my ($self, $meta, $table, $respect_case) = @_;
...
}
The method "complete_table_name" tries to map a filename to the associated table name. It is called with a partially filled meta structure for the resulting table containing at least the following attributes: "f_ext", "f_dir", "f_lockfile" and "sql_identifier_case".
If a file/table map can be found then this method sets the "f_fqfn", "f_fqbn", "f_fqln" and "table_name" attributes in the meta structure. If a map cannot be found the table name will be undef.
package DBD::File::DataSource::File;
sub open_data ($)
{
my ($self, $meta, $attrs, $flags) = @_;
...
}
Depending on the attributes set in the table's meta data, the following steps are performed. Unless "f_dontopen" is set to a true value, "f_fqfn" must contain the full qualified file name for the table to work on (file2table ensures this). The encoding in "f_encoding" is applied if set and the file is opened. If "<f_fqln "> (full qualified lock name) is set, this file is opened, too. Depending on the value in "f_lock", the appropriate lock is set on the opened data file or lock 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
It copies the following attributes from the database into the table meta data "f_dir", "f_ext", "f_encoding", "f_lock", "f_schema" and "f_lockfile" and makes them sticky to the table.
This method should be called before you attempt to map between file name and table name to ensure the correct directory, extension etc. are used.
If the modified attribute requires to reset a calculated attribute, the calculated attribute is reset (deleted from meta data structure) and the initialized flag is removed, too. The decision is made based on %register_reset_on_modify.
If your DBD has calculated values in the meta data area, then call "register_reset_on_modify":
my %reset_on_modify = (xxx_foo => "xxx_bar"); __PACKAGE__->register_reset_on_modify (\%reset_on_modify);
# from DBD::DBM my %compat_map = (dbm_ext => "f_ext"); __PACKAGE__->register_compat_map (\%compat_map);
Depending on the attributes set in the table's meta data, the following steps are performed. Unless "f_dontopen" is set to a true value, "f_fqfn" must contain the full qualified file name for the table to work on (file2table ensures this). The encoding in "f_encoding" is applied if set and the file is opened. If "<f_fqln "> (full qualified lock name) is set, this file is opened, too. Depending on the value in "f_lock", the appropriate lock is set on the opened data file or lock file.
After this is done, a derived class might add more steps in an overridden "open_file" method.
1. get the table meta data 2. open the data file 3. bless the table data structure using inherited constructor new
It is not recommended to override the constructor of the table class. Find a reasonable place to add you extensions in one of the above four methods.
Overriding this method might be reasonable in very rare cases.
You should consult the documentation of "SQL::Eval::Table" (see SQL::Eval) to get more information about the abstract methods of the table's base class you have to override and a description of the table meta information expected by the SQL engines.
H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack < rehsack at googlemail.com >
The original author is Jochen Wiedmann.
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.