SQLServerConnection Class

Package:

com.microsoft.sqlserver.jdbc

Maven Artifact:

com.microsoft.sqlserver:mssql-jdbc:12.8.0.jre11

• java.lang.Object
• • com.microsoft.sqlserver.jdbc.SQLServerConnection

Implements

ISQLServerConnection java.io.Serializable

public class SQLServerConnection
implements ISQLServerConnection, java.io.Serializable

Provides an implementation java.sql.connection interface that assists creating a JDBC connection to SQL Server. SQLServerConnections support JDBC connection pooling and may be either physical JDBC connections or logical JDBC connections. SQLServerConnection manages transaction control for all statements that were created from it. SQLServerConnection may participate in XA distributed transactions managed via an XAResource adapter. SQLServerConnection instantiates a new TDSChannel object for use by itself and all statement objects that are created under this connection. SQLServerConnection manages a pool of prepared statement handles. Prepared statements are prepared once and typically executed many times with different data values for their parameters. Prepared statements are also maintained across logical (pooled) connection closes. SQLServerConnection is not thread safe, however multiple statements created from a single connection can be processing simultaneously in concurrent threads. This class's public functions need to be kept identical to the SQLServerConnectionPoolProxy's. The API javadoc for JDBC API methods that this class implements are not repeated here. Please see Sun's JDBC API interfaces javadoc for those details. NOTE: All the public functions in this class also need to be defined in SQLServerConnectionPoolProxy Declare all new custom (non-static) Public APIs in ISQLServerConnection interface such that they can also be implemented by SQLServerConnectionPoolProxy

Method Summary

Modifier and Type	Method and Description
T	unwrap(Class<T> iface)
void	abort(Executor executor)
static void	clearUserTokenCache() Clears User token cache.
void	clearWarnings()
void	close()
void	closeUnreferencedPreparedStatementHandles() Forces the un-prepare requests for any outstanding discarded prepared statements to be executed.
void	commit()
void	commit(boolean delayedDurability) Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object.
java.sql.Array	createArrayOf(String typeName, Object[] elements)
java.sql.Blob	createBlob()
java.sql.Clob	createClob()
java.sql.NClob	createNClob()
java.sql.SQLXML	createSQLXML()
java.sql.Statement	createStatement()
java.sql.Statement	createStatement(int resultSetType, int resultSetConcurrency)
java.sql.Statement	createStatement(int nType, int nConcur, int resultSetHoldability)
java.sql.Statement	createStatement(int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) Creates a Statement object that will generate ResultSet objects with the given type, concurrency, and holdability.
java.sql.Struct	createStruct(String typeName, Object[] attributes)
java.lang.String	getAccessTokenCallbackClass() Returns the fully qualified class name of the implementing class for SQLServerAccessTokenCallback.
boolean	getAutoCommit()
boolean	getCalcBigDecimalPrecision() Returns the current flag for calcBigDecimalPrecision.
java.lang.String	getCatalog()
java.util.UUID	getClientConnectionId() Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.
java.util.Properties	getClientInfo()
java.lang.String	getClientInfo(String name)
static java.util.Map<java.lang.String,java.util.List<java.lang.String>>	getColumnEncryptionTrustedMasterKeyPaths() Returns the Trusted Master Key Paths.
final java.lang.String	getDatetimeParameterType() Returns the value of the datetimeParameterType property.
boolean	getDelayLoadingLobs() Returns the current flag value for delayLoadingLobs.
boolean	getDisableStatementPooling() Returns the value whether statement pooling is disabled.
int	getDiscardedServerPreparedStatementCount() Returns the number of currently outstanding prepared statement un-prepare actions.
boolean	getEnablePrepareOnFirstPreparedStatementCall() Returns the behavior for a specific connection instance.
int	getHoldability()
java.lang.String	getIPAddressPreference() Gets the name of the preferred type of IP Address.
boolean	getIgnoreOffsetOnDateTimeOffsetConversion() Returns the current flag value for ignoreOffsetOnDateTimeOffsetConversion.
java.sql.DatabaseMetaData	getMetaData()
int	getMsiTokenCacheTtl() Deprecated Time-to-live is no longer supported for the cached Managed Identity tokens. This method will always return 0 and is for backwards compatibility only. This method will always return 0 and is for backwards compatibility only.
int	getNetworkTimeout()
java.lang.String	getPrepareMethod() Returns the behavior for a specific connection instance.
java.lang.String	getSchema()
final boolean	getSendTimeAsDatetime() Returns the value of the sendTimeAsDatetime property.
ISQLServerMessageHandler	getServerMessageHandler() Get Currently installed message handler on the connection
int	getServerPreparedStatementDiscardThreshold() Returns the behavior for a specific connection instance.
int	getStatementHandleCacheEntryCount() Returns the current number of pooled prepared statement handles.
int	getStatementPoolingCacheSize() Returns the size of the prepared statement cache for this connection.
int	getTransactionIsolation()
java.util.Map<java.lang.String,java.lang.Class<?>>	getTypeMap()
boolean	getUseBulkCopyForBatchInsert() Returns the useBulkCopyForBatchInsert value.
boolean	getUseFlexibleCallableStatements() Returns whether or not sp_sproc_columns is being used for parameter name lookup.
final boolean	getUseFmtOnly() Returns the current flag value for useFmtOnly.
java.sql.SQLWarning	getWarnings()
boolean	getcacheBulkCopyMetadata() Sets the value for 'cacheBulkCopyMetadata' property
boolean	isClosed()
boolean	isReadOnly()
boolean	isStatementPoolingEnabled() Returns whether statement pooling is enabled or not for this connection.
boolean	isValid(int timeout) Determine whether the connection is still valid.
boolean	isWrapperFor(Class<?> iface)
java.lang.String	nativeSQL(String sql)
protected boolean	needsReconnect() Returns if Federated Authentication is in use or is about to expire soon
java.sql.CallableStatement	prepareCall(String sql)
java.sql.CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency)
java.sql.CallableStatement	prepareCall(String sql, int nType, int nConcur, int resultSetHoldability)
java.sql.CallableStatement	prepareCall(String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetiing) Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency.
java.sql.PreparedStatement	prepareStatement(String sql)
java.sql.PreparedStatement	prepareStatement(String sql, int flag)
java.sql.PreparedStatement	prepareStatement(String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) Creates a default PreparedStatement object that has the capability to retrieve auto-generated keys.
java.sql.PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency)
java.sql.PreparedStatement	prepareStatement(String sql, int nType, int nConcur, int resultSetHoldability)
java.sql.PreparedStatement	prepareStatement(String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) Creates a PreparedStatement object that will generate ResultSet objects with the given type, concurrency, and holdability.
java.sql.PreparedStatement	prepareStatement(String sql, int[] columnIndexes)
java.sql.PreparedStatement	prepareStatement(String sql, int[] columnIndexes, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array.
java.sql.PreparedStatement	prepareStatement(String sql, String[] columnNames)
java.sql.PreparedStatement	prepareStatement(String sql, String[] columnNames, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array.
void	registerBeforeReconnectListener(ReconnectListener reconnectListener)
static void	registerColumnEncryptionKeyStoreProviders(Map<String,SQLServerColumnEncryptionKeyStoreProvider> clientKeyStoreProviders) Registers key store providers in the globalCustomColumnEncryptionKeyStoreProviders.
void	registerColumnEncryptionKeyStoreProvidersOnConnection(Map<String,SQLServerColumnEncryptionKeyStoreProvider> clientKeyStoreProviders) Registers connection-level key store providers, replacing all existing providers.
void	releaseSavepoint(Savepoint savepoint)
void	removeBeforeReconnectListener(ReconnectListener reconnectListener)
static void	removeColumnEncryptionTrustedMasterKeyPaths(String server) Removes the trusted Master key Path from the columnEncryptionTrustedMasterKeyPaths.
void	rollback()
void	rollback(Savepoint s)
void	setAccessTokenCallbackClass(String accessTokenCallbackClass) Sets 'accessTokenCallbackClass' to the fully qualified class name of the implementing class for SQLServerAccessTokenCallback.
void	setAutoCommit(boolean newAutoCommitMode)
void	setCalcBigDecimalPrecision(boolean calcBigDecimalPrecision) Specifies whether to calculate precision from inputted big decimal values.
void	setCatalog(String catalog)
void	setClientInfo(String name, String value)
void	setClientInfo(Properties properties)
static void	setColumnEncryptionKeyCacheTtl(int columnEncryptionKeyCacheTTL, TimeUnit unit) Sets time-to-live for column encryption key entries in the column encryption key cache for the Always Encrypted feature.
static void	setColumnEncryptionTrustedMasterKeyPaths(Map<String,List<String>> trustedKeyPaths) Sets Trusted Master Key Paths in the columnEncryptionTrustedMasterKeyPaths.
void	setDatetimeParameterType(String datetimeParameterTypeValue) Sets the value of the datetimeParameterType connection property, which controls how date and time parameters are sent to the server against SQL Server 2008+.
void	setDelayLoadingLobs(boolean b) Specifies the flag to immediately load LOB objects into memory.
void	setDisableStatementPooling(boolean value) Sets the value to Disable/enable statement pooling.
void	setEnablePrepareOnFirstPreparedStatementCall(boolean value) Sets the behavior for a specific connection instance.
void	setHoldability(int holdability)
void	setIPAddressPreference(String iPAddressPreference) Sets the name of the preferred type of IP Address.
void	setIgnoreOffsetOnDateTimeOffsetConversion(boolean ignoreOffsetOnDateTimeOffsetConversion) Specifies the flag to ignore offset when converting DATETIMEOFFSET to LocalDateTime.
void	setMsiTokenCacheTtl(int timeToLive) Deprecated Time-to-live is no longer supported for the cached Managed Identity tokens. This method is a no-op for backwards compatibility only. Time-to-live is no longer supported for the cached Managed Identity tokens.
void	setNetworkTimeout(Executor executor, int timeout)
void	setPrepareMethod(String prepareMethod) Sets the behavior for the prepare method.
void	setReadOnly(boolean readOnly)
java.sql.Savepoint	setSavepoint()
java.sql.Savepoint	setSavepoint(String sName)
void	setSchema(String schema)
void	setSendTimeAsDatetime(boolean sendTimeAsDateTimeValue) Sets the value of the sendTimeAsDatetime connection property.
ISQLServerMessageHandler	setServerMessageHandler(ISQLServerMessageHandler messageHandler) Set current message handler
void	setServerPreparedStatementDiscardThreshold(int value) Sets the behavior for a specific connection instance.
void	setStatementPoolingCacheSize(int value) Sets the size of the prepared statement cache for this connection.
void	setTransactionIsolation(int level)
void	setTypeMap(Map<String,Class<?>> map)
void	setUseBulkCopyForBatchInsert(boolean useBulkCopyForBatchInsert) Specifies the flag for using Bulk Copy API for batch insert operations.
void	setUseFlexibleCallableStatements(boolean useFlexibleCallableStatements) Sets whether or not sp_sproc_columns will be used for parameter name lookup.
void	setUseFmtOnly(boolean useFmtOnly) Specifies the flag to use FMTONLY for parameter metadata queries.
void	setcacheBulkCopyMetadata(boolean value) Returns value of 'cacheBulkCopyMetadata' from Connection String.
java.lang.String	toString() Provides a helper function to return an ID string suitable for tracing.
static void	unregisterColumnEncryptionKeyStoreProviders() Unregisters all the custom key store providers from the globalCustomColumnEncryptionKeyStoreProviders by clearing the map and setting it to null.
static void	updateColumnEncryptionTrustedMasterKeyPaths(String server, List<String> trustedKeyPaths) Updates the columnEncryptionTrustedMasterKeyPaths with the new Server and trustedKeyPaths.

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Method Details

unwrap

public T <T>unwrap(Class<T> iface)

Parameters:

iface

Throws:

java.sql.SQLException

abort

public void abort(Executor executor)

Parameters:

executor

Throws:

java.sql.SQLException

clearUserTokenCache

public static void clearUserTokenCache()

Clears User token cache. This will clear all account info so interactive login will be required on the next request to acquire an access token.

clearWarnings

public void clearWarnings()

Throws:

SQLServerException

close

public void close()

Throws:

SQLServerException

closeUnreferencedPreparedStatementHandles

public void closeUnreferencedPreparedStatementHandles()

Forces the un-prepare requests for any outstanding discarded prepared statements to be executed.

commit

public void commit()

Throws:

SQLServerException

commit

public void commit(boolean delayedDurability)

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object. This method should be used only when auto-commit mode has been disabled.

Parameters:

delayedDurability - flag to indicate whether the commit will occur with delayed durability on.

Throws:

SQLServerException - Exception if a database access error occurs

createArrayOf

public Array createArrayOf(String typeName, Object[] elements)

Parameters:

typeName

elements

Throws:

java.sql.SQLException

createBlob

public Blob createBlob()

Throws:

java.sql.SQLException

createClob

public Clob createClob()

Throws:

java.sql.SQLException

createNClob

public NClob createNClob()

Throws:

java.sql.SQLException

createSQLXML

public SQLXML createSQLXML()

Throws:

java.sql.SQLException

createStatement

public Statement createStatement()

Throws:

SQLServerException

createStatement

public Statement createStatement(int resultSetType, int resultSetConcurrency)

Parameters:

resultSetType

resultSetConcurrency

Throws:

SQLServerException

createStatement

public Statement createStatement(int nType, int nConcur, int resultSetHoldability)

Parameters:

nType

nConcur

resultSetHoldability

Throws:

SQLServerException

createStatement

public Statement createStatement(int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)

Creates a Statement object that will generate ResultSet objects with the given type, concurrency, and holdability. This method is the same as the createStatement method above, but it allows the default result set type, concurrency, and holdability to be overridden.

Parameters:

nType

nConcur

resultSetHoldability

stmtColEncSetting

Throws:

SQLServerException

createStruct

public Struct createStruct(String typeName, Object[] attributes)

Parameters:

typeName

attributes

Throws:

java.sql.SQLException

getAccessTokenCallbackClass

public String getAccessTokenCallbackClass()

Returns the fully qualified class name of the implementing class for SQLServerAccessTokenCallback.

Returns:

accessTokenCallbackClass

getAutoCommit

public boolean getAutoCommit()

Throws:

SQLServerException

getCalcBigDecimalPrecision

public boolean getCalcBigDecimalPrecision()

Returns the current flag for calcBigDecimalPrecision.

getCatalog

public String getCatalog()

Throws:

SQLServerException

getClientConnectionId

public UUID getClientConnectionId()

Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.

Throws:

SQLServerException

getClientInfo

public Properties getClientInfo()

Throws:

java.sql.SQLException

getClientInfo

public String getClientInfo(String name)

Parameters:

name

Throws:

java.sql.SQLException

getColumnEncryptionTrustedMasterKeyPaths

public static Map<String,List<String>> getColumnEncryptionTrustedMasterKeyPaths()

Returns the Trusted Master Key Paths.

Returns:

columnEncryptionTrustedMasterKeyPaths.

getDatetimeParameterType

public final String getDatetimeParameterType()

Returns the value of the datetimeParameterType property.

getDelayLoadingLobs

public boolean getDelayLoadingLobs()

Returns the current flag value for delayLoadingLobs.

getDisableStatementPooling

public boolean getDisableStatementPooling()

Returns the value whether statement pooling is disabled.

getDiscardedServerPreparedStatementCount

public int getDiscardedServerPreparedStatementCount()

Returns the number of currently outstanding prepared statement un-prepare actions.

getEnablePrepareOnFirstPreparedStatementCall

public boolean getEnablePrepareOnFirstPreparedStatementCall()

Returns the behavior for a specific connection instance. If false the first execution will call sp_executesql and not prepare a statement, once the second execution happens it will call sp_prepexec and actually setup a prepared statement handle. Following executions will call sp_execute. This relieves the need for sp_unprepare on prepared statement close if the statement is only executed once. The default for this option can be changed by calling setDefaultEnablePrepareOnFirstPreparedStatementCall().

getHoldability

public int getHoldability()

Throws:

SQLServerException

getIPAddressPreference

public String getIPAddressPreference()

Gets the name of the preferred type of IP Address.

getIgnoreOffsetOnDateTimeOffsetConversion

public boolean getIgnoreOffsetOnDateTimeOffsetConversion()

Returns the current flag value for ignoreOffsetOnDateTimeOffsetConversion.

getMetaData

public DatabaseMetaData getMetaData()

Throws:

SQLServerException

getMsiTokenCacheTtl

(=12.1.0,=true)
public int getMsiTokenCacheTtl()

Deprecated

Time-to-live is no longer supported for the cached Managed Identity tokens. This method will always return 0 and is for backwards compatibility only.

This method will always return 0 and is for backwards compatibility only.

getNetworkTimeout

public int getNetworkTimeout()

Throws:

java.sql.SQLException

getPrepareMethod

public String getPrepareMethod()

Returns the behavior for a specific connection instance. PrepareMethod

getSchema

public String getSchema()

Throws:

java.sql.SQLException

getSendTimeAsDatetime

public final boolean getSendTimeAsDatetime()

Returns the value of the sendTimeAsDatetime property.

getServerMessageHandler

public ISQLServerMessageHandler getServerMessageHandler()

Get Currently installed message handler on the connection

Returns:

Get Currently installed message handler on the connection

getServerPreparedStatementDiscardThreshold

public int getServerPreparedStatementDiscardThreshold()

Returns the behavior for a specific connection instance. This setting controls how many outstanding prepared statement discard actions (sp_unprepare) can be outstanding per connection before a call to clean-up the outstanding handles on the server is executed. If the setting is <= 1, unprepare actions will be executed immediately on prepared statement close. If it is set to > 1, these calls will be batched together to avoid overhead of calling sp_unprepare too often. The default for this option can be changed by calling getDefaultServerPreparedStatementDiscardThreshold().

getStatementHandleCacheEntryCount

public int getStatementHandleCacheEntryCount()

Returns the current number of pooled prepared statement handles.

getStatementPoolingCacheSize

public int getStatementPoolingCacheSize()

Returns the size of the prepared statement cache for this connection. A value less than 1 means no cache.

getTransactionIsolation

public int getTransactionIsolation()

Throws:

SQLServerException

getTypeMap

public Map<String,Class<?>> getTypeMap()

Throws:

SQLServerException

getUseBulkCopyForBatchInsert

public boolean getUseBulkCopyForBatchInsert()

Returns the useBulkCopyForBatchInsert value.

Returns:

flag for using Bulk Copy API for batch insert operations.

getUseFlexibleCallableStatements

public boolean getUseFlexibleCallableStatements()

Returns whether or not sp_sproc_columns is being used for parameter name lookup.

Returns:

useFlexibleCallableStatements

getUseFmtOnly

public final boolean getUseFmtOnly()

Returns the current flag value for useFmtOnly.

getWarnings

public SQLWarning getWarnings()

Throws:

SQLServerException

getcacheBulkCopyMetadata

public boolean getcacheBulkCopyMetadata()

Sets the value for 'cacheBulkCopyMetadata' property

isClosed

public boolean isClosed()

Throws:

SQLServerException

isReadOnly

public boolean isReadOnly()

Throws:

SQLServerException

isStatementPoolingEnabled

public boolean isStatementPoolingEnabled()

Returns whether statement pooling is enabled or not for this connection.

isValid

public boolean isValid(int timeout)

Determine whether the connection is still valid. The driver shall submit a query on the connection or use some other mechanism that positively verifies the connection is still valid when this method is called. The query submitted by the driver to validate the connection shall be executed in the context of the current transaction.

Parameters:

timeout - The time in seconds to wait for the database operation used to validate the connection to complete. If the timeout period expires before the operation completes, this method returns false. A value of 0 indicates a timeout is not applied to the database operation. Note that if the value is 0, the call to isValid may block indefinitely if the connection is not valid...

Returns:

true if the connection has not been closed and is still valid.

Throws:

java.sql.SQLException - if the value supplied for the timeout is less than 0.

isWrapperFor

public boolean isWrapperFor(Class<?> iface)

Parameters:

iface

Throws:

java.sql.SQLException

nativeSQL

public String nativeSQL(String sql)

Parameters:

sql

Throws:

SQLServerException

needsReconnect

protected boolean needsReconnect()

Returns if Federated Authentication is in use or is about to expire soon

Returns:

true/false

prepareCall

public CallableStatement prepareCall(String sql)

Parameters:

sql

Throws:

SQLServerException

prepareCall

public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency)

Parameters:

sql

resultSetType

resultSetConcurrency

Throws:

SQLServerException

prepareCall

public CallableStatement prepareCall(String sql, int nType, int nConcur, int resultSetHoldability)

Parameters:

sql

nType

nConcur

resultSetHoldability

Throws:

SQLServerException

prepareCall

public CallableStatement prepareCall(String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetiing)

Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency. This method is the same as the prepareCall method above, but it allows the default result set type, result set concurrency type and holdability to be overridden.

Parameters:

sql

nType

nConcur

resultSetHoldability

stmtColEncSetiing

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql)

Parameters:

sql

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int flag)

Parameters:

sql

flag

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)

Creates a default PreparedStatement object that has the capability to retrieve auto-generated keys. The given constant tells the driver whether it should make auto-generated keys available for retrieval. This parameter is ignored if the SQL statement is not an INSERT statement, or an SQL statement able to return auto-generated keys (the list of such statements is vendor-specific).

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLExceptions.

Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. The holdability of the created result sets can be determined by calling #getHoldability.

Parameters:

sql

flag

stmtColEncSetting

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency)

Parameters:

sql

resultSetType

resultSetConcurrency

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int nType, int nConcur, int resultSetHoldability)

Parameters:

sql

nType

nConcur

resultSetHoldability

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)

Creates a PreparedStatement object that will generate ResultSet objects with the given type, concurrency, and holdability.

This method is the same as the prepareStatement method above, but it allows the default result set type, concurrency, and holdability to be overridden.

Parameters:

sql

nType

nConcur

resultSetHoldability

stmtColEncSetting

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int[] columnIndexes)

Parameters:

sql

columnIndexes

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, int[] columnIndexes, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)

Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array. This array contains the indexes of the columns in the target table that contain the auto-generated keys that should be made available. The driver will ignore the array if the SQL statement is not an INSERT statement, or an SQL statement able to return auto-generated keys (the list of such statements is vendor-specific).

An SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLExceptions.

Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. The holdability of the created result sets can be determined by calling #getHoldability.

Parameters:

sql

columnIndexes

stmtColEncSetting

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, String[] columnNames)

Parameters:

sql

columnNames

Throws:

SQLServerException

prepareStatement

public PreparedStatement prepareStatement(String sql, String[] columnNames, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)

Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array. This array contains the names of the columns in the target table that contain the auto-generated keys that should be returned. The driver will ignore the array if the SQL statement is not an INSERT statement, or an SQL statement able to return auto-generated keys (the list of such statements is vendor-specific).

An SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLExceptions.

Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. The holdability of the created result sets can be determined by calling #getHoldability.

Parameters:

sql

columnNames

stmtColEncSetting

Throws:

SQLServerException

registerBeforeReconnectListener

public void registerBeforeReconnectListener(ReconnectListener reconnectListener)

Parameters:

reconnectListener

registerColumnEncryptionKeyStoreProviders

public static void registerColumnEncryptionKeyStoreProviders(Map<String,SQLServerColumnEncryptionKeyStoreProvider> clientKeyStoreProviders)

Registers key store providers in the globalCustomColumnEncryptionKeyStoreProviders.

Parameters:

clientKeyStoreProviders - a map containing the store providers information.

Throws:

SQLServerException - when an error occurs

registerColumnEncryptionKeyStoreProvidersOnConnection

public void registerColumnEncryptionKeyStoreProvidersOnConnection(Map<String,SQLServerColumnEncryptionKeyStoreProvider> clientKeyStoreProviders)

Registers connection-level key store providers, replacing all existing providers.

Parameters:

clientKeyStoreProviders - a map containing the store providers information.

Throws:

SQLServerException - when an error occurs

releaseSavepoint

public void releaseSavepoint(Savepoint savepoint)

Parameters:

savepoint

Throws:

java.sql.SQLException

removeBeforeReconnectListener

public void removeBeforeReconnectListener(ReconnectListener reconnectListener)

Parameters:

reconnectListener

removeColumnEncryptionTrustedMasterKeyPaths

public static void removeColumnEncryptionTrustedMasterKeyPaths(String server)

Removes the trusted Master key Path from the columnEncryptionTrustedMasterKeyPaths.

Parameters:

server - String server name

rollback

public void rollback()

Throws:

SQLServerException

rollback

public void rollback(Savepoint s)

Parameters:

s

Throws:

SQLServerException

setAccessTokenCallbackClass

public void setAccessTokenCallbackClass(String accessTokenCallbackClass)

Sets 'accessTokenCallbackClass' to the fully qualified class name of the implementing class for SQLServerAccessTokenCallback.

Parameters:

accessTokenCallbackClass - access token callback class

setAutoCommit

public void setAutoCommit(boolean newAutoCommitMode)

Parameters:

newAutoCommitMode

Throws:

SQLServerException

setCalcBigDecimalPrecision

public void setCalcBigDecimalPrecision(boolean calcBigDecimalPrecision)

Specifies whether to calculate precision from inputted big decimal values.

Parameters:

calcBigDecimalPrecision

setCatalog

public void setCatalog(String catalog)

Parameters:

catalog

Throws:

SQLServerException

setClientInfo

public void setClientInfo(String name, String value)

Parameters:

name

value

Throws:

java.sql.SQLClientInfoException

setClientInfo

public void setClientInfo(Properties properties)

Parameters:

properties

Throws:

java.sql.SQLClientInfoException

setColumnEncryptionKeyCacheTtl

public static void setColumnEncryptionKeyCacheTtl(int columnEncryptionKeyCacheTTL, TimeUnit unit)

Sets time-to-live for column encryption key entries in the column encryption key cache for the Always Encrypted feature. The default value is 2 hours. This variable holds the value in seconds. This only applies to global-level key store providers. Connection and Statement-level providers need to set their own cache TTL values.

Parameters:

columnEncryptionKeyCacheTTL - The timeunit in seconds

unit - The Timeunit

Throws:

SQLServerException - when an error occurs

setColumnEncryptionTrustedMasterKeyPaths

public static void setColumnEncryptionTrustedMasterKeyPaths(Map<String,List<String>> trustedKeyPaths)

Sets Trusted Master Key Paths in the columnEncryptionTrustedMasterKeyPaths.

Parameters:

trustedKeyPaths - all master key paths that are trusted

setDatetimeParameterType

public void setDatetimeParameterType(String datetimeParameterTypeValue)

Sets the value of the datetimeParameterType connection property, which controls how date and time parameters are sent to the server against SQL Server 2008+. This setting can affect server-side date conversions and comparisons during statement execution, particularly against SQL Server 2016+. By default, the value is set to "datetime2". Valid values are: datetime, datetime2 or datetimeoffset.

Parameters:

datetimeParameterTypeValue

Throws:

SQLServerException

setDelayLoadingLobs

public void setDelayLoadingLobs(boolean b)

Specifies the flag to immediately load LOB objects into memory.

Parameters:

b

setDisableStatementPooling

public void setDisableStatementPooling(boolean value)

Sets the value to Disable/enable statement pooling.

Parameters:

value

setEnablePrepareOnFirstPreparedStatementCall

public void setEnablePrepareOnFirstPreparedStatementCall(boolean value)

Sets the behavior for a specific connection instance. If value is false the first execution will call sp_executesql and not prepare a statement, once the second execution happens it will call sp_prepexec and actually setup a prepared statement handle. Following executions will call sp_execute. This relieves the need for sp_unprepare on prepared statement close if the statement is only executed once.

Parameters:

value

setHoldability

public void setHoldability(int holdability)

Parameters:

holdability

Throws:

SQLServerException

setIPAddressPreference

public void setIPAddressPreference(String iPAddressPreference)

Sets the name of the preferred type of IP Address.

Parameters:

iPAddressPreference

setIgnoreOffsetOnDateTimeOffsetConversion

public void setIgnoreOffsetOnDateTimeOffsetConversion(boolean ignoreOffsetOnDateTimeOffsetConversion)

Specifies the flag to ignore offset when converting DATETIMEOFFSET to LocalDateTime.

Parameters:

ignoreOffsetOnDateTimeOffsetConversion

setMsiTokenCacheTtl

(=12.1.0,=true)
public void setMsiTokenCacheTtl(int timeToLive)

Deprecated

Time-to-live is no longer supported for the cached Managed Identity tokens. This method is a no-op for backwards compatibility only.

Time-to-live is no longer supported for the cached Managed Identity tokens. This method is a no-op for backwards compatibility only.

Parameters:

timeToLive

setNetworkTimeout

public void setNetworkTimeout(Executor executor, int timeout)

Parameters:

executor

timeout

Throws:

java.sql.SQLException

setPrepareMethod

public void setPrepareMethod(String prepareMethod)

Sets the behavior for the prepare method. PrepareMethod

Parameters:

prepareMethod

setReadOnly

public void setReadOnly(boolean readOnly)

Parameters:

readOnly

Throws:

SQLServerException

setSavepoint

public Savepoint setSavepoint()

Throws:

SQLServerException

setSavepoint

public Savepoint setSavepoint(String sName)

Parameters:

sName

Throws:

SQLServerException

setSchema

public void setSchema(String schema)

Parameters:

schema

Throws:

java.sql.SQLException

setSendTimeAsDatetime

public void setSendTimeAsDatetime(boolean sendTimeAsDateTimeValue)

Sets the value of the sendTimeAsDatetime connection property. When true, java.sql.Time values will be sent to the server as SQL Serverdatetime values. When false, java.sql.Time values will be sent to the server as SQL Servertime values. sendTimeAsDatetime can also be modified programmatically with SQLServerDataSource.setSendTimeAsDatetime. The default value for this property may change in a future release.

Parameters:

sendTimeAsDateTimeValue

setServerMessageHandler

public ISQLServerMessageHandler setServerMessageHandler(ISQLServerMessageHandler messageHandler)

Set current message handler

Parameters:

messageHandler - message handler

Returns:

The previously installed message handler (null if none)

setServerPreparedStatementDiscardThreshold

public void setServerPreparedStatementDiscardThreshold(int value)

Sets the behavior for a specific connection instance. This setting controls how many outstanding prepared statement discard actions (sp_unprepare) can be outstanding per connection before a call to clean-up the outstanding handles on the server is executed. If the setting is <= 1 unprepare actions will be executed immedietely on prepared statement close. If it is set to > 1 these calls will be batched together to avoid overhead of calling sp_unprepare too often.

Parameters:

value

setStatementPoolingCacheSize

public void setStatementPoolingCacheSize(int value)

Sets the size of the prepared statement cache for this connection. A value less than 1 means no cache.

Parameters:

value

setTransactionIsolation

public void setTransactionIsolation(int level)

Parameters:

level

Throws:

SQLServerException

setTypeMap

public void setTypeMap(Map<String,Class<?>> map)

Parameters:

map

Throws:

java.sql.SQLException

setUseBulkCopyForBatchInsert

public void setUseBulkCopyForBatchInsert(boolean useBulkCopyForBatchInsert)

Specifies the flag for using Bulk Copy API for batch insert operations.

Parameters:

useBulkCopyForBatchInsert - boolean value for useBulkCopyForBatchInsert.

setUseFlexibleCallableStatements

public void setUseFlexibleCallableStatements(boolean useFlexibleCallableStatements)

Sets whether or not sp_sproc_columns will be used for parameter name lookup.

Parameters:

useFlexibleCallableStatements - When set to false, sp_sproc_columns is not used for parameter name lookup in callable statements. This eliminates a round trip to the server but imposes limitations on how parameters are set. When set to false, applications must either reference parameters by name or by index, not both. Parameters must also be set in the same order as the stored procedure definition.

setUseFmtOnly

public void setUseFmtOnly(boolean useFmtOnly)

Specifies the flag to use FMTONLY for parameter metadata queries.

Parameters:

useFmtOnly

setcacheBulkCopyMetadata

public void setcacheBulkCopyMetadata(boolean value)

Returns value of 'cacheBulkCopyMetadata' from Connection String.

Parameters:

value

toString

public String toString()

Provides a helper function to return an ID string suitable for tracing.

Overrides:

SQLServerConnection.toString()

unregisterColumnEncryptionKeyStoreProviders

public static void unregisterColumnEncryptionKeyStoreProviders()

Unregisters all the custom key store providers from the globalCustomColumnEncryptionKeyStoreProviders by clearing the map and setting it to null.

updateColumnEncryptionTrustedMasterKeyPaths

public static void updateColumnEncryptionTrustedMasterKeyPaths(String server, List<String> trustedKeyPaths)

Updates the columnEncryptionTrustedMasterKeyPaths with the new Server and trustedKeyPaths.

Parameters:

server - String server name

trustedKeyPaths - all master key paths that are trusted