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.SQLException;
026:
027: /**
028: * A factory for XAConnection objects. An object that implements the XADataSource interface
029: * is typically registered with a JNDI service provider.
030: */
031: public interface XADataSource {
032:
033: /**
034: * <p>Get the log writer for this data source.</p>
035: *
036: * <p>The log writer is a character output stream to which all logging and tracing messages
037: * for this data source object instance will be printed. This includes messages printed by the
038: * methods of this object, messages printed by methods of other objects manufactured by this object,
039: * and so on. Messages printed to a data source specific log writer are not printed to the log writer
040: * associated with the java.sql.Drivermanager class. When a data source object is created the log
041: * writer is initially null, in other words, logging is disabled.</p>
042: *
043: * @return the log writer for this data source, null if disabled
044: * @exception SQLException - if a database-access error occurs.
045: */
046: public PrintWriter getLogWriter() throws SQLException;
047:
048: /**
049: * Gets the maximum time in seconds that this data source can wait while attempting to connect to
050: * a database. A value of zero means that the timeout is the default system timeout if there is one;
051: * otherwise it means that there is no timeout. When a data source object is created the login timeout
052: * is initially zero.
053: *
054: * @return the data source login time limit
055: * @exception SQLException - if a database-access error occurs.
056: */
057: public int getLoginTimeout() throws SQLException;
058:
059: /**
060: * Attempt to establish a database connection.
061: *
062: * @return a Connection to the database
063: * @exception SQLException - if a database-access error occurs.
064: */
065: public XAConnection getXAConnection() throws SQLException;
066:
067: /**
068: * Attempt to establish a database connection.
069: *
070: * @param user - the database user on whose behalf the Connection is being made
071: * @param password - the user's password
072: * @return a Connection to the database
073: * @exception SQLException - if a database-access error occurs.
074: */
075: public XAConnection getXAConnection(String user, String password)
076: 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
082: * for this data source object instance will be printed. This includes messages printed by the
083: * methods of this object, messages printed by methods of other objects manufactured by this object,
084: * and so on. Messages printed to a data source specific log writer are not printed to the log writer
085: * associated with the java.sql.Drivermanager class. When a data source object is created the log writer
086: * is initially null, in other words, logging is disabled.</p>
087: *
088: * @param printWriter - the new log writer; to disable, set to null
089: * @exception SQLException - if a database-access error occurs.
090: */
091: public void setLogWriter(PrintWriter printWriter)
092: throws SQLException;
093:
094: /**
095: * Sets the maximum time in seconds that this data source will wait while attempting to connect
096: * to a database. A value of zero specifies that the timeout is the default system timeout if there
097: * is one; otherwise it specifies that there is no timeout. When a data source object is created the
098: * login timeout is initially zero.
099: *
100: * @param sec - the data source login time limit
101: * @exception SQLException - if a database-access error occurs.
102: */
103: public void setLoginTimeout(int sec) throws SQLException;
104: }
|