1 /*
2 Copyright 2007 MySQL AB, 2008 Sun Microsystems
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of version 2 of the GNU General Public License as
6 published by the Free Software Foundation.
7
8 There are special exceptions to the terms and conditions of the GPL
9 as it is applied to this software. View the full text of the
10 exception in file EXCEPTIONS-CONNECTOR-J in the directory of this
11 software distribution.
12
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
17
18 You should have received a copy of the GNU General Public License
19 along with this program; if not, write to the Free Software
20 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21
22 */
23
24 package com.mysql.jdbc;
25
26 import java.sql.SQLException;
27 import java.util.Properties;
28 import java.util.TimeZone;
29
30 import com.mysql.jdbc.log.Log;
31
32 /**
33 * This interface contains methods that are considered the "vendor extension"
34 * to the JDBC API for MySQL's implementation of java.sql.Connection.
35 *
36 * For those looking further into the driver implementation, it is not
37 * an API that is used for plugability of implementations inside our driver
38 * (which is why there are still references to ConnectionImpl throughout the
39 * code).
40 *
41 * @version $Id: $
42 *
43 */
44 public interface Connection extends java.sql.Connection, ConnectionProperties {
45
46 /**
47 * Changes the user on this connection by performing a re-authentication. If
48 * authentication fails, the connection will remain under the context of the
49 * current user.
50 *
51 * @param userName
52 * the username to authenticate with
53 * @param newPassword
54 * the password to authenticate with
55 * @throws SQLException
56 * if authentication fails, or some other error occurs while
57 * performing the command.
58 */
59 public abstract void changeUser(String userName, String newPassword)
60 throws SQLException;
61
62 public abstract void clearHasTriedMaster();
63
64 /**
65 * Prepares a statement on the client, using client-side emulation
66 * (irregardless of the configuration property 'useServerPrepStmts')
67 * with the same semantics as the java.sql.Connection.prepareStatement()
68 * method with the same argument types.
69 *
70 * @see java.sql.Connection#prepareStatement(String)
71 */
72 public abstract java.sql.PreparedStatement clientPrepareStatement(String sql)
73 throws SQLException;
74
75 /**
76 * Prepares a statement on the client, using client-side emulation
77 * (irregardless of the configuration property 'useServerPrepStmts')
78 * with the same semantics as the java.sql.Connection.prepareStatement()
79 * method with the same argument types.
80 *
81 * @see java.sql.Connection#prepareStatement(String, int)
82 */
83 public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
84 int autoGenKeyIndex) throws SQLException;
85
86 /**
87 * Prepares a statement on the client, using client-side emulation
88 * (irregardless of the configuration property 'useServerPrepStmts')
89 * with the same semantics as the java.sql.Connection.prepareStatement()
90 * method with the same argument types.
91 *
92 * @see java.sql.Connection#prepareStatement(String, int, int)
93 */
94 public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
95 int resultSetType, int resultSetConcurrency) throws SQLException;
96
97 /**
98 * Prepares a statement on the client, using client-side emulation
99 * (irregardless of the configuration property 'useServerPrepStmts')
100 * with the same semantics as the java.sql.Connection.prepareStatement()
101 * method with the same argument types.
102 *
103 * @see java.sql.Connection#prepareStatement(String, int[])
104 */
105 public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
106 int[] autoGenKeyIndexes) throws SQLException;
107
108 /**
109 * Prepares a statement on the client, using client-side emulation
110 * (irregardless of the configuration property 'useServerPrepStmts')
111 * with the same semantics as the java.sql.Connection.prepareStatement()
112 * method with the same argument types.
113 *
114 * @see java.sql.Connection#prepareStatement(String, int, int, int)
115 */
116 public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
117 int resultSetType, int resultSetConcurrency,
118 int resultSetHoldability) throws SQLException;
119
120 /**
121 * Prepares a statement on the client, using client-side emulation
122 * (irregardless of the configuration property 'useServerPrepStmts')
123 * with the same semantics as the java.sql.Connection.prepareStatement()
124 * method with the same argument types.
125 *
126 * @see java.sql.Connection#prepareStatement(String, String[])
127 */
128 public abstract java.sql.PreparedStatement clientPrepareStatement(String sql,
129 String[] autoGenKeyColNames) throws SQLException;
130
131 /**
132 * Returns the number of statements active on this connection, which
133 * haven't been .close()d.
134 */
135 public abstract int getActiveStatementCount();
136
137 /**
138 * Reports how long this connection has been idle.
139 * This time (reported in milliseconds) is updated once a query has
140 * completed.
141 *
142 * @return number of ms that this connection has been idle, 0 if the driver
143 * is busy retrieving results.
144 */
145 public abstract long getIdleFor();
146
147 /**
148 * Returns the log mechanism that should be used to log information from/for
149 * this Connection.
150 *
151 * @return the Log instance to use for logging messages.
152 * @throws SQLException
153 * if an error occurs
154 */
155 public abstract Log getLog() throws SQLException;
156
157 /**
158 * Returns the server's character set
159 *
160 * @return the server's character set.
161 */
162 public abstract String getServerCharacterEncoding();
163
164 /**
165 * Returns the TimeZone that represents the configured
166 * timezone for the server.
167 */
168 public abstract TimeZone getServerTimezoneTZ();
169
170 /**
171 * Returns the comment that will be prepended to all statements
172 * sent to the server.
173 *
174 * @return the comment that will be prepended to all statements
175 * sent to the server.
176 */
177 public abstract String getStatementComment();
178
179 /**
180 * Has this connection tried to execute a query on the "master"
181 * server (first host in a multiple host list).
182 */
183 public abstract boolean hasTriedMaster();
184
185 /**
186 * Is this connection currently a participant in an XA transaction?
187 */
188 public abstract boolean isInGlobalTx();
189
190 /**
191 * Set the state of being in a global (XA) transaction.
192 * @param flag
193 */
194 public void setInGlobalTx(boolean flag);
195
196 /**
197 * Is this connection connected to the first host in the list if
198 * there is a list of servers in the URL?
199 *
200 * @return true if this connection is connected to the first in
201 * the list.
202 */
203 public abstract boolean isMasterConnection();
204
205 /**
206 * Is the server in a sql_mode that doesn't allow us to use \\ to escape
207 * things?
208 *
209 * @return Returns the noBackslashEscapes.
210 */
211 public abstract boolean isNoBackslashEscapesSet();
212
213 /**
214 * Does this connection have the same resource name as the given
215 * connection (for XA)?
216 *
217 * @param c
218 * @return
219 */
220 public abstract boolean isSameResource(Connection c);
221
222 /**
223 * Is the server configured to use lower-case table names only?
224 *
225 * @return true if lower_case_table_names is 'on'
226 */
227 public abstract boolean lowerCaseTableNames();
228
229 /**
230 * Does the server this connection is connected to
231 * support unicode?
232 */
233 public abstract boolean parserKnowsUnicode();
234
235 /**
236 * Detect if the connection is still good by sending a ping command
237 * to the server.
238 *
239 * @throws SQLException
240 * if the ping fails
241 */
242 public abstract void ping() throws SQLException;
243
244 /**
245 * Resets the server-side state of this connection. Doesn't work for MySQL
246 * versions older than 4.0.6 or if isParanoid() is set (it will become a
247 * no-op in these cases). Usually only used from connection pooling code.
248 *
249 * @throws SQLException
250 * if the operation fails while resetting server state.
251 */
252 public abstract void resetServerState() throws SQLException;
253
254 /**
255 * Prepares a statement on the server (irregardless of the
256 * configuration property 'useServerPrepStmts') with the same semantics
257 * as the java.sql.Connection.prepareStatement() method with the
258 * same argument types.
259 *
260 * @see java.sql.Connection#prepareStatement(String)
261 */
262 public abstract java.sql.PreparedStatement serverPrepareStatement(String sql)
263 throws SQLException;
264
265 /**
266 * Prepares a statement on the server (irregardless of the
267 * configuration property 'useServerPrepStmts') with the same semantics
268 * as the java.sql.Connection.prepareStatement() method with the
269 * same argument types.
270 *
271 * @see java.sql.Connection#prepareStatement(String, int)
272 */
273 public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
274 int autoGenKeyIndex) throws SQLException;
275
276 /**
277 * Prepares a statement on the server (irregardless of the
278 * configuration property 'useServerPrepStmts') with the same semantics
279 * as the java.sql.Connection.prepareStatement() method with the
280 * same argument types.
281 *
282 * @see java.sql.Connection#prepareStatement(String, int, int)
283 */
284 public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
285 int resultSetType, int resultSetConcurrency) throws SQLException;
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, int, int, int)
293 */
294 public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
295 int resultSetType, int resultSetConcurrency,
296 int resultSetHoldability) throws SQLException;
297
298 /**
299 * Prepares a statement on the server (irregardless of the
300 * configuration property 'useServerPrepStmts') with the same semantics
301 * as the java.sql.Connection.prepareStatement() method with the
302 * same argument types.
303 *
304 * @see java.sql.Connection#prepareStatement(String, int[])
305 */
306 public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
307 int[] autoGenKeyIndexes) throws SQLException;
308
309 /**
310 * Prepares a statement on the server (irregardless of the
311 * configuration property 'useServerPrepStmts') with the same semantics
312 * as the java.sql.Connection.prepareStatement() method with the
313 * same argument types.
314 *
315 * @see java.sql.Connection#prepareStatement(String, String[])
316 */
317 public abstract java.sql.PreparedStatement serverPrepareStatement(String sql,
318 String[] autoGenKeyColNames) throws SQLException;
319
320 /**
321 * @param failedOver
322 * The failedOver to set.
323 */
324 public abstract void setFailedOver(boolean flag);
325
326 /**
327 * @param preferSlaveDuringFailover
328 * The preferSlaveDuringFailover to set.
329 */
330 public abstract void setPreferSlaveDuringFailover(boolean flag);
331
332 /**
333 * Sets the comment that will be prepended to all statements
334 * sent to the server. Do not use slash-star or star-slash tokens
335 * in the comment as these will be added by the driver itself.
336 *
337 * @param comment the comment that will be prepended to all statements
338 * sent to the server.
339 */
340 public abstract void setStatementComment(String comment);
341
342 /**
343 * Used by MiniAdmin to shutdown a MySQL server
344 *
345 * @throws SQLException
346 * if the command can not be issued.
347 */
348 public abstract void shutdownServer() throws SQLException;
349
350 /**
351 * Does the server this connection is connected to
352 * support quoted isolation levels?
353 */
354 public abstract boolean supportsIsolationLevel();
355
356 /**
357 * Does the server this connection is connected to
358 * support quoted identifiers?
359 */
360 public abstract boolean supportsQuotedIdentifiers();
361
362 /**
363 * Does the server this connection is connected to
364 * support quoted identifiers?
365 */
366 public abstract boolean supportsTransactions();
367
368 /**
369 * Does the server this connection is connected to
370 * meet or exceed the given version?
371 */
372 public abstract boolean versionMeetsMinimum(int major, int minor,
373 int subminor) throws SQLException;
374
375 public abstract void reportQueryTime(long millisOrNanos);
376
377 public abstract boolean isAbonormallyLongQuery(long millisOrNanos);
378
379 public abstract void initializeExtension(Extension ex) throws SQLException;
380
381 /** Returns the -session- value of 'auto_increment_increment' from the server if it exists,
382 * or '1' if not.
383 */
384 public abstract int getAutoIncrementIncrement();
385
386 /**
387 * Does this connection have the same properties as another?
388 */
389 public boolean hasSameProperties(Connection c);
390
391 /**
392 * Returns the parsed and passed in properties for this connection.
393 * @return
394 */
395 public Properties getProperties();
396 }
Save This Page