Since: API Level 1
public interface

DataSource

javax.sql.DataSource

Class Overview

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 different characteristics:

  1. Standard DataSource: produces standard Connection objects with no special features.
  2. Connection Pool DataSource: produces PooledConnection objects which require a connection pool manager as an intermediary component.
  3. Distributed transaction DataSource ("XADataSource"): produces XAConnection objects which can be used to handle distributed transactions which typically require an intermediary transaction manager component. XAConnection objects also 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.

Summary

Public Methods
abstract Connection getConnection(String theUsername, String thePassword)
Creates a connection to the database represented by this DataSource, using the supplied user name and password.
abstract Connection getConnection()
Creates a connection to the database represented by this DataSource.
abstract PrintWriter getLogWriter()
Gets the log writer for this DataSource.
abstract int getLoginTimeout()
Gets the login timeout value for this DataSource.
abstract void setLogWriter(PrintWriter theWriter)
Sets the log writer for this DataSource.
abstract void setLoginTimeout(int theTimeout)
Sets the login timeout value for this DataSource.

Public Methods

public abstract Connection getConnection (String theUsername, String thePassword)

Since: API Level 1

Creates a connection to the database represented by this DataSource, using the supplied user name and password.

Parameters
theUsername the a user name for the database login.
thePassword the password associated with the user identified by theUsername.
Returns
  • the Connection object which is the connection to the database.
Throws
SQLException if there is a problem accessing the database.

public abstract Connection getConnection ()

Since: API Level 1

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.

public abstract PrintWriter getLogWriter ()

Since: API Level 1

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

public abstract int getLoginTimeout ()

Since: API Level 1

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.

public abstract void setLogWriter (PrintWriter theWriter)

Since: API Level 1

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 a DataSource is created is null. Note that the log writer for a 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.

public abstract void setLoginTimeout (int theTimeout)

Since: API Level 1

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.