GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


NAME

       Alzabo::Driver - Alzabo base class for RDBMS drivers

SYNOPSIS

         use Alzabo::Driver;

         my $driver = Alzabo::Driver->new( rdbms => 'MySQL',
                                           schema => $schema );

DESCRIPTION

       This is the base class for all Alzabo::Driver modules.  To instantiate
       a driver call this class's "new()" method.  See SUBCLASSING
       Alzabo::Driver for information on how to make a driver for the RDBMS of
       your choice.

       This class throws several, exceptions, one of which,
       "Alzabo::Exception::Driver", has additional methods not present in
       other exception classes.  See "Alzabo::Exception::Driver METHODS" for a
       description of these methods.

METHODS

   available
       Returns a list of names representing the available "Alzabo::Driver"
       subclasses.  Any one of these names would be appropriate as the "rdbms"
       parameter for the "Alzabo::Driver->new" method.

   new
       The constructor takes the following parameters:

       ·   rdbms => $rdbms_name

           The name of the RDBMS being used.

       ·   schema => "Alzabo::Schema" object

       It returns a new "Alzabo::Driver" object of the appropriate subclass.

       Throws: "Alzabo::Exception::Eval"

   tables
       Returns a list of strings containing the names of the tables in the
       database.  See the "DBI" documentation of the "DBI->tables" method for
       more details.

       Throws: "Alzabo::Exception::Driver"

   handle ($optional_dbh)
       This method takes one optional parameter, a connected DBI handle.  If
       this is given, then this handle is the new handle for the driver.

       It returns the active database handle.

       Throws: "Alzabo::Exception::Params"

   Data Retrieval methods
       Some of these methods return lists of data (the "rows", "rows_hashref",
       and "column" methods).  With large result sets, this can use a lot
       memory as these lists are created in memory before being returned to
       the caller.  To avoid this, it may be desirable to use the
       functionality provided by the "Alzabo::DriverStatement" class, which
       allows you to fetch results one row at a time.

       These methods all accept the following parameters:

       ·   sql => $sql_string

       ·   bind => $bind_value or \@bind_values

       ·   limit => [ $max, optional $offset ] (optional)

           The $offset defaults to 0.

           This parameter has no effect for the methods that return only one
           row.  For the others, it causes the drivers to skip $offset rows
           and then return only $max rows.  This is useful if the RDBMS being
           used does not support "LIMIT" clauses.

   rows
       Returns an array of array references containing the data requested.

   rows_hashref
       Returns an array of hash references containing the data requested.  The
       hash reference keys are the columns being selected.  All the key names
       are in uppercase.

   one_row
       Returns an array or scalar containing the data returned, depending on
       context.

   one_row_hash
       Returns a hash containing the data requested.  The hash keys are the
       columns being selected.  All the key names are in uppercase.

   column
       Returns an array containing the values for the first column of each row
       returned.

   do
       Use this for non-SELECT SQL statements.

       Returns the number of rows affected.

       Throws: "Alzabo::Exception::Driver"

   statement
       This methods returns a new "Alzabo::DriverStatement" handle, ready to
       return data via the "Alzabo::DriverStatement->next()" or
       "Alzabo::DriverStatement->next_as_hash()" methods.

       Throws: "Alzabo::Exception::Driver"

   rdbms_version
       Returns the version string of the database backend currently in use.
       The form of this string will vary depending on which driver subclass is
       being used.

   quote (@strings)
       This methods calls the underlying DBI handles "quote()" method on the
       array of strings provided, and returns the quoted versions.

   quote_identifier (@strings)
       This methods calls the underlying DBI handles "quote_identifier()"
       method on the array of strings provided, and returns the quoted
       versions.

Alzabo::DriverStatement

       This class is a wrapper around "DBI"'s statement handles.  It finishes
       automatically as appropriate so the end user does need not worry about
       doing this.

   next
       Use this method in a while loop to fetch all the data from a statement.

       Returns an array containing the next row of data for statement or an
       empty list if no more data is available.

       Throws: "Alzabo::Exception::Driver"

   next_as_hash
       For backwards compatibility, this is also available as "next_hash()".

       Returns a hash containing the next row of data for statement or an
       empty list if no more data is available.  All the keys of the hash will
       be lowercased.

       Throws: "Alzabo::Exception::Driver"

   all_rows
       If the select for which this statement is cursor was for a single
       column (or aggregate value), then this method returns an array
       containing each remaining value from the database.

       Otherwise, it returns an array of array references, each one containing
       a returned row from the database.

       Throws: "Alzabo::Exception::Driver"

   all_rows_hash
       Returns an array of hashes, each hash representing a single row
       returned from the database.  The hash keys are all in lowercase.

       Throws: "Alzabo::Exception::Driver"

   execute (@bind_values)
       Executes the associated statement handle with the given bound
       parameters.  If the statement handle is still active (it was previously
       executed and has more data left) then its "finish()" method will be
       called first.

       Throws: "Alzabo::Exception::Driver"

   count
       Returns the number of rows returned so far.

Alzabo::Exception::Driver METHODS

       In addition to the methods inherited from "Exception::Class::Base",
       objects in this class also contain several methods specific to this
       subclass.

   sql
       Returns the SQL statement in use at the time the error occurred, if
       any.

   bind
       Returns an array reference contaning the bound parameters for the SQL
       statement, if any.

SUBCLASSING Alzabo::Driver

       To create a subclass of "Alzabo::Driver" for your particular RDBMS is
       fairly simple.  First of all, there must be a "DBD::*" driver for it,
       as "Alzabo::Driver" is built on top of "DBI".

       Here's a sample header to the module using a fictional RDBMS called
       FooDB:

        package Alzabo::Driver::FooDB;

        use strict;
        use vars qw($VERSION);

        use Alzabo::Driver;

        use DBI;
        use DBD::FooDB;

        use base qw(Alzabo::Driver);

       The next step is to implement a "new" method and the methods listed
       under "Virtual Methods".  The "new" method should look a bit like this:

        1:  sub new
        2:  {
        3:      my $proto = shift;
        4:      my $class = ref $proto || $proto;
        5:      my %p = @_;
        6:
        7:      my $self = bless {}, $class;
        8:
        9:      return $self;
        10:  }

       The hash %p contains any values passed to the "Alzabo::Driver->new"
       method by its caller.

       Lines 1-7 should probably be copied verbatim into your own "new"
       method.  Line 5 can be deleted if you don't need to look at the
       parameters.

       Look at the included "Alzabo::Driver" subclasses for examples.  Feel
       free to contact me for further help if you get stuck.  Please tell me
       what database you're attempting to implement, what its DBD::* driver
       is, and include the code you've written so far.

   Virtual Methods
       The following methods are not implemented in "Alzabo::Driver" itself
       and must be implemented in a subclass.

       Parameters for connect(), create_database(), and drop_database()

       ·   user => $db_username

       ·   password => $db_pw

       ·   host => $hostname

       ·   port => $port

       All of these default to undef.  See the appropriate DBD driver
       documentation for more details.

       After the driver is created, it will have access to its associated
       schema object in "$self->{schema}".

   connect
       Some drivers may accept or require more arguments than specified above.

       Note that "Alzabo::Driver" subclasses are not expected to cache
       connections.  If you want to do this please use "Apache::DBI" under
       mod_perl or don't call "connect()" more than once per process.

   create_database
       Attempts to create a new database for the schema attached to the
       driver.  Some drivers may accept or require more arguments than
       specified above.

   drop_database
       Attempts to drop the database for the schema attached to the driver.

   schemas
       Returns a list of schemas in the specified RDBMS.  This method may
       accept some or all of the parameters which can be given to "connect()".

   supports_referential_integrity
       Should return a boolean value indicating whether or not the RDBMS
       supports referential integrity constraints.

   next_sequence_number ("Alzabo::Column" object)
       This method is expected to return the value of the next sequence number
       based on a column object.  For some databases (MySQL, for example), the
       appropriate value is "undef".  This is accounted for in the Alzabo code
       that calls this method.

   begin_work
       Notify Alzabo that you wish to start a transaction.

   rollback
       Rolls back the current transaction.

   commit
       Notify Alzabo that you wish to finish a transaction.  This is basically
       the equivalent of calling commit.

   get_last_id
       Returns the last primary key id created via a sequenced column.

   rdbms_version
       Returns the version of the server to which the driver is connected.

   driver_id
       Returns the driver's name.  This should be something that can be passed
       to "Alzabo::Driver->new()" as a "name" parameter.

AUTHOR

       Dave Rolsky, <dave@urth.org>



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.162 seconds. Last modified: November 04 2018 12:49:43.