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.io.PrintWriter;
022:
023: /**
024: * An interface for the creation of PooledConnection objects. Used internally
025: * within the package.
026: * <p>
027: * A class which implements the ConnectionPoolDataSource interface is typically
028: * registered with a JNDI naming service directory and is retrieved from there
029: * by name.
030: */
031: public interface ConnectionPoolDataSource {
032:
033: /**
034: * Gets the Login Timeout value for this ConnectionPoolDataSource. The Login
035: * Timeout is the maximum time in seconds that the ConnectionPoolDataSource
036: * will wait when opening a connection to a database. A Timeout value of 0
037: * implies either the system default timeout value (if there is one) or that
038: * there is no timeout. The default value for the Login Timeout is 0.
039: *
040: * @return the Login Timeout value in seconds.
041: * @throws SQLException
042: * if there is a problem accessing the database.
043: */
044: public int getLoginTimeout() throws SQLException;
045:
046: /**
047: * Gets the Log Writer for this ConnectionPoolDataSource.
048: * <p>
049: * The Log Writer is a stream to which all log and trace messages are sent
050: * from this ConnectionPoolDataSource. The Log Writer can be null, in which
051: * case, log and trace capture is disabled. The default value for the Log
052: * Writer when an ConnectionPoolDataSource is created is null. Note that the
053: * Log Writer for an ConnectionPoolDataSource is not the same as the Log
054: * Writer used by a <code>DriverManager</code>.
055: *
056: * @return a PrintWriter which is the Log Writer for this
057: * ConnectionPoolDataSource. Can be null, in which case log writing
058: * is disabled for this ConnectionPoolDataSource.
059: * @throws SQLException
060: * if there is a problem accessing the database.
061: */
062: public PrintWriter getLogWriter() throws SQLException;
063:
064: /**
065: * Create a connection to a database which can then be used as a pooled
066: * connection.
067: *
068: * @return a PooledConnection which represents the connection to the
069: * database
070: * @throws SQLException
071: * if there is a problem accessing the database.
072: */
073: public PooledConnection getPooledConnection() throws SQLException;
074:
075: /**
076: * Create a connection to a database, using a supplied Username and
077: * Password, which can then be used as a pooled connection.
078: *
079: * @param theUser
080: * a String containing a User Name for the database
081: * @param thePassword
082: * a String containing the Password for the user identified by
083: * <code>theUser</code>
084: * @return a PooledConnection which represents the connection to the
085: * database
086: * @throws SQLException
087: * if there is a problem accessing the database.
088: */
089: public PooledConnection getPooledConnection(String theUser,
090: String thePassword) throws SQLException;
091:
092: /**
093: * Sets the Login Timeout value for this ConnectionPoolDataSource. The Login
094: * Timeout is the maximum time in seconds that the ConnectionPoolDataSource
095: * will wait when opening a connection to a database. A Timeout value of 0
096: * implies either the system default timeout value (if there is one) or that
097: * there is no timeout. The default value for the Login Timeout is 0.
098: *
099: * @param theTimeout
100: * the new Login Timeout value in seconds.
101: * @throws SQLException
102: * if there is a problem accessing the database.
103: */
104: public void setLoginTimeout(int theTimeout) throws SQLException;
105:
106: /**
107: * Sets the Log Writer for this ConnectionPoolDataSource.
108: * <p>
109: * The Log Writer is a stream to which all log and trace messages are sent
110: * from this ConnectionPoolDataSource. The Log Writer can be null, in which
111: * case, log and trace capture is disabled. The default value for the Log
112: * Writer when an ConnectionPoolDataSource is created is null. Note that the
113: * Log Writer for an ConnectionPoolDataSource is not the same as the Log
114: * Writer used by a <code>DriverManager</code>.
115: *
116: * @param theWriter
117: * a PrintWriter to use as the Log Writer for this
118: * ConnectionPoolDataSource.
119: * @throws SQLException
120: * if there is a problem accessing the database.
121: */
122: public void setLogWriter(PrintWriter theWriter) throws SQLException;
123: }
|