/*
* @(#)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;
/**
* <p>A factory for connections to the physical data source that this
* <code>DataSource</code> object represents. An alternative to the
* <code>DriverManager</code> facility, a <code>DataSource</code> object
* is the preferred means of getting a connection. An object that implements
* the <code>DataSource</code> interface will typically be
* registered with a naming service based on the
* Java<sup><font size=-2>TM</font></sup> Naming and Directory (JNDI) API.
* <P>
* The <code>DataSource</code> interface is implemented by a driver vendor.
* There are three types of implementations:
* <OL>
* <LI>Basic implementation -- produces a standard <code>Connection</code>
* object
* <LI>Connection pooling implementation -- produces a <code>Connection</code>
* object that will automatically participate in connection pooling. This
* implementation works with a middle-tier connection pooling manager.
* <LI>Distributed transaction implementation -- produces a
* <code>Connection</code> 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.
* </OL>
* <P>
* A <code>DataSource</code> 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.
* <P>
* A driver that is accessed via a <code>DataSource</code> object does not
* register itself with the <code>DriverManager</code>. Rather, a
* <code>DataSource</code> object is retrieved though a lookup operation
* and then used to create a <code>Connection</code> object. With a basic
* implementation, the connection obtained through a <code>DataSource</code>
* object is identical to a connection obtained through the
* <code>DriverManager</code> facility.
*
* @since 1.4
*/
public interface DataSource {
/**
* <p>Attempts to establish a connection with the data source that
* this <code>DataSource</code> object represents.
*
* @return a connection to the data source
* @exception SQLException if a database access error occurs
*/
Connection getConnection() throws SQLException;
/**
* <p>Attempts to establish a connection with the data source that
* this <code>DataSource</code> 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;
/**
* <p>Retrieves the log writer for this <code>DataSource</code>
* object.
*
* <p>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 <code>java.sql.Drivermanager</code> class. When a
* <code>DataSource</code> 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;
/**
* <p>Sets the log writer for this <code>DataSource</code>
* object to the given <code>java.io.PrintWriter</code> object.
*
* <p>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 <code>java.sql.Drivermanager</code> class. When a
* <code>DataSource</code> 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;
/**
* <p>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 <code>DataSource</code> 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 <code>DataSource</code> 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;
}
|
