/* * @(#)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: *

    *
  1. Basic implementation -- produces a standard Connection * object *
  2. Connection pooling implementation -- produces a Connection * object that will automatically participate in connection pooling. This * implementation works with a middle-tier connection pooling manager. *
  3. Distributed transaction implementation -- produces a * 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; }