javax.sql
Interface DataSource

public interface DataSource

An interface for the creation of Connection objects which represent a connection to a database. This interface is an alternative to the java.sql.DriverManager.

A class which implements the DataSource interface is typically registered with a JNDI naming service directory and is retrieved from there by name.

The DataSource interface is typically implemented by the writer of a JDBC driver. There are three variants of the DataSource interface, which produce Connections with differing characteristics:

1. Standard DataSource, which produces standard Connection objects with no special features.
2. Connection Pool DataSource, which produces PooledConnection objects which are able to participate in connection pooling, typically involving a connection pooling manager as an intermediary between applications and the database.
3. Distributed transaction DataSource ("XADataSource"), which produces XAConnection objects which can be used to handle distributed transactions and which typically involve a transaction manager component in the system. XAConnection objects also typically provide connection pooling capabilities as well as distributed transaction capabilities.

Note that a JDBC driver which is accessed via the DataSource interface is loaded via a JNDI lookup process. A driver loaded in this way does not register itself with the DriverManager.

Method Summary

Connection	getConnection() Creates a connection to the database represented by this DataSource.
Connection	getConnection(String theUsername, String thePassword) Creates a connection to the database represented by this DataSource, using a supplied Username and Password,.
int	getLoginTimeout() Gets the Login Timeout value for this DataSource.
PrintWriter	getLogWriter() Gets the Log Writer for this DataSource.
void	setLoginTimeout(int theTimeout) Sets the Login Timeout value for this DataSource.
void	setLogWriter(PrintWriter theWriter) Sets the Log Writer for this DataSource.

Method Detail

getConnection

Connection getConnection()
                         throws SQLException

Creates a connection to the database represented by this DataSource.

Returns:

a Connection object which is a connection to the database.

Throws:

SQLException - if there is a problem accessing the database.

getConnection

Connection getConnection(String theUsername,
                         String thePassword)
                         throws SQLException

Creates a connection to the database represented by this DataSource, using a supplied Username and Password,.

Parameters:

theUsername - a String containing a User Name for the database

thePassword - a String containing the Password for the user identified by theUsername

Returns:

a Connection object which is a connection to the database.

Throws:

SQLException - if there is a problem accessing the database.

getLoginTimeout

int getLoginTimeout()
                    throws SQLException

Gets the Login Timeout value for this DataSource. The Login Timeout is the maximum time in seconds that the DataSource will wait when opening a connection to a database. A Timeout value of 0 implies either the system default timeout value (if there is one) or that there is no timeout. The default value for the Login Timeout is 0.

Returns:

the Login Timeout value in seconds.

Throws:

SQLException - if there is a problem accessing the database.

getLogWriter

PrintWriter getLogWriter()
                         throws SQLException

Gets the Log Writer for this DataSource.

The Log Writer is a stream to which all log and trace messages are sent from this DataSource. The Log Writer can be null, in which case, log and trace capture is disabled. The default value for the Log Writer when an DataSource is created is null. Note that the Log Writer for an DataSource is not the same as the Log Writer used by a DriverManager.

Returns:

a PrintWriter which is the Log Writer for this DataSource. Can be null, in which case log writing is disabled for this DataSource.

Throws:

SQLException - if there is a problem accessing the database.

setLoginTimeout

void setLoginTimeout(int theTimeout)
                     throws SQLException

Sets the Login Timeout value for this DataSource. The Login Timeout is the maximum time in seconds that the DataSource will wait when opening a connection to a database. A Timeout value of 0 implies either the system default timeout value (if there is one) or that there is no timeout. The default value for the Login Timeout is 0.

Parameters:

theTimeout - the new Login Timeout value in seconds.

Throws:

SQLException - if there is a problem accessing the database.

setLogWriter

void setLogWriter(PrintWriter theWriter)
                  throws SQLException

Sets the Log Writer for this DataSource.

The Log Writer is a stream to which all log and trace messages are sent from this DataSource. The Log Writer can be null, in which case, log and trace capture is disabled. The default value for the Log Writer when an DataSource is created is null. Note that the Log Writer for an DataSource is not the same as the Log Writer used by a DriverManager.

Parameters:

theWriter - a PrintWriter to use as the Log Writer for this DataSource.

Throws:

SQLException - if there is a problem accessing the database.