NAME
   Class::DBI::ViewLoader - Load views from existing databases as
   Class::DBI objects

SYNOPSIS
       use Class::DBI::ViewLoader;

       # set up loader object
       $loader = new Class::DBI::ViewLoader (
               dsn => 'dbi:Pg:dbname=mydb',
               username => 'me',
               password => 'mypasswd',
               options => {
                   RaiseError => 1,
                   AutoCommit => 1
               },
               namespace => 'MyClass::View',
               exclude => qr(^te(?:st|mp)_)i,
               include => qr(_foo$),
               import_classes => [qw(
                   Class::DBI::Plugin::RetrieveAll
                   Class::DBI::AbstractSearch
               )];
               base_classes => [qw(
                   MyBase
               )];
           );

       # create classes
       @classes = $loader->load_views;

       # retrieve all rows from view live_foo
       MyClass::View::LiveFoo->retrieve_all()

       # Get the class name from the view name
       $class = $loader->view_to_class('live_foo');

       # Works for views that weren't loaded too
       $unloaded_class = $loader->view_to_class('test_foo');

DESCRIPTION
   This class loads views from databases as Class::DBI classes. It follows
   roughly the same interface employed by Class::DBI::Loader.

   This class behaves as a base class for the database-dependent driver
   classes, which are loaded by Module::Pluggable. Objects are reblessed
   into the relevant subclass as soon as the driver is discovered, see
   set_dsn(). Driver classes should always be named
   Class::DBI::ViewLoader::<driver_name>.

CONSTRUCTOR
 new
       $obj = $class->new(%args)

   Instantiates a new object. The values of %args are passed to the
   relevant set_* accessors, detailed below. The following 2 statements
   should be equivalent:

       new Class::DBI::ViewLoader ( dsn => $dsn, username => $user );

       new Class::DBI::ViewLoader->set_dsn($dsn)->set_username($user);

   For compatibilty with Class::DBI::Loader, the following aliases are
   provided for use in the arguments to new() only.

   * user -> username
   * additional_classes -> import_classes
   * additional_base_classes -> base_classes
   * constraint -> include

   the debug and relationships options are not supported but are silently
   ignored.

   So

       new Class::DBI::ViewLoader user => 'me', constraint => '^foo', debug => 1;

   Is equivalent to:

       new Class::DBI::ViewLoader username => 'me', include => '^foo';

   Unrecognised options will cause a fatal error to be raised, see
   DIAGNOSTICS.

ACCESSORS
 set_dsn
       $obj = $obj->set_dsn($dsn_string)

   Sets the datasource for the object. This should be in the form
   understood by DBI e.g. "dbi:Pg:dbname=mydb"

   Calling this method will rebless the object into a handler class for the
   given driver. If no such handler is installed, "No handler for driver"
   will be raised via croak(). See DIAGNOSTICS for other fatal errors
   raised by this method.

 get_dsn
       $dsn = $obj->get_dsn

   Returns the dsn string, as passed in by set_dsn.

 set_username
       $obj = $obj->set_username($username)

   Sets the username to use when connecting to the database.

 get_username
       $username = $obj->get_username

   Returns the username.

 set_password
       $obj = $obj->set_password

   Sets the password to use when connecting to the database.

 get_password
       $password = $obj->get_password

   Returns the password

 set_options
       $obj = $obj->set_dbi_options(%opts)

   Accepts a hash or a hash reference.

   Sets the additional configuration options to pass to DBI.

   The hash will be copied internally, to guard against any accidental
   modification after assignment.

 get_options
       \%opts = $obj->get_dbi_options

   Returns the DBI options hash. The return value should always be a hash
   reference, even if there are no dbi options set.

   The reference returned by this function is live, so modification of it
   directly affects the object.

 set_namespace
       $obj = $obj->set_namespace($namespace)

   Sets the namespace to load views into. This should be a valid perl
   package name, with or without a trailing '::'.

 get_namespace
       $namespace = $obj->get_namespace

   Returns the target namespace. If not set, returns an empty list.

 set_include
       $obj = $obj->set_include($regexp)

   Sets a regexp that matches the views to load. Only views that match this
   expression will be loaded, unless they also match the exclude
   expression.

   Accepts strings or Regexps, croaks if any other reference is passed.

   The value is stored as a Regexp, even if a string was passed in.

 get_include
       $regexp = $obj->get_include

   Returns the include regular expression.

   Note that this may not be identical to what was passed in.

 set_exclude
       $obj = $obj->set_exclude($regexp)

   Sets a regexp to use to rule out views. Any view that matches this regex
   will not be loaded by load_views(), even if it is explicitly included by
   the include rule.

   Accepts strings or Regexps, croaks if any other reference is passed.

   The value is stored as a Regexp, even if a string was passed in.

 get_exclude
       $regexp = $obj->get_exclude

   Returns the exclude regular expression.

   Note that this may not be identical to what was passed in.

 set_base_classes
       $obj = $obj->set_base_classes(@classes)

   Sets classes for all generated classes to inherit from.

   This is in addition to the class specified by the driver's base_class
   method, which will always be the first item in the generated @ISA.

   Note that these classes are not loaded for you, be sure to "use" or
   "require" them yourself.

 add_base_classes
       $obj = $obj->add_base_classes(@classes)

   Appends to the list of base classes.

 get_base_classes
       @classes = $obj->get_base_classes

   Returns the list of base classes.

 set_import_classes
       $obj = $obj->set_import_classes(@classes)

   Sets a list of classes to import from. Note that these classes are not
   loaded by the generated class itself.

       # Load the module first
       require Class::DBI::Plugin::RetrieveAll;

       # Make generated classes import symbols
       $loader->set_import_classes(qw(Class::DBI::Plugin::RetrieveAll));

   Any classes that inherit from Exporter will be loaded via Exporter's
   export() function. Any other classes are loaded by an import() call in a
   string eval.

 add_import_classes
       $obj = $obj->add_import_classes(@classes)

   Appends to the list of import classes.

 get_import_classes
       @classes = $obj->get_import_classes

METHODS
 load_views
       @classes = $obj->load_views

   The main method for the class, loads all relevant views from the
   database and generates classes for those views.

   The generated classes will be read-only and have a multi-column primary
   key containing every column. This is because it is not guaranteed that
   the view will have a real primary key and Class::DBI insists that there
   should be a unique identifier for every row.

   Usually, any row containing an undef (NULL) primary key column is
   considered false in boolean context, in this particular case however
   that doesn't make much sense. So only all-null rows are considered false
   in classes generated by this class.

   Each class is only ever generated once, no matter how many times
   load_views() is called. If you want to load the same view twice for some
   reason, you can achieve this by changing the namespace.

   Returns class names for all created classes, including any that were
   skipped due to already existing.

 view_to_class
       $class = $obj->view_to_class($view)

   Returns the class for the given view name. This depends on the object's
   current namespace, see set_namespace(). It doesn't matter if the class
   has been loaded, or if the view exists in the database.

   If this method is called without arguments, or with an empty string, it
   returns an empty string.

 _get_dbi_handle
       $dbh = $obj->_get_dbi_handle

   Returns a DBI handle based on the object's dsn, username and password.
   This generally shouldn't be called externally (hence the leading
   underscore).

   Making multiple calls to this method won't cause multiple connections to
   be made. A single handle is cached by the object from the first call to
   _get_dbi_handle until such time as the object goes out of scope or
   set_dsn is called again, at which time the handle is disconnected and
   the cache is cleared.

   If the connection fails, a fatal error is raised.

 _clear_dbi_handle
       $obj->_clear_dbi_handle

   This is the cleanup method for the object's DBI handle. It is called
   whenever the DBI handle needs to be closed down. Subclasses should
   override this method if they need to clean up any state data that relies
   on the current database connection, like statement handles for example.

       sub _clear_dbi_handle {
           my $self = shift;

           delete $self->{statement_handle};

           $self->SUPER::_clear_dbi_handle(@_);
       }

DRIVER METHODS
   The following methods are provided by the relevant driver classes. If
   they are called on a native Class::DBI::ViewLoader object (one without a
   dsn set), they will cause fatal errors. They are documented here for the
   benefit of driver writers but they may prove useful for users also.

   * base_class
           $class = $driver->base_class

       Should return the name of the base class to be used by generated
       classes. This will generally be a Class::DBI driver class.

           package Class::DBI::ViewLoader::Pg;

           # Generate postgres classes
           sub base_class { "Class::DBI::Pg" }

   * get_views
           @views = $driver->get_views;

       Should return the names of all the views in the current database.

   * get_view_cols
           @columns = $driver->get_view_cols($view);

       Should return the names of all the columns in the given view.

   A list of these methods is provided by this class, in
   @Class::DBI::ViewLoader::driver_methods, so that each driver can be sure
   that it is implementing all required methods. The provided
   t/04..plugin.t is a self-contained test script that checks a driver for
   compatibility with the current version of Class::DBI::ViewLoader, driver
   writers should be able to copy the test into their distribution and edit
   the driver name to provide basic compliance tests.

DIAGNOSTICS
   The following fatal errors are raised by this class:

   * No dsn
       set_dsn was called without an argument

   * Invalid dsn %s
       the dsn passed to set_dsn couldn't be parsed by DBI->parse_dsn

   * No handler for driver %s, from dsn %s
       set_dsn couldn't find a driver handler for the given dsn. You may
       need to install a plugin to handle your database.

   * No handler loaded
       load_views() or some other driver-dependent method was called on an
       object which hadn't loaded a driver.

   * %s not overridden
       A driver did not override the given method. You may need to upgrade
       the driver class.

   * Couldn't connect to database
       Self-explanatory. The DBI error string is appended to the error
       message.

   * Regexp or string required
       set_include or set_exclude called with a ref other than 'Regexp'.

   * Unrecognised arguments in new
       new() encountered unsupported arguments. The offending arguments are
       listed after the error message.

   The following warnings are generated:

   * No columns found in %s, skipping
       The given view didn't have any columns, it won't be loaded.

   * %s has no import function
       The given module from the object's import_classes list couldn't be
       imported because it had no import() function.

SEE ALSO
   DBI, Class::DBI, Class::DBI::Loader

AUTHOR
   Matt Lawrence <[email protected]>

COPYRIGHT
   Copyright 2005 Matt Lawrence, All Rights Reserved.

   This program is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.