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