NAME

Class::DBI::ViewLoader - Load views from database tables 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;

    MyClass::View::LiveFoo->retrieve_all()

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 will be 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.

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 handler is installed, "No handler for driver" will be raised via croak().

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 prevent 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.

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.

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.

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 use or require them manually before calling.

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() 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 and be read-only, and have a multi-column primary key containing every column. This is because it is unlikely that the view will have a real primary key.

Each class is only ever generated once.

Returns class names for all created classes, including those that already existed.

_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, but is documented for the benefit of driver writers.

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.

DRIVERS

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 mostly 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 database.

• get_view_cols

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

  Returns 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 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.

• 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 $view, skipping

  The view $view didn't have any columns, it won't be loaded.

• $module 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 <mattlaw@cpan.org>

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.

cpanm Class::DBI::ViewLoader

perl -MCPAN -e shell
install Class::DBI::ViewLoader