/ 
Class-DBI-ViewLoader-0.06
River stage one • 1 direct dependent • 1 total dependent
/ Class::DBI::ViewLoader

NAME

Class::DBI::ViewLoader - Load views from existing databases as Class::DBI classes

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
	    )],
	    accessor_prefix => 'get_',
	    mutator_prefix => 'set_',
	);

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

Options specified affect how the database that is used by the loader is built. This is not always the same handle that is used by generated classes.

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, as supplied by set_base_classes.

set_left_base_classes

Sets base classes like set_base_classes, except that the added classes will go before the driver's base_class.

get_left_base_classes

@classes = $obj->get_left_base_classes

Returns the list of left base classes, as supplied by set_base_classes.

add_left_base_classes

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

Appends to the list of left 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 a use 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

Returns the list of classes that will be imported into you generated classes.

set_accessor_prefix

$obj = $obj->set_accessor_prefix

Sets the accessor prefix for generated classes. See Class::DBI for details of how this works.

get_accessor_prefix

$prefix = $obj->get_accessor_prefix

Returns the object's accessor prefix.

set_mutator_prefix

$obj = $obj->set_mutator_prefix

Sets the mutator prefix for generated classes. See Class::DBI for details of how this works.

get_mutator_prefix

$prefix = $obj->get_mutator_prefix

Returns the object's mutator prefix.

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.

If the newly generated class inherits a "Main" Class::DBI handle (via connection or set_db calls in base classes) that handle will be used by the class. Otherwise, a new connection is set up for the classes based on the loader's connection.

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.

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. i.e. when a new handle is used or the object goes out of scope. 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. If you don't want the handle that the object is using to be disconnected, use the _set_keepalive method.

    sub _clear_dbi_handle {
	my $self = shift;

	delete $self->{statement_handle};

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

_set_dbi_handle

$obj = $obj->_set_dbi_handle($dbh)

This method is used to attach a DBI handle to the object. It might prove useful to use this method in order to use an existing database connection in the loader object. Note that unlike set_dsn, calling this method directly will not cause an appropriate driver to be loaded. See _load_driver for that.

_set_keepalive

$obj = $obj->_set_keepalive($bool)

When set to true, the database handle used by the object won't be disconnected automatically.

_load_driver

$obj = $obj->_load_driver($driver_name)

This method is used internally by set_dsn to load a driver to handle database-specific functionality. It can be called directly in conjunction with _set_dbi_handle to load views from an existing database connection.

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 seem to 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.

BUGS

With later versions of Class::DBI, columns names that clash with methods (such as 'id') can cause exceptions. Using accessor_prefix and mutator_prefix can help avoid this problem.

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.