001: /*
002: Copyright (C) 2007 MySQL AB
003:
004: This program is free software; you can redistribute it and/or modify
005: it under the terms of version 2 of the GNU General Public License as
006: published by the Free Software Foundation.
007:
008: There are special exceptions to the terms and conditions of the GPL
009: as it is applied to this software. View the full text of the
010: exception in file EXCEPTIONS-CONNECTOR-J in the directory of this
011: software distribution.
012:
013: This program is distributed in the hope that it will be useful,
014: but WITHOUT ANY WARRANTY; without even the implied warranty of
015: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
016: GNU General Public License for more details.
017:
018: You should have received a copy of the GNU General Public License
019: along with this program; if not, write to the Free Software
020: Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
021:
022: */
023:
024: package com.mysql.jdbc;
025:
026: import java.sql.SQLException;
027: import java.sql.SQLClientInfoException;
028: import java.util.Properties;
029:
030: import com.mysql.jdbc.exceptions.NotYetImplementedException;
031:
032: /**
033: * Classes that implement this interface and provide a no-args constructor
034: * can be used by the driver to store and retrieve client information and/or
035: * labels.
036: *
037: * The driver will create an instance for each Connection instance, and call
038: * initialize() once and only once. When the connection is closed, destroy()
039: * will be called, and the provider is expected to clean up any resources at
040: * this time.
041: *
042: * @version $Id: $
043: */
044: public interface JDBC4ClientInfoProvider {
045: /**
046: * Called once by the driver when it needs to configure the provider.
047: *
048: * @param conn the connection that the provider belongs too.
049: * @param configurationProps a java.util.Properties instance that contains
050: * configuration information for the connection.
051: * @throws SQLException if initialization fails.
052: */
053: public void initialize(java.sql.Connection conn,
054: Properties configurationProps) throws SQLException;
055:
056: /**
057: * Called once by the driver when the connection this provider instance
058: * belongs to is being closed.
059: *
060: * Implementations are expected to clean up and resources at this point
061: * in time.
062: *
063: * @throws SQLException if an error occurs.
064: */
065: public void destroy() throws SQLException;
066:
067: /**
068: * Returns the client info for the connection that this provider
069: * instance belongs to. The connection instance is passed as an argument
070: * for convenience's sake.
071: *
072: * Providers can use the connection to communicate with the database,
073: * but it will be within the scope of any ongoing transactions, so therefore
074: * implementations should not attempt to change isolation level, autocommit settings
075: * or call rollback() or commit() on the connection.
076: *
077: * @param conn
078: * @return
079: * @throws SQLException
080: *
081: * @see java.sql.Connection#getClientInfo()
082: */
083: public Properties getClientInfo(java.sql.Connection conn)
084: throws SQLException;
085:
086: /**
087: * Returns the client info for the connection that this provider
088: * instance belongs to. The connection instance is passed as an argument
089: * for convenience's sake.
090: *
091: * Providers can use the connection to communicate with the database,
092: * but it will be within the scope of any ongoing transactions, so therefore
093: * implementations should not attempt to change isolation level, autocommit settings
094: * or call rollback() or commit() on the connection.
095: *
096: * @param conn
097: * @return
098: * @throws SQLException
099: *
100: * @see java.sql.Connection#getClientInfo(java.lang.String)
101: */
102: public String getClientInfo(java.sql.Connection conn, String name)
103: throws SQLException;
104:
105: /**
106: * Sets the client info for the connection that this provider
107: * instance belongs to. The connection instance is passed as an argument
108: * for convenience's sake.
109: *
110: * Providers can use the connection to communicate with the database,
111: * but it will be within the scope of any ongoing transactions, so therefore
112: * implementations should not attempt to change isolation level, autocommit settings
113: * or call rollback() or commit() on the connection.
114: *
115: * @param conn
116: * @return
117: * @throws SQLException
118: *
119: * @see java.sql.Connection#setClientInfo(java.util.Properties)
120: */
121: public void setClientInfo(java.sql.Connection conn,
122: Properties properties) throws SQLClientInfoException;
123:
124: /**
125: * Sets the client info for the connection that this provider
126: * instance belongs to. The connection instance is passed as an argument
127: * for convenience's sake.
128: *
129: * Providers can use the connection to communicate with the database,
130: * but it will be within the scope of any ongoing transactions, so therefore
131: * implementations should not attempt to change isolation level, autocommit settings
132: * or call rollback() or commit() on the connection.
133: *
134: * @param conn
135: * @return
136: * @throws SQLException
137: *
138: * @see java.sql.Connection#setClientInfo(java.lang.String,java.lang.String)
139: */
140: public void setClientInfo(java.sql.Connection conn, String name,
141: String value) throws SQLClientInfoException;
142: }
| 