com.mysql.cj.jdbc

Interface JdbcConnection

All Superinterfaces:

AutoCloseable, Connection, MysqlConnection, TransactionEventHandler, Wrapper

All Known Subinterfaces:

LoadBalancedConnection, ReplicationConnection

public interface JdbcConnection
extends Connection, MysqlConnection, TransactionEventHandler

This interface contains methods that are considered the "vendor extension" to the JDBC API for MySQL's implementation of java.sql.Connection. For those looking further into the driver implementation, it is not an API that is used for plugability of implementations inside our driver (which is why there are still references to ConnectionImpl throughout the code).

Field Summary

Fields inherited from interface java.sql.Connection

TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Method Summary

Modifier and Type	Method and Description
void	abortInternal() Clobbers the physical network connection and marks this connection as closed.
void	changeUser(String userName, String newPassword) Changes the user on this connection by performing a re-authentication.
void	clearHasTriedMaster() Deprecated.
PreparedStatement	clientPrepareStatement(String sql) Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	clientPrepareStatement(String sql, int autoGenKeyIndex) Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	clientPrepareStatement(String sql, int[] autoGenKeyIndexes) Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	clientPrepareStatement(String sql, int resultSetType, int resultSetConcurrency) Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	clientPrepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	clientPrepareStatement(String sql, String[] autoGenKeyColNames) Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
void	decachePreparedStatement(JdbcPreparedStatement pstmt)
JdbcConnection	getActiveMySQLConnection()
int	getActiveStatementCount() Returns the number of statements active on this connection, which haven't been .close()d.
int	getAutoIncrementIncrement() Returns the -session- value of 'auto_increment_increment' from the server if it exists, or '1' if not.
CachedResultSetMetaData	getCachedMetaData(String sql) Returns cached metadata (or null if not cached) for the given query, which must match _exactly_.
String	getCharacterSetMetadata()
ClientInfoProvider	getClientInfoProviderImpl()
String	getDatabase() Retrieves this connection object's current database name.
String	getHost()
String	getHostPortPair()
long	getIdleFor() Reports how long this connection has been idle.
Statement	getMetadataSafeStatement()
JdbcConnection	getMultiHostParentProxy()
JdbcConnection	getMultiHostSafeProxy()
JdbcPropertySet	getPropertySet()
List<QueryInterceptor>	getQueryInterceptorsInstances()
ServerVersion	getServerVersion()
int	getSessionMaxRows() Returns the sql select limit max-rows for this session.
String	getStatementComment() Returns the comment that will be prepended to all statements sent to the server.
boolean	hasSameProperties(JdbcConnection c) Does this connection have the same properties as another?
boolean	hasTriedMaster() Deprecated.
void	initializeResultsMetadataFromCache(String sql, CachedResultSetMetaData cachedMetaData, ResultSetInternalMethods resultSet) Caches CachedResultSetMetaData that has been placed in the cache using the given SQL as a key.
void	initializeSafeQueryInterceptors()
boolean	isInGlobalTx() Is this connection currently a participant in an XA transaction?
default boolean	isMasterConnection() Deprecated.
boolean	isProxySet()
boolean	isReadOnly(boolean useSessionStatus) Tests to see if the connection is in Read Only Mode.
boolean	isSameResource(JdbcConnection c) Does this connection have the same resource name as the given connection (for XA)?
boolean	isServerLocal() Is the server this connection is connected to "local" (i.e.
boolean	isSourceConnection() Is this connection connected to the first host in the list if there is a list of servers in the URL?
boolean	lowerCaseTableNames() Is the server configured to use lower-case table names only?
void	ping() Detect if the connection is still good by sending a ping command to the server.
void	pingInternal(boolean checkForClosedConnection, int timeoutMillis)
void	realClose(boolean calledExplicitly, boolean issueRollback, boolean skipLocalTeardown, Throwable reason) Closes connection and frees resources.
void	recachePreparedStatement(JdbcPreparedStatement pstmt)
void	registerStatement(JdbcStatement stmt) Register a Statement instance as open.
void	resetServerState() Resets the server-side state of this connection.
PreparedStatement	serverPrepareStatement(String sql) Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	serverPrepareStatement(String sql, int autoGenKeyIndex) Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	serverPrepareStatement(String sql, int[] autoGenKeyIndexes) Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	serverPrepareStatement(String sql, int resultSetType, int resultSetConcurrency) Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	serverPrepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
PreparedStatement	serverPrepareStatement(String sql, String[] autoGenKeyColNames) Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.
void	setDatabase(String dbName) Set current database for this connection.
void	setFailedOver(boolean flag)
void	setInGlobalTx(boolean flag) Set the state of being in a global (XA) transaction.
void	setProxy(JdbcConnection proxy)
void	setReadOnlyInternal(boolean readOnlyFlag)
void	setSessionMaxRows(int max) Sets the sql select limit max-rows for this session if different from current.
void	setStatementComment(String comment) Sets the comment that will be prepended to all statements sent to the server.
void	shutdownServer() Used by MiniAdmin to shutdown a MySQL server
boolean	storesLowerCaseTableName()
void	throwConnectionClosedException()
void	unregisterStatement(JdbcStatement stmt) Remove the given statement from the list of open statements
void	unSafeQueryInterceptors()

Methods inherited from interface java.sql.Connection

abort, clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, getAutoCommit, getCatalog, getClientInfo, getClientInfo, getHoldability, getMetaData, getNetworkTimeout, getSchema, getTransactionIsolation, getTypeMap, getWarnings, isClosed, isReadOnly, isValid, nativeSQL, prepareCall, prepareCall, prepareCall, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, prepareStatement, releaseSavepoint, rollback, rollback, setAutoCommit, setCatalog, setClientInfo, setClientInfo, setHoldability, setNetworkTimeout, setReadOnly, setSavepoint, setSavepoint, setSchema, setTransactionIsolation, setTypeMap

Methods inherited from interface java.sql.Wrapper

isWrapperFor, unwrap

Methods inherited from interface com.mysql.cj.MysqlConnection

checkClosed, cleanup, createNewIO, getConnectionMutex, getExceptionInterceptor, getId, getProperties, getServerSessionStateController, getSession, getURL, getUser, normalClose

Methods inherited from interface com.mysql.cj.TransactionEventHandler

transactionBegun, transactionCompleted

Method Detail

getPropertySet

JdbcPropertySet getPropertySet()

Specified by:

getPropertySet in interface MysqlConnection

changeUser

void changeUser(String userName,
                String newPassword)
         throws SQLException

Changes the user on this connection by performing a re-authentication. If authentication fails, the connection is failed.

Parameters:

userName - the username to authenticate with

newPassword - the password to authenticate with

Throws:

SQLException - if authentication fails, or some other error occurs while performing the command.

clearHasTriedMaster

@Deprecated
void clearHasTriedMaster()

Deprecated.

clientPrepareStatement

PreparedStatement clientPrepareStatement(String sql)
                                  throws SQLException

Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String)

clientPrepareStatement

PreparedStatement clientPrepareStatement(String sql,
                                         int autoGenKeyIndex)
                                  throws SQLException

Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

autoGenKeyIndex - autoGenKeyIndex

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int)

clientPrepareStatement

PreparedStatement clientPrepareStatement(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency)
                                  throws SQLException

Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

resultSetType - resultSetType

resultSetConcurrency - resultSetConcurrency

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int, int)

clientPrepareStatement

PreparedStatement clientPrepareStatement(String sql,
                                         int[] autoGenKeyIndexes)
                                  throws SQLException

Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

autoGenKeyIndexes - autoGenKeyIndexes

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int[])

clientPrepareStatement

PreparedStatement clientPrepareStatement(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency,
                                         int resultSetHoldability)
                                  throws SQLException

Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

resultSetType - resultSetType

resultSetConcurrency - resultSetConcurrency

resultSetHoldability - resultSetHoldability

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int, int, int)

clientPrepareStatement

PreparedStatement clientPrepareStatement(String sql,
                                         String[] autoGenKeyColNames)
                                  throws SQLException

Prepares a statement on the client, using client-side emulation (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

autoGenKeyColNames - autoGenKeyColNames

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, String[])

getActiveStatementCount

int getActiveStatementCount()

Returns the number of statements active on this connection, which haven't been .close()d.

Returns:

the number of active statements

getIdleFor

long getIdleFor()

Reports how long this connection has been idle. This time (reported in milliseconds) is updated once a query has completed.

Returns:

number of ms that this connection has been idle, 0 if the driver is busy retrieving results.

getStatementComment

String getStatementComment()

Returns the comment that will be prepended to all statements sent to the server.

Returns:

the comment that will be prepended to all statements sent to the server.

hasTriedMaster

@Deprecated
boolean hasTriedMaster()

Deprecated.

Has this connection tried to execute a query on the "source" server (first host in a multiple host list).

Returns:

true if it has tried

isInGlobalTx

boolean isInGlobalTx()

Is this connection currently a participant in an XA transaction?

Returns:

true if this connection currently a participant in an XA transaction

setInGlobalTx

void setInGlobalTx(boolean flag)

Set the state of being in a global (XA) transaction.

Parameters:

flag - the state flag

isSourceConnection

boolean isSourceConnection()

Is this connection connected to the first host in the list if there is a list of servers in the URL?

Returns:

true if this connection is connected to the first in the list.

isMasterConnection

@Deprecated
default boolean isMasterConnection()

Deprecated.

Use isSourceConnection() instead.

Returns:

true if it's a source connection

isSameResource

boolean isSameResource(JdbcConnection c)

Does this connection have the same resource name as the given connection (for XA)?

Parameters:

c - connection

Returns:

true if it is the same one

lowerCaseTableNames

boolean lowerCaseTableNames()

Is the server configured to use lower-case table names only?

Returns:

true if lower_case_table_names is 'on'

ping

void ping()
   throws SQLException

Detect if the connection is still good by sending a ping command to the server.

Throws:

SQLException - if the ping fails

resetServerState

void resetServerState()
               throws SQLException

Resets the server-side state of this connection. Doesn't work if isParanoid() is set (it will become a no-op in this case). Usually only used from connection pooling code.

Throws:

SQLException - if the operation fails while resetting server state.

serverPrepareStatement

PreparedStatement serverPrepareStatement(String sql)
                                  throws SQLException

Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String)

serverPrepareStatement

PreparedStatement serverPrepareStatement(String sql,
                                         int autoGenKeyIndex)
                                  throws SQLException

Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

autoGenKeyIndex - autoGenKeyIndex

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int)

serverPrepareStatement

PreparedStatement serverPrepareStatement(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency)
                                  throws SQLException

Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

resultSetType - resultSetType

resultSetConcurrency - resultSetConcurrency

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int, int)

serverPrepareStatement

PreparedStatement serverPrepareStatement(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency,
                                         int resultSetHoldability)
                                  throws SQLException

Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

resultSetType - resultSetType

resultSetConcurrency - resultSetConcurrency

resultSetHoldability - resultSetHoldability

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int, int, int)

serverPrepareStatement

PreparedStatement serverPrepareStatement(String sql,
                                         int[] autoGenKeyIndexes)
                                  throws SQLException

Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

autoGenKeyIndexes - autoGenKeyIndexes

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, int[])

serverPrepareStatement

PreparedStatement serverPrepareStatement(String sql,
                                         String[] autoGenKeyColNames)
                                  throws SQLException

Prepares a statement on the server (irregardless of the configuration property 'useServerPrepStmts') with the same semantics as the java.sql.Connection.prepareStatement() method with the same argument types.

Parameters:

sql - statement

autoGenKeyColNames - autoGenKeyColNames

Returns:

prepared statement

Throws:

SQLException - if an error occurs

See Also:

Connection.prepareStatement(String, String[])

setFailedOver

void setFailedOver(boolean flag)

Parameters:

flag - The failedOver flag to set.

setStatementComment

void setStatementComment(String comment)

Sets the comment that will be prepended to all statements sent to the server. Do not use slash-star or star-slash tokens in the comment as these will be added by the driver itself.

Parameters:

comment - the comment that will be prepended to all statements sent to the server.

shutdownServer

void shutdownServer()
             throws SQLException

Used by MiniAdmin to shutdown a MySQL server

Throws:

SQLException - if the command can not be issued.

getAutoIncrementIncrement

int getAutoIncrementIncrement()

Returns the -session- value of 'auto_increment_increment' from the server if it exists, or '1' if not.

Returns:

the -session- value of 'auto_increment_increment'

hasSameProperties

boolean hasSameProperties(JdbcConnection c)

Does this connection have the same properties as another?

Parameters:

c - connection

Returns:

true if has the same properties

getHost

String getHost()

getHostPortPair

String getHostPortPair()

setProxy

void setProxy(JdbcConnection proxy)

isServerLocal

boolean isServerLocal()
               throws SQLException

Is the server this connection is connected to "local" (i.e. same host) as the application?

Returns:

true if the server is "local"

Throws:

SQLException - if an error occurs

getSessionMaxRows

int getSessionMaxRows()

Returns the sql select limit max-rows for this session.

Returns:

int max rows

setSessionMaxRows

void setSessionMaxRows(int max)
                throws SQLException

Sets the sql select limit max-rows for this session if different from current.

Parameters:

max - the new max-rows value to set.

Throws:

SQLException - if a database error occurs issuing the statement that sets the limit.

abortInternal

void abortInternal()
            throws SQLException

Clobbers the physical network connection and marks this connection as closed.

Throws:

SQLException - if an error occurs

isProxySet

boolean isProxySet()

getCachedMetaData

CachedResultSetMetaData getCachedMetaData(String sql)

Returns cached metadata (or null if not cached) for the given query, which must match _exactly_. This method is synchronized by the caller on getMutex(), so if calling this method from internal code in the driver, make sure it's synchronized on the mutex that guards communication with the server.

Parameters:

sql - the query that is the key to the cache

Returns:

metadata cached for the given SQL, or none if it doesn't exist.

getCharacterSetMetadata

String getCharacterSetMetadata()

Returns:

Returns the characterSetMetadata.

getMetadataSafeStatement

Statement getMetadataSafeStatement()
                            throws SQLException

Throws:

SQLException

getServerVersion

ServerVersion getServerVersion()

getQueryInterceptorsInstances

List<QueryInterceptor> getQueryInterceptorsInstances()

initializeResultsMetadataFromCache

void initializeResultsMetadataFromCache(String sql,
                                        CachedResultSetMetaData cachedMetaData,
                                        ResultSetInternalMethods resultSet)
                                 throws SQLException

Caches CachedResultSetMetaData that has been placed in the cache using the given SQL as a key. This method is synchronized by the caller on getMutex(), so if calling this method from internal code in the driver, make sure it's synchronized on the mutex that guards communication with the server.

Parameters:

sql - the query that the metadata pertains too.

cachedMetaData - metadata (if it exists) to populate the cache.

resultSet - the result set to retreive metadata from, or apply to.

Throws:

SQLException - if an error occurs

initializeSafeQueryInterceptors

void initializeSafeQueryInterceptors()
                              throws SQLException

Throws:

SQLException

isReadOnly

boolean isReadOnly(boolean useSessionStatus)
            throws SQLException

Tests to see if the connection is in Read Only Mode.

Parameters:

useSessionStatus - in some cases, for example when restoring connection with autoReconnect=true, we can rely only on saved readOnly state, so use useSessionStatus=false in that case

Returns:

true if the connection is read only

Throws:

SQLException - if a database access error occurs

pingInternal

void pingInternal(boolean checkForClosedConnection,
                  int timeoutMillis)
           throws SQLException

Throws:

SQLException

realClose

void realClose(boolean calledExplicitly,
               boolean issueRollback,
               boolean skipLocalTeardown,
               Throwable reason)
        throws SQLException

Closes connection and frees resources.

Parameters:

calledExplicitly - is this being called from close()

issueRollback - should a rollback() be issued?

skipLocalTeardown - if true, driver tries to close connection normally, performing rollbacks, closing open statements etc; otherwise the force close is performed

reason - the exception caused this method call

Throws:

SQLException - if an error occurs

recachePreparedStatement

void recachePreparedStatement(JdbcPreparedStatement pstmt)
                       throws SQLException

Throws:

SQLException

decachePreparedStatement

void decachePreparedStatement(JdbcPreparedStatement pstmt)
                       throws SQLException

Throws:

SQLException

registerStatement

void registerStatement(JdbcStatement stmt)

Register a Statement instance as open.

Parameters:

stmt - the Statement instance to remove

setReadOnlyInternal

void setReadOnlyInternal(boolean readOnlyFlag)
                  throws SQLException

Throws:

SQLException

storesLowerCaseTableName

boolean storesLowerCaseTableName()

throwConnectionClosedException

void throwConnectionClosedException()
                             throws SQLException

Throws:

SQLException

unregisterStatement

void unregisterStatement(JdbcStatement stmt)

Remove the given statement from the list of open statements

Parameters:

stmt - the Statement instance to remove

unSafeQueryInterceptors

void unSafeQueryInterceptors()
                      throws SQLException

Throws:

SQLException

getMultiHostSafeProxy

JdbcConnection getMultiHostSafeProxy()

getMultiHostParentProxy

JdbcConnection getMultiHostParentProxy()

getActiveMySQLConnection

JdbcConnection getActiveMySQLConnection()

getClientInfoProviderImpl

ClientInfoProvider getClientInfoProviderImpl()
                                      throws SQLException

Throws:

SQLException

setDatabase

void setDatabase(String dbName)
          throws SQLException

Set current database for this connection.

Parameters:

dbName - the database for this connection to use

Throws:

SQLException - if a database access error occurs

getDatabase

String getDatabase()
            throws SQLException

Retrieves this connection object's current database name.

Returns:

current database name

Throws:

SQLException - if an error occurs