org.vibur.dbcp

Interface ViburDataSource

All Superinterfaces:

AutoCloseable, CommonDataSource, DataSource, Wrapper

All Known Implementing Classes:

ViburDBCPDataSource

public interface ViburDataSource
extends DataSource, AutoCloseable

Defines the ViburDBCPDataSource lifecycle operations and states. Also, defines specific to Vibur DataSource operations such as retrieving and manipulating of non-pooled connections as well as operations giving information about the currently taken from the pool connections.

Author:

Simeon Malchev

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ViburDataSource.State The possible states in which the DataSource can be.

Method Summary

Modifier and Type	Method and Description
void	close() A synonym for terminate().
Connection	getConnection()
Connection	getConnection(String username, String password)
Connection	getNonPooledConnection() Returns a raw (non-pooled) JDBC Connection using the default username and password.
Connection	getNonPooledConnection(String username, String password) Returns a raw (non-pooled) JDBC Connection using the supplied username and password.
ViburDataSource.State	getState() Returns this DataSource current state.
TakenConnection[]	getTakenConnections() Returns an array of all taken proxy Connections.
String	getTakenConnectionsStackTraces() Generates information about all currently taken connections, including the stack traces of the threads that have taken them, plus the threads names and states.
void	severConnection(Connection connection) Severs the supplied connection which can either be a pooled connection retrieved via calling one of the getConnection() methods or a raw non-pooled connection retrieved via calling one of the getNonPooledConnection() methods.
void	start() Starts this DataSource.
void	terminate() Terminates this DataSource.

Methods inherited from interface javax.sql.CommonDataSource

getLoginTimeout, getLogWriter, getParentLogger, setLoginTimeout, setLogWriter

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Method Detail

start

void start()
    throws ViburDBCPException

Starts this DataSource. In order to be used, the implementing DataSource has to be first created via calling one of the available constructors, configured, and then started via calling this method. Any necessary validation of the configuration will be performed as part of this call.

Throws:

ViburDBCPException - if not in a NEW state when started; if a configuration error is found during start; if cannot start this DataSource successfully for any other reason

getState

ViburDataSource.State getState()

Returns this DataSource current state.

terminate

void terminate()

Terminates this DataSource. Once terminated the DataSource cannot be more revived.

close

void close()

A synonym for terminate(). Overrides the AutoCloseable's method in order to overrule the throwing of a checked Exception.

Specified by:

close in interface AutoCloseable

getConnection

Connection getConnection()
                  throws SQLException

Specified by:

getConnection in interface DataSource

Throws:

SQLTimeoutException - when the timeout value specified by the connectionTimeoutInMs has been exceeded

SQLException

getConnection

Connection getConnection(String username,
                         String password)
                  throws SQLException

This method will return a raw (non-pooled) JDBC Connection when called with credentials different than the configured default credentials.

Specified by:

getConnection in interface DataSource

Throws:

SQLTimeoutException - when called with the default credentials and when the timeout value specified by the connectionTimeoutInMs has been exceeded

SQLException

getNonPooledConnection

Connection getNonPooledConnection()
                           throws SQLException

Returns a raw (non-pooled) JDBC Connection using the default username and password.

Throws:

SQLException - if an error occurs while creating the connection

getNonPooledConnection

Connection getNonPooledConnection(String username,
                                  String password)
                           throws SQLException

Returns a raw (non-pooled) JDBC Connection using the supplied username and password.

Parameters:

username - the database username

password - the database password

Throws:

SQLException - if an error occurs while creating the connection

severConnection

void severConnection(Connection connection)
              throws SQLException

Severs the supplied connection which can either be a pooled connection retrieved via calling one of the getConnection() methods or a raw non-pooled connection retrieved via calling one of the getNonPooledConnection() methods. If the supplied connection is pooled, it will be closed and removed from the pool and its underlying raw connection will be closed, too. In the case when the supplied connection is non-pooled, it will be just closed.

Calling this method on a pooled or non-pooled connection that is already closed is a no-op. When the severConnection method returns, the connection on which it is called will be marked as closed.

Parameters:

connection - the connection to be severed

Throws:

SQLException - if an error occurs while closing/severing the connection

getTakenConnectionsStackTraces

String getTakenConnectionsStackTraces()

Generates information about all currently taken connections, including the stack traces of the threads that have taken them, plus the threads names and states. This method implies that that the ViburConfig.poolEnableConnectionTracking option is enabled.

The exact format of the logged message is controlled by ViburConfig.takenConnectionsFormatter.

Also see ViburConfig.logTakenConnectionsOnTimeout and getTakenConnections().

getTakenConnections

TakenConnection[] getTakenConnections()

Returns an array of all taken proxy Connections. Note that this is just a snapshot of the taken Connections at the moment of the method call; the closed/restored state of some (or all) of the returned Connections may change immediately after this method returns. This method implies that that the ViburConfig.poolEnableConnectionTracking option is enabled.

Also see getTakenConnectionsStackTraces().

Returns:

an array of all taken proxy Connections