/* * @(#)DataSource.java 1.9 03/12/19 * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package javax.sql; import java.sql.Connection; import java.sql.SQLException; /** *
A factory for connections to the physical data source that this
* DataSource
object represents. An alternative to the
* DriverManager
facility, a DataSource
object
* is the preferred means of getting a connection. An object that implements
* the DataSource
interface will typically be
* registered with a naming service based on the
* JavaTM Naming and Directory (JNDI) API.
*
* The DataSource
interface is implemented by a driver vendor.
* There are three types of implementations:
*
Connection
* object
* Connection
* object that will automatically participate in connection pooling. This
* implementation works with a middle-tier connection pooling manager.
* Connection
object that may be used for distributed
* transactions and almost always participates in connection pooling.
* This implementation works with a middle-tier
* transaction manager and almost always with a connection
* pooling manager.
*
* A DataSource
object has properties that can be modified
* when necessary. For example, if the data source is moved to a different
* server, the property for the server can be changed. The benefit is that
* because the data source's properties can be changed, any code accessing
* that data source does not need to be changed.
*
* A driver that is accessed via a DataSource
object does not
* register itself with the DriverManager
. Rather, a
* DataSource
object is retrieved though a lookup operation
* and then used to create a Connection
object. With a basic
* implementation, the connection obtained through a DataSource
* object is identical to a connection obtained through the
* DriverManager
facility.
*
* @since 1.4
*/
public interface DataSource {
/**
*
Attempts to establish a connection with the data source that
* this DataSource
object represents.
*
* @return a connection to the data source
* @exception SQLException if a database access error occurs
*/
Connection getConnection() throws SQLException;
/**
*
Attempts to establish a connection with the data source that
* this DataSource
object represents.
*
* @param username the database user on whose behalf the connection is
* being made
* @param password the user's password
* @return a connection to the data source
* @exception SQLException if a database access error occurs
*/
Connection getConnection(String username, String password)
throws SQLException;
/**
*
Retrieves the log writer for this DataSource
* object.
*
*
The log writer is a character output stream to which all logging
* and tracing messages for this data source will be
* printed. This includes messages printed by the methods of this
* object, messages printed by methods of other objects manufactured
* by this object, and so on. Messages printed to a data source
* specific log writer are not printed to the log writer associated
* with the java.sql.Drivermanager
class. When a
* DataSource
object is
* created, the log writer is initially null; in other words, the
* default is for logging to be disabled.
*
* @return the log writer for this data source or null if
* logging is disabled
* @exception SQLException if a database access error occurs
* @see #setLogWriter
*/
java.io.PrintWriter getLogWriter() throws SQLException;
/**
*
Sets the log writer for this DataSource
* object to the given java.io.PrintWriter
object.
*
*
The log writer is a character output stream to which all logging
* and tracing messages for this data source will be
* printed. This includes messages printed by the methods of this
* object, messages printed by methods of other objects manufactured
* by this object, and so on. Messages printed to a data source-
* specific log writer are not printed to the log writer associated
* with the java.sql.Drivermanager
class. When a
* DataSource
object is created the log writer is
* initially null; in other words, the default is for logging to be
* disabled.
*
* @param out the new log writer; to disable logging, set to null
* @exception SQLException if a database access error occurs
* @see #getLogWriter
*/
void setLogWriter(java.io.PrintWriter out) throws SQLException;
/**
*
Sets the maximum time in seconds that this data source will wait
* while attempting to connect to a database. A value of zero
* specifies that the timeout is the default system timeout
* if there is one; otherwise, it specifies that there is no timeout.
* When a DataSource
object is created, the login timeout is
* initially zero.
*
* @param seconds the data source login time limit
* @exception SQLException if a database access error occurs.
* @see #getLoginTimeout
*/
void setLoginTimeout(int seconds) throws SQLException;
/**
* Gets the maximum time in seconds that this data source can wait
* while attempting to connect to a database. A value of zero
* means that the timeout is the default system timeout
* if there is one; otherwise, it means that there is no timeout.
* When a DataSource
object is created, the login timeout is
* initially zero.
*
* @return the data source login time limit
* @exception SQLException if a database access error occurs.
* @see #setLoginTimeout
*/
int getLoginTimeout() throws SQLException;
}