001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.sql;
023:
024: import java.io.PrintWriter;
025: import java.sql.Connection;
026: import java.sql.SQLException;
027:
028: /**
029: * A DataSource object is a factory for Connection objects. An object that implements the DataSource interface
030: * will typically be registered with a JNDI service provider. A JDBC driver that is accessed via the DataSource
031: * API does not automatically register itself with the DriverManager.
032: */
033: public interface DataSource {
034:
035: /**
036: * Attempt to establish a database connection.
037: *
038: * @return a Connection to the database
039: * @exception SQLException - if a database-access error occurs.
040: */
041: public Connection getConnection() throws SQLException;
042:
043: /**
044: * Attempt to establish a database connection.
045: *
046: * @param user - the database user on whose behalf the Connection is being made
047: * @param password - the user's password
048: * @return a Connection to the database
049: * @exception SQLException - if a database-access error occurs.
050: */
051: public Connection getConnection(String user, String password)
052: throws SQLException;
053:
054: /**
055: * <p>Get the log writer for this data source.</p>
056: *
057: * <p>The log writer is a character output stream to which all logging and tracing messages for this data
058: * source object instance will be printed. This includes messages printed by the methods of this object,
059: * messages printed by methods of other objects manufactured by this object, and so on. Messages printed to
060: * a data source specific log writer are not printed to the log writer associated with the java.sql.Drivermanager class.
061: * When a DataSource object is created the log writer is initially null, in other words, logging is disabled.</p>
062: *
063: * @return the log writer for this data source, null if disabled
064: * @exception SQLException - if a database-access error occurs.
065: */
066: public PrintWriter getLogWriter() throws SQLException;
067:
068: /**
069: * Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.
070: * A value of zero means that the timeout is the default system timeout if there is one; otherwise it means that
071: * there is no timeout. When a DataSource object is created the login timeout is initially zero.
072: *
073: * @return the data source login time limit
074: * @exception SQLException - if a database access error occurs.
075: */
076: public int getLoginTimeout() throws SQLException;
077:
078: /**
079: * <p>Set the log writer for this data source.</p>
080: *
081: * <p>The log writer is a character output stream to which all logging and tracing messages for this data
082: * source object instance will be printed. This includes messages printed by the methods of this object,
083: * messages printed by methods of other objects manufactured by this object, and so on. Messages printed to
084: * a data source specific log writer are not printed to the log writer associated with the java.sql.Drivermanager class.
085: * When a DataSource object is created the log writer is initially null, in other words, logging is disabled.</p>
086: *
087: * @param printWriter - the new log writer; to disable, set to null
088: * @exception SQLException - if a database-access error occurs.
089: */
090: public void setLogWriter(PrintWriter printWriter)
091: throws SQLException;
092:
093: /**
094: * Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.
095: * A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies
096: * that there is no timeout. When a DataSource object is created the login timeout is initially zero.
097: *
098: * @param seconds - the data source login time limit
099: * @exception SQLException - if a database access error occurs.
100: */
101: public void setLoginTimeout(int seconds) throws SQLException;
102: }
|