com.programix.sql
Interface ConnectionSource

All Known Implementing Classes:

ConnectionPool, DriverManagerConnectionSource

public interface ConnectionSource

Interface used to mark a generic source of JDBC connections.

Author:

Paul Hyde

Method Summary

Connection	getConnection() Returns a Connection (potentially from a shared resource pool).
Connection	getConnection(long msTimeout) Returns a Connection (potentially from a shared resource pool).
void	shutdown() Call this when done with the ConnectionSource to allow any underlying allocated resources to be released.

Method Detail

getConnection

Connection getConnection(long msTimeout)
                         throws SQLTimedOutException,
                                SQLInterruptedException,
                                SQLShutdownException,
                                SQLException

Returns a Connection (potentially from a shared resource pool). This connection may be checked out from a shared pool of connections or may be from some other source. When done with a Connection, be sure to close it to potentially return it to a pool. Due to the fact that this Connection might be in a shared pool, you must ensure that after you have called close, your code does not do anything more with this Connection or anything it created (like a Statement, or a ResultSet).

Calls to this method may block while waiting for a Connection if there is a maximum number of connections allowed in an underlying resource pool.

Parameters:

msTimeout - the maximum amount of time to wait for a connection to become available.

Throws:

SQLTimedOutException - if the specific maximum waiting time is exceeded and still no connection is available. Only some implementations (ones that support timeout detection) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simply catching SQLException.

SQLInterruptedException - if calling thread is interrupted while waiting for a connection to become available. Only some implementations (ones that support interrupt detection) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simple catching SQLException.

SQLShutdowException - if this ConnectionSource is shutdown while the caller is waiting (or was shutdown earlier). Only some implementations (ones that support being shutdown) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simple catching SQLException.

SQLException - if there is trouble getting a connection.

SQLShutdownException

getConnection

Connection getConnection()
                         throws SQLException

Returns a Connection (potentially from a shared resource pool). This connection may be checked out from a shared pool of connections or may be from some other source. When done with a Connection, be sure to close it to potentially return it to a pool. Due to the fact that this Connection might be in a shared pool, you must ensure that after you have called close, your code does not do anything more with this Connection or anything it created (like a Statement, or a ResultSet).

Calls to this method may block while waiting for a Connection if there is a maximum number of connections allowed in an underlying resource pool.

Throws:

SQLInterruptedException - if calling thread is interrupted while waiting for a connection to become available. Only some implementations (ones that support interrupt detection) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simple catching SQLException.

SQLShutdowException - if this ConnectionSource is shutdown while the caller is waiting (or was shutdown earlier). Only some implementations (ones that support being shutdown) throw this specific SQLException. This is a subclass of SQLException so callers can optionally ignore this specific kind of exception by simple catching SQLException.

SQLException - if there is trouble getting a connection.

shutdown

void shutdown()

Call this when done with the ConnectionSource to allow any underlying allocated resources to be released.