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.util.TimeZone;
028:
029: import com.mysql.jdbc.log.Log;
030:
031: /**
032: * This interface contains methods that are considered the "vendor extension"
033: * to the JDBC API for MySQL's implementation of java.sql.Connection.
034: *
035: * For those looking further into the driver implementation, it is not
036: * an API that is used for plugability of implementations inside our driver
037: * (which is why there are still references to ConnectionImpl throughout the
038: * code).
039: *
040: * @version $Id: $
041: *
042: */
043: public interface Connection extends java.sql.Connection,
044: ConnectionProperties {
045:
046: /**
047: * Changes the user on this connection by performing a re-authentication. If
048: * authentication fails, the connection will remain under the context of the
049: * current user.
050: *
051: * @param userName
052: * the username to authenticate with
053: * @param newPassword
054: * the password to authenticate with
055: * @throws SQLException
056: * if authentication fails, or some other error occurs while
057: * performing the command.
058: */
059: public abstract void changeUser(String userName, String newPassword)
060: throws SQLException;
061:
062: public abstract void clearHasTriedMaster();
063:
064: /**
065: * Prepares a statement on the client, using client-side emulation
066: * (irregardless of the configuration property 'useServerPrepStmts')
067: * with the same semantics as the java.sql.Connection.prepareStatement()
068: * method with the same argument types.
069: *
070: * @see java.sql.Connection#prepareStatement(String)
071: */
072: public abstract PreparedStatement clientPrepareStatement(String sql)
073: throws SQLException;
074:
075: /**
076: * Prepares a statement on the client, using client-side emulation
077: * (irregardless of the configuration property 'useServerPrepStmts')
078: * with the same semantics as the java.sql.Connection.prepareStatement()
079: * method with the same argument types.
080: *
081: * @see java.sql.Connection#prepareStatement(String, int)
082: */
083: public abstract java.sql.PreparedStatement clientPrepareStatement(
084: String sql, int autoGenKeyIndex) throws SQLException;
085:
086: /**
087: * Prepares a statement on the client, using client-side emulation
088: * (irregardless of the configuration property 'useServerPrepStmts')
089: * with the same semantics as the java.sql.Connection.prepareStatement()
090: * method with the same argument types.
091: *
092: * @see java.sql.Connection#prepareStatement(String, int, int)
093: */
094: public abstract PreparedStatement clientPrepareStatement(
095: String sql, int resultSetType, int resultSetConcurrency)
096: throws SQLException;
097:
098: /**
099: * Prepares a statement on the client, using client-side emulation
100: * (irregardless of the configuration property 'useServerPrepStmts')
101: * with the same semantics as the java.sql.Connection.prepareStatement()
102: * method with the same argument types.
103: *
104: * @see java.sql.Connection#prepareStatement(String, int[])
105: */
106: public abstract java.sql.PreparedStatement clientPrepareStatement(
107: String sql, int[] autoGenKeyIndexes) throws SQLException;
108:
109: /**
110: * Prepares a statement on the client, using client-side emulation
111: * (irregardless of the configuration property 'useServerPrepStmts')
112: * with the same semantics as the java.sql.Connection.prepareStatement()
113: * method with the same argument types.
114: *
115: * @see java.sql.Connection#prepareStatement(String, String[])
116: */
117: public abstract java.sql.PreparedStatement clientPrepareStatement(
118: String sql, String[] autoGenKeyColNames)
119: throws SQLException;
120:
121: /**
122: * Returns the number of statements active on this connection, which
123: * haven't been .close()d.
124: */
125: public abstract int getActiveStatementCount();
126:
127: /**
128: * Reports how long this connection has been idle.
129: * This time (reported in milliseconds) is updated once a query has
130: * completed.
131: *
132: * @return number of ms that this connection has been idle, 0 if the driver
133: * is busy retrieving results.
134: */
135: public abstract long getIdleFor();
136:
137: /**
138: * Returns the log mechanism that should be used to log information from/for
139: * this Connection.
140: *
141: * @return the Log instance to use for logging messages.
142: * @throws SQLException
143: * if an error occurs
144: */
145: public abstract Log getLog() throws SQLException;
146:
147: /**
148: * Returns the server's character set
149: *
150: * @return the server's character set.
151: */
152: public abstract String getServerCharacterEncoding();
153:
154: /**
155: * Returns the TimeZone that represents the configured
156: * timezone for the server.
157: */
158: public abstract TimeZone getServerTimezoneTZ();
159:
160: /**
161: * Returns the comment that will be prepended to all statements
162: * sent to the server.
163: *
164: * @return the comment that will be prepended to all statements
165: * sent to the server.
166: */
167: public abstract String getStatementComment();
168:
169: /**
170: * Has this connection tried to execute a query on the "master"
171: * server (first host in a multiple host list).
172: */
173: public abstract boolean hasTriedMaster();
174:
175: /**
176: * Is this connection currently a participant in an XA transaction?
177: */
178: public abstract boolean isInGlobalTx();
179:
180: /**
181: * Is this connection connected to the first host in the list if
182: * there is a list of servers in the URL?
183: *
184: * @return true if this connection is connected to the first in
185: * the list.
186: */
187: public abstract boolean isMasterConnection();
188:
189: /**
190: * Is the server in a sql_mode that doesn't allow us to use \\ to escape
191: * things?
192: *
193: * @return Returns the noBackslashEscapes.
194: */
195: public abstract boolean isNoBackslashEscapesSet();
196:
197: /**
198: * Is the server configured to use lower-case table names only?
199: *
200: * @return true if lower_case_table_names is 'on'
201: */
202: public abstract boolean lowerCaseTableNames();
203:
204: /**
205: * Does the server this connection is connected to
206: * support unicode?
207: */
208: public abstract boolean parserKnowsUnicode();
209:
210: /**
211: * Detect if the connection is still good by sending a ping command
212: * to the server.
213: *
214: * @throws SQLException
215: * if the ping fails
216: */
217: public abstract void ping() throws SQLException;
218:
219: /**
220: * Resets the server-side state of this connection. Doesn't work for MySQL
221: * versions older than 4.0.6 or if isParanoid() is set (it will become a
222: * no-op in these cases). Usually only used from connection pooling code.
223: *
224: * @throws SQLException
225: * if the operation fails while resetting server state.
226: */
227: public abstract void resetServerState() throws SQLException;
228:
229: /**
230: * Prepares a statement on the server (irregardless of the
231: * configuration property 'useServerPrepStmts') with the same semantics
232: * as the java.sql.Connection.prepareStatement() method with the
233: * same argument types.
234: *
235: * @see java.sql.Connection#prepareStatement(String)
236: */
237: public abstract ServerPreparedStatement serverPrepareStatement(
238: String sql) throws SQLException;
239:
240: /**
241: * Prepares a statement on the server (irregardless of the
242: * configuration property 'useServerPrepStmts') with the same semantics
243: * as the java.sql.Connection.prepareStatement() method with the
244: * same argument types.
245: *
246: * @see java.sql.Connection#prepareStatement(String, int)
247: */
248: public abstract java.sql.PreparedStatement serverPrepareStatement(
249: String sql, int autoGenKeyIndex) throws SQLException;
250:
251: /**
252: * Prepares a statement on the server (irregardless of the
253: * configuration property 'useServerPrepStmts') with the same semantics
254: * as the java.sql.Connection.prepareStatement() method with the
255: * same argument types.
256: *
257: * @see java.sql.Connection#prepareStatement(String, int, int)
258: */
259: public abstract java.sql.PreparedStatement serverPrepareStatement(
260: String sql, int resultSetType, int resultSetConcurrency)
261: throws SQLException;
262:
263: /**
264: * Prepares a statement on the server (irregardless of the
265: * configuration property 'useServerPrepStmts') with the same semantics
266: * as the java.sql.Connection.prepareStatement() method with the
267: * same argument types.
268: *
269: * @see java.sql.Connection#prepareStatement(String, int, int, int)
270: */
271: public abstract java.sql.PreparedStatement serverPrepareStatement(
272: String sql, int resultSetType, int resultSetConcurrency,
273: int resultSetHoldability) throws SQLException;
274:
275: /**
276: * Prepares a statement on the server (irregardless of the
277: * configuration property 'useServerPrepStmts') with the same semantics
278: * as the java.sql.Connection.prepareStatement() method with the
279: * same argument types.
280: *
281: * @see java.sql.Connection#prepareStatement(String, int[])
282: */
283: public abstract java.sql.PreparedStatement serverPrepareStatement(
284: String sql, int[] autoGenKeyIndexes) throws SQLException;
285:
286: /**
287: * Prepares a statement on the server (irregardless of the
288: * configuration property 'useServerPrepStmts') with the same semantics
289: * as the java.sql.Connection.prepareStatement() method with the
290: * same argument types.
291: *
292: * @see java.sql.Connection#prepareStatement(String, String[])
293: */
294: public abstract java.sql.PreparedStatement serverPrepareStatement(
295: String sql, String[] autoGenKeyColNames)
296: throws SQLException;
297:
298: /**
299: * @param failedOver
300: * The failedOver to set.
301: */
302: public abstract void setFailedOver(boolean flag);
303:
304: /**
305: * @param preferSlaveDuringFailover
306: * The preferSlaveDuringFailover to set.
307: */
308: public abstract void setPreferSlaveDuringFailover(boolean flag);
309:
310: /**
311: * Sets the comment that will be prepended to all statements
312: * sent to the server. Do not use slash-star or star-slash tokens
313: * in the comment as these will be added by the driver itself.
314: *
315: * @param comment the comment that will be prepended to all statements
316: * sent to the server.
317: */
318: public abstract void setStatementComment(String comment);
319:
320: /**
321: * Used by MiniAdmin to shutdown a MySQL server
322: *
323: * @throws SQLException
324: * if the command can not be issued.
325: */
326: public abstract void shutdownServer() throws SQLException;
327:
328: /**
329: * Does the server this connection is connected to
330: * support quoted isolation levels?
331: */
332: public abstract boolean supportsIsolationLevel();
333:
334: /**
335: * Does the server this connection is connected to
336: * support quoted identifiers?
337: */
338: public abstract boolean supportsQuotedIdentifiers();
339:
340: /**
341: * Does the server this connection is connected to
342: * support quoted identifiers?
343: */
344: public abstract boolean supportsTransactions();
345:
346: /**
347: * Does the server this connection is connected to
348: * meet or exceed the given version?
349: */
350: public abstract boolean versionMeetsMinimum(int major, int minor,
351: int subminor) throws SQLException;
352:
353: }
|