DBD::File::Developers(3pm) - phpMan

DBD::File::Developers(User Contributed Perl DocumentatDBD::File::Developers(3)

NAME
       DBD::File::Developers - Developers documentation for DBD::File
SYNOPSIS
           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 { ... }
DESCRIPTION
       This document describes how DBD developers can write DBD::File based
       DBI drivers. It supplements DBI::DBD and
       DBI::DBD::SqlEngine::Developers, which you should read first.
CLASSES
       Each DBI driver must provide a package global "driver" method and three
       DBI related classes:
       DBD::File::dr
           Driver package, contains the methods DBI calls indirectly via DBI
           interface:
             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.
       DBD::File::db
           Contains the methods which are called through DBI database handles
           ($dbh). e.g.,
             $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".
       DBD::File::st
           Contains the methods to deal with prepared statement handles. e.g.,
             $sth->execute () or die $sth->errstr;
   DBD::File
       This is the main package containing the routines to initialize
       DBD::File based DBI drivers. Primarily the "DBD::File::driver" method
       is invoked, either directly from DBI when the driver is initialized or
       from the derived class.
         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::dr
       The driver package contains the methods DBI calls indirectly via the
       DBI interface (see "DBI Class Methods" in DBI).
       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";
   DBD::File::db
       This package defines the database methods, which are called via the DBI
       database handle $dbh.
       Methods provided by DBD::File:
       ping
           Simply returns the content of the "Active" attribute. Override when
           your driver needs more complicated actions here.
       prepare
           Prepares a new SQL statement to execute. Returns a statement
           handle, $sth - instance of the DBD:XXX::st. It is neither required
           nor recommended to override this method.
       FETCH
           Fetches an attribute of a DBI database object. Private handle
           attributes must have a prefix (this is mandatory). If a requested
           attribute is detected as a private attribute without a valid
           prefix, the driver prefix (written as $drv_prefix) is added.
           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.
       STORE
           Stores a database private attribute. Private handle attributes must
           have a prefix (this is mandatory). If a requested attribute is
           detected as a private attribute without a valid prefix, the driver
           prefix (written as $drv_prefix) is added. If the database handle
           has an attribute "${drv_prefix}_valid_attrs" - for attribute names
           which are not listed in that hash, this method croaks. If the
           database handle has an attribute "${drv_prefix}_readonly_attrs",
           only attributes which are not listed there can be stored (once they
           are initialized). Trying to overwrite such an immutable attribute
           forces this method to croak.
           An example of a valid attributes list can be found in
           "DBD::File::db::init_valid_attributes".
       set_versions
           This method sets the attribute "f_version" with the version of
           DBD::File.
           This method is called at the begin of the "connect ()" phase.
           When overriding this method, do not forget to invoke the superior
           one.
       init_valid_attributes
           This method is called after the database handle is instantiated as
           the first attribute initialization.
           "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";
       init_default_attributes
           This method is called after the database handle is instantiated to
           initialize the default attributes.
           "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.
       get_single_table_meta
       get_file_meta
           Retrieve an attribute from a table's meta information. The method
           signature is "get_file_meta ($dbh, $table, $attr)". This method is
           called by the injected db handle method "${drv_prefix}get_meta".
           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.
       set_single_table_meta
       set_file_meta
           Sets an attribute in a table's meta information. The method
           signature is "set_file_meta ($dbh, $table, $attr, $value)". This
           method is called by the injected db handle method
           "${drv_prefix}set_meta".
           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.
       clear_file_meta
           Clears all meta information cached about a table. The method
           signature is "clear_file_meta ($dbh, $table)". This method is
           called by the injected db handle method "${drv_prefix}clear_meta".
   DBD::File::st
       Contains the methods to deal with prepared statement handles:
       FETCH
           Fetches statement handle attributes. Supported attributes (for full
           overview see "Statement Handle Attributes" in DBI) are "NAME",
           "TYPE", "PRECISION" and "NULLABLE" in case that SQL::Statement is
           used as SQL execution engine and a statement is successful
           prepared.  When SQL::Statement has additional information about a
           table, those information are returned. Otherwise, the same defaults
           as in DBI::DBD::SqlEngine are used.
           This method usually requires extending in a derived implementation.
           See DBD::CSV or DBD::DBM for some example.
   DBD::File::TableSource::FileSystem
       Provides data sources and table information on database driver and
       database handle level.
         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.
   DBD::File::DataSource::Stream
         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).
   DBD::File::DataSource::File
         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.
   DBD::File::Statement
       Derives from DBI::SQL::Nano::Statement to provide following method:
       open_table
           Implements the open_table method required by SQL::Statement and
           DBI::SQL::Nano. All the work 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
   DBD::File::Table
       Derives from DBI::SQL::Nano::Table and provides physical file access
       for the table data which are stored in the files.
       bootstrap_table_meta
           Initializes a table meta structure. Can be safely overridden in a
           derived class, as long as the "SUPER" method is called at the end
           of the overridden method.
           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.
       init_table_meta
           Initializes more attributes of the table meta data - usually more
           expensive ones (e.g. those which require class instantiations) -
           when the file name and the table name could mapped.
       get_table_meta
           Returns the table meta data. If there are none for the required
           table, a new one is initialized. When it fails, nothing is
           returned. On success, the name of the table and the meta data
           structure is returned.
       get_table_meta_attr
           Returns a single attribute from the table meta data. If the
           attribute name appears in %compat_map, the attribute name is
           updated from there.
       set_table_meta_attr
           Sets a single attribute in the table meta data. If the attribute
           name appears in %compat_map, the attribute name is updated from
           there.
       table_meta_attr_changed
           Called when an attribute of the meta data is modified.
           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.
       register_reset_on_modify
           Allows "set_table_meta_attr" to reset meta attributes when special
           attributes are modified. For DBD::File, modifying one of "f_file",
           "f_dir", "f_ext" or "f_lockfile" will reset "f_fqfn". DBD::DBM
           extends the list for "dbm_type" and "dbm_mldbm" to reset the value
           of "dbm_tietype".
           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);
       register_compat_map
           Allows "get_table_meta_attr" and "set_table_meta_attr" to update
           the attribute name to the current favored one:
             # from DBD::DBM
             my %compat_map = (dbm_ext => "f_ext");
             __PACKAGE__->register_compat_map (\%compat_map);
       open_file
           Called to open the table's data file.
           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.
       new Instantiates the table. This is done in 3 steps:
            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.
       drop
           Implements the abstract table method for the "DROP" command.
           Discards table meta data after all files belonging to the table are
           closed and unlinked.
           Overriding this method might be reasonable in very rare cases.
       seek
           Implements the abstract table method used when accessing the table
           from the engine. "seek" is called every time the engine uses dumb
           algorithms for iterating over the table content.
       truncate
           Implements the abstract table method used when dumb table
           algorithms for "UPDATE" or "DELETE" need to truncate the table
           storage after the last written row.
       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.
AUTHOR
       The module DBD::File is currently maintained by
       H.Merijn Brand < h.m.brand at xs4all.nl > and Jens Rehsack  < rehsack
       at googlemail.com >
       The original author is Jochen Wiedmann.
COPYRIGHT AND LICENSE
       Copyright (C) 2010-2013 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.

perl v5.16.3                      2013-04-04          DBD::File::Developers(3)