001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package javax.sql;
019:
020: import java.sql.SQLException;
021: import java.sql.Connection;
022: import java.io.PrintWriter;
023:
024: /**
025: * An interface for the creation of Connection objects which represent a
026: * connection to a database. This interface is an alternative to the
027: * <code>java.sql.DriverManager</code>.
028: * <p>
029: * A class which implements the DataSource interface is typically registered
030: * with a JNDI naming service directory and is retrieved from there by name.
031: * <p>
032: * The DataSource interface is typically implemented by the writer of a JDBC
033: * driver. There are three variants of the DataSource interface, which produce
034: * Connections with differing characteristics:
035: * <ol>
036: * <li>Standard DataSource, which produces standard Connection objects with no
037: * special features.</li>
038: * <li>Connection Pool DataSource, which produces PooledConnection objects
039: * which are able to participate in connection pooling, typically involving a
040: * connection pooling manager as an intermediary between applications and the
041: * database.</li>
042: * <li>Distributed transaction DataSource ("XADataSource"), which produces
043: * XAConnection objects which can be used to handle distributed transactions and
044: * which typically involve a transaction manager component in the system.
045: * XAConnection objects also typically provide connection pooling capabilities
046: * as well as distributed transaction capabilities. </li>
047: * </ol>
048: * <p>
049: * Note that a JDBC driver which is accessed via the DataSource interface is
050: * loaded via a JNDI lookup process. A driver loaded in this way does not
051: * register itself with the <code>DriverManager</code>.
052: */
053: public interface DataSource {
054:
055: /**
056: * Creates a connection to the database represented by this DataSource.
057: *
058: * @return a Connection object which is a connection to the database.
059: * @throws SQLException
060: * if there is a problem accessing the database.
061: */
062: public Connection getConnection() throws SQLException;
063:
064: /**
065: * Creates a connection to the database represented by this DataSource,
066: * using a supplied Username and Password,.
067: *
068: * @param theUsername
069: * a String containing a User Name for the database
070: * @param thePassword
071: * a String containing the Password for the user identified by
072: * <code>theUsername</code>
073: * @return a Connection object which is a connection to the database.
074: * @throws SQLException
075: * if there is a problem accessing the database.
076: */
077: public Connection getConnection(String theUsername,
078: String thePassword) throws SQLException;
079:
080: /**
081: * Gets the Login Timeout value for this DataSource. The Login Timeout is
082: * the maximum time in seconds that the DataSource will wait when opening a
083: * connection to a database. A Timeout value of 0 implies either the system
084: * default timeout value (if there is one) or that there is no timeout. The
085: * default value for the Login Timeout is 0.
086: *
087: * @return the Login Timeout value in seconds.
088: * @throws SQLException
089: * if there is a problem accessing the database.
090: */
091: public int getLoginTimeout() throws SQLException;
092:
093: /**
094: * Gets the Log Writer for this DataSource.
095: * <p>
096: * The Log Writer is a stream to which all log and trace messages are sent
097: * from this DataSource. The Log Writer can be null, in which case, log and
098: * trace capture is disabled. The default value for the Log Writer when an
099: * DataSource is created is null. Note that the Log Writer for an DataSource
100: * is not the same as the Log Writer used by a <code>DriverManager</code>.
101: *
102: * @return a PrintWriter which is the Log Writer for this DataSource. Can be
103: * null, in which case log writing is disabled for this DataSource.
104: * @throws SQLException
105: * if there is a problem accessing the database.
106: */
107: public PrintWriter getLogWriter() throws SQLException;
108:
109: /**
110: * Sets the Login Timeout value for this DataSource. The Login Timeout is
111: * the maximum time in seconds that the DataSource will wait when opening a
112: * connection to a database. A Timeout value of 0 implies either the system
113: * default timeout value (if there is one) or that there is no timeout. The
114: * default value for the Login Timeout is 0.
115: *
116: * @param theTimeout
117: * the new Login Timeout value in seconds.
118: * @throws SQLException
119: * if there is a problem accessing the database.
120: */
121: public void setLoginTimeout(int theTimeout) throws SQLException;
122:
123: /**
124: * Sets the Log Writer for this DataSource.
125: * <p>
126: * The Log Writer is a stream to which all log and trace messages are sent
127: * from this DataSource. The Log Writer can be null, in which case, log and
128: * trace capture is disabled. The default value for the Log Writer when an
129: * DataSource is created is null. Note that the Log Writer for an DataSource
130: * is not the same as the Log Writer used by a <code>DriverManager</code>.
131: *
132: * @param theWriter
133: * a PrintWriter to use as the Log Writer for this DataSource.
134: * @throws SQLException
135: * if there is a problem accessing the database.
136: */
137: public void setLogWriter(PrintWriter theWriter) throws SQLException;
138: }
|