view release on metacpan or  search on metacpan

lib/Class/DBI/ViewLoader.pm  view on Meta::CPAN

=head2 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.

=cut

sub get_options {
    my $self = shift;

    # set up an empty options hash if there is none available.
    $self->set_options unless $self->{_dbi_options};

    return $self->{_dbi_options};
}

# Return this object's complete arguments to send to DBI.
sub _get_dbi_args {
    my $self = shift;

    # breaking encapsulation to use hashslice:
    return @$self{qw( _dsn _username _password _dbi_options )};
}

# Return a new or existing DBI handle
# Drivers should use this method to access the database
sub _get_dbi_handle {
    my $self = shift;

    return $self->{_dbh} if $self->{_dbh};

    my $dbh = DBI->connect( $self->_get_dbi_args )
	or croak "Couldn't connect to database, $DBI::errstr";

    $self->_set_dbi_handle($dbh);

    return $dbh;
}

# set the DBI handle. Might one day be called directly..
sub _set_dbi_handle {
    my $self = shift;
    my $dbh = shift;

    $self->_clear_dbi_handle;
    $self->{_dbh} = $dbh;

    return $self;
}

# disconnect current DBI handle, if any
sub _clear_dbi_handle {
    my $self = shift;

    return $self if $self->_keepalive;

    if (defined $self->{_dbh}) {
	delete($self->{_dbh})->disconnect;
    }

    return $self;
}

sub DESTROY {
    my $self = shift;

    $self->_clear_dbi_handle;
}

# switch to disable _clear_dbi_handle
sub _set_keepalive {
    my $self = shift;
    $self->{__keepalive} = shift;
    return $self;
}

# check status of switch
sub _keepalive {
    my $self = shift;
    return $self->{__keepalive};
}

=head2 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 '::'.

=cut

sub set_namespace {
    my($self, $namespace) = @_;

    $namespace =~ s/::$//;

    $self->{_namespace} = $namespace;

    return $self;
}

=head2 get_namespace

    $namespace = $obj->get_namespace

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

=cut

sub get_namespace {
    my $self = shift;
    my $out = $self->{_namespace};

    if (defined $out and length $out) {
	return $out;
    }
    else {
	return;
    }
}

=head2 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.

=cut

sub set_include {
    my($self, $include) = @_;

    $self->{_include} = $self->_compile_regex($include);

    return $self;
}

lib/Class/DBI/ViewLoader.pm  view on Meta::CPAN

	my $code = join("\n\n", @$cache);

	eval $code;

	croak "Eval error!\nCode:\n$code\n\nMessage: $@" if $@;
    }

    return $self;
}

=head2 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.

=cut

sub view_to_class {
    my($self, $view) = @_;

    if (defined $view and length $view) {
	# cribbed from Class::DBI::Loader
	$view = join('', map { ucfirst } split(/[\W_]+/, $view));

	return join('::', $self->get_namespace, $view);
    }
    else {
	return '';
    }
}

=head2 _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.

=head2 _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(@_);
    }

=head2 _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.

=head2 _set_keepalive

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

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

=head2 _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.

=head1 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.

=over 4

=item * 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" }

=item * get_views

    @views = $driver->get_views;

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

=item * get_view_cols

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

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

=back

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.

=cut

our @driver_methods = qw(
	base_class
	get_views
	get_view_cols