Interface ISQLServerConnection
-
- All Superinterfaces:
AutoCloseable
,Connection
,Wrapper
- All Known Subinterfaces:
ISQLServerConnection43
- All Known Implementing Classes:
SQLServerConnection
,SQLServerConnection43
public interface ISQLServerConnection extends Connection
Provides an interface to theSQLServerConnection
andSQLServerConnectionPoolProxy
classes.
-
-
Field Summary
Fields Modifier and Type Field Description static int
TRANSACTION_SNAPSHOT
Transaction types "TRANSACTION_SNAPSHOT corresponds to" "SET TRANSACTION ISOLATION LEVEL SNAPSHOT"-
Fields inherited from interface java.sql.Connection
TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description void
closeUnreferencedPreparedStatementHandles()
Forces the un-prepare requests for any outstanding discarded prepared statements to be executed.Statement
createStatement(int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
Creates aStatement
object that will generateResultSet
objects with the given type, concurrency, and holdability.String
getAccessTokenCallbackClass()
Returns the fully qualified class name of the implementing class forSQLServerAccessTokenCallback
.UUID
getClientConnectionId()
Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.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.String
getIPAddressPreference()
Gets the name of the preferred type of IP Address.int
getMsiTokenCacheTtl()
Deprecated, for removal: This API element is subject to removal in a future version.Time-to-live is no longer supported for the cached Managed Identity tokens.String
getPrepareMethod()
Returns the behavior for a specific connection instance.boolean
getSendTimeAsDatetime()
Returns the value of the sendTimeAsDatetime property.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.boolean
getUseFmtOnly()
Returns the current flag value for useFmtOnly.boolean
isStatementPoolingEnabled()
Returns whether statement pooling is enabled or not for this connection.CallableStatement
prepareCall(String sql, int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
Creates aCallableStatement
object that will generateResultSet
objects with the given type and concurrency.PreparedStatement
prepareStatement(String sql, int[] columnIndexes, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
Creates a defaultPreparedStatement
object capable of returning the auto-generated keys designated by the given array.PreparedStatement
prepareStatement(String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
Creates aPreparedStatement
object that will generateResultSet
objects with the given type, concurrency, and holdability.PreparedStatement
prepareStatement(String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
Creates a defaultPreparedStatement
object that has the capability to retrieve auto-generated keys.PreparedStatement
prepareStatement(String sql, String[] columnNames, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
Creates a defaultPreparedStatement
object capable of returning the auto-generated keys designated by the given array.void
setAccessTokenCallbackClass(String accessTokenCallbackClass)
Sets 'accessTokenCallbackClass' to the fully qualified class name of the implementing class forSQLServerAccessTokenCallback
.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 delayLoadingLobs)
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
setIPAddressPreference(String iPAddressPreference)
Sets the name of the preferred type of IP Address.void
setMsiTokenCacheTtl(int timeToLive)
Deprecated, for removal: This API element is subject to removal in a future version.Time-to-live is no longer supported for the cached Managed Identity tokens.void
setPrepareMethod(String prepareMethod)
Sets the behavior for the prepare method.void
setSendTimeAsDatetime(boolean sendTimeAsDateTimeValue)
Sets the value of the sendTimeAsDatetime connection property.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
setUseFmtOnly(boolean useFmtOnly)
Specifies the flag to use FMTONLY for parameter metadata queries.-
Methods inherited from interface java.sql.Connection
abort, beginRequest, clearWarnings, close, commit, createArrayOf, createBlob, createClob, createNClob, createSQLXML, createStatement, createStatement, createStatement, createStruct, endRequest, 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, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid, setTransactionIsolation, setTypeMap
-
Methods inherited from interface java.sql.Wrapper
isWrapperFor, unwrap
-
-
-
-
Field Detail
-
TRANSACTION_SNAPSHOT
static final int TRANSACTION_SNAPSHOT
Transaction types "TRANSACTION_SNAPSHOT corresponds to" "SET TRANSACTION ISOLATION LEVEL SNAPSHOT"- See Also:
- Constant Field Values
-
-
Method Detail
-
getClientConnectionId
UUID getClientConnectionId() throws SQLServerException
Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.- Returns:
- 16-byte GUID representing the connection ID of the most recent connection attempt. Or, NULL if there is a failure after the connection request is initiated and the pre-login handshake.
- Throws:
SQLServerException
- If any errors occur.
-
createStatement
Statement createStatement(int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
Creates aStatement
object that will generateResultSet
objects with the given type, concurrency, and holdability. This method is the same as thecreateStatement
method above, but it allows the default result set type, concurrency, and holdability to be overridden.- Parameters:
nType
- one of the followingResultSet
constants:ResultSet.TYPE_FORWARD_ONLY
,ResultSet.TYPE_SCROLL_INSENSITIVE
, orResultSet.TYPE_SCROLL_SENSITIVE
nConcur
- one of the followingResultSet
constants:ResultSet.CONCUR_READ_ONLY
orResultSet.CONCUR_UPDATABLE
nHold
- one of the followingResultSet
constants:ResultSet.HOLD_CURSORS_OVER_COMMIT
orResultSet.CLOSE_CURSORS_AT_COMMIT
stmtColEncSetting
- Specifies how data will be sent and received when reading and writing encrypted columns.- Returns:
- a new
Statement
object that will generateResultSet
objects with the given type, concurrency, and holdability - Throws:
SQLServerException
- if a database access error occurs, this method is called on a closed connection or the given parameters are notResultSet
constants indicating type, concurrency, and holdability
-
prepareStatement
PreparedStatement prepareStatement(String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
Creates a defaultPreparedStatement
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 anINSERT
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 thePreparedStatement
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 typeTYPE_FORWARD_ONLY
and have a concurrency level ofCONCUR_READ_ONLY
. The holdability of the created result sets can be determined by callingConnection.getHoldability()
.- Parameters:
sql
- an SQL statement that may contain one or more '?' IN parameter placeholdersflag
- a flag indicating whether auto-generated keys should be returned; one ofStatement.RETURN_GENERATED_KEYS
orStatement.NO_GENERATED_KEYS
stmtColEncSetting
- Specifies how data will be sent and received when reading and writing encrypted columns.- Returns:
- a new
PreparedStatement
object, containing the pre-compiled SQL statement, that will have the capability of returning auto-generated keys - Throws:
SQLServerException
- if a database access error occurs, this method is called on a closed connection or the given parameter is not aStatement
constant indicating whether auto-generated keys should be returned
-
prepareStatement
PreparedStatement prepareStatement(String sql, int[] columnIndexes, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
Creates a defaultPreparedStatement
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 anINSERT
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 thePreparedStatement
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 typeTYPE_FORWARD_ONLY
and have a concurrency level ofCONCUR_READ_ONLY
. The holdability of the created result sets can be determined by callingConnection.getHoldability()
.- Parameters:
sql
- an SQL statement that may contain one or more '?' IN parameter placeholderscolumnIndexes
- an array of column indexes indicating the columns that should be returned from the inserted row or rowsstmtColEncSetting
- Specifies how data will be sent and received when reading and writing encrypted columns.- Returns:
- a new
PreparedStatement
object, containing the pre-compiled statement, that is capable of returning the auto-generated keys designated by the given array of column indexes - Throws:
SQLServerException
- if a database access error occurs or this method is called on a closed connection
-
prepareStatement
PreparedStatement prepareStatement(String sql, String[] columnNames, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
Creates a defaultPreparedStatement
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 anINSERT
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 thePreparedStatement
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 typeTYPE_FORWARD_ONLY
and have a concurrency level ofCONCUR_READ_ONLY
. The holdability of the created result sets can be determined by callingConnection.getHoldability()
.- Parameters:
sql
- an SQL statement that may contain one or more '?' IN parameter placeholderscolumnNames
- an array of column names indicating the columns that should be returned from the inserted row or rowsstmtColEncSetting
- Specifies how data will be sent and received when reading and writing encrypted columns.- Returns:
- a new
PreparedStatement
object, containing the pre-compiled statement, that is capable of returning the auto-generated keys designated by the given array of column names - Throws:
SQLServerException
- if a database access error occurs or this method is called on a closed connection
-
prepareStatement
PreparedStatement prepareStatement(String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
Creates aPreparedStatement
object that will generateResultSet
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
- aString
object that is the SQL statement to be sent to the database; may contain one or more '?' IN parametersnType
- one of the followingResultSet
constants:ResultSet.TYPE_FORWARD_ONLY
,ResultSet.TYPE_SCROLL_INSENSITIVE
, orResultSet.TYPE_SCROLL_SENSITIVE
nConcur
- one of the followingResultSet
constants:ResultSet.CONCUR_READ_ONLY
orResultSet.CONCUR_UPDATABLE
resultSetHoldability
- one of the followingResultSet
constants:ResultSet.HOLD_CURSORS_OVER_COMMIT
orResultSet.CLOSE_CURSORS_AT_COMMIT
stmtColEncSetting
- Specifies how data will be sent and received when reading and writing encrypted columns.- Returns:
- a new
PreparedStatement
object, containing the pre-compiled SQL statement, that will generateResultSet
objects with the given type, concurrency, and holdability - Throws:
SQLServerException
- if a database access error occurs, this method is called on a closed connection or the given parameters are notResultSet
constants indicating type, concurrency, and holdability
-
prepareCall
CallableStatement prepareCall(String sql, int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
Creates aCallableStatement
object that will generateResultSet
objects with the given type and concurrency. This method is the same as theprepareCall
method above, but it allows the default result set type, result set concurrency type and holdability to be overridden.- Parameters:
sql
- aString
object that is the SQL statement to be sent to the database; may contain on or more '?' parametersnType
- one of the followingResultSet
constants:ResultSet.TYPE_FORWARD_ONLY
,ResultSet.TYPE_SCROLL_INSENSITIVE
, orResultSet.TYPE_SCROLL_SENSITIVE
nConcur
- one of the followingResultSet
constants:ResultSet.CONCUR_READ_ONLY
orResultSet.CONCUR_UPDATABLE
nHold
- one of the followingResultSet
constants:ResultSet.HOLD_CURSORS_OVER_COMMIT
orResultSet.CLOSE_CURSORS_AT_COMMIT
stmtColEncSetting
- Specifies how data will be sent and received when reading and writing encrypted columns.- Returns:
- a new
CallableStatement
object, containing the pre-compiled SQL statement, that will generateResultSet
objects with the given type, concurrency, and holdability - Throws:
SQLServerException
- if a database access error occurs, this method is called on a closed connection or the given parameters are notResultSet
constants indicating type, concurrency, and holdability
-
setSendTimeAsDatetime
void setSendTimeAsDatetime(boolean sendTimeAsDateTimeValue) throws SQLServerException
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
- enables/disables setting the sendTimeAsDatetime connection property. For more information about how the Microsoft JDBC Driver for SQL Server configures java.sql.Time values before sending them to the server, see Configuring How java.sql.Time Values are Sent to the Server.- Throws:
SQLServerException
- if a database access error occurs
-
setDatetimeParameterType
void setDatetimeParameterType(String datetimeParameterTypeValue) throws SQLServerException
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
- The datatype to use when encoding Java dates into SQL Server. Valid values are: datetime, datetime2 or datetimeoffset.- Throws:
SQLServerException
- if a database access error occurs
-
getSendTimeAsDatetime
boolean getSendTimeAsDatetime() throws SQLServerException
Returns the value of the sendTimeAsDatetime property.- Returns:
- boolean value of sendTimeAsDatetime
- Throws:
SQLServerException
- if a database access error occurs
-
getDatetimeParameterType
String getDatetimeParameterType() throws SQLServerException
Returns the value of the datetimeParameterType property.- Returns:
- The string value of the datetimeParameterType property.
- Throws:
SQLServerException
- if a database access error occurs
-
getDiscardedServerPreparedStatementCount
int getDiscardedServerPreparedStatementCount()
Returns the number of currently outstanding prepared statement un-prepare actions.- Returns:
- Returns the current value per the description.
-
closeUnreferencedPreparedStatementHandles
void closeUnreferencedPreparedStatementHandles()
Forces the un-prepare requests for any outstanding discarded prepared statements to be executed.
-
getEnablePrepareOnFirstPreparedStatementCall
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().- Returns:
- Returns the current setting per the description.
-
setEnablePrepareOnFirstPreparedStatementCall
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
- Changes the setting per the description.
-
getPrepareMethod
String getPrepareMethod()
Returns the behavior for a specific connection instance.PrepareMethod
- Returns:
- Returns current setting for prepareMethod connection property.
-
setPrepareMethod
void setPrepareMethod(String prepareMethod)
Sets the behavior for the prepare method.PrepareMethod
- Parameters:
prepareMethod
- Changes the setting as per description
-
getServerPreparedStatementDiscardThreshold
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().- Returns:
- Returns the current setting per the description.
-
setServerPreparedStatementDiscardThreshold
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
- Changes the setting per the description.
-
setStatementPoolingCacheSize
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
- The new cache size.
-
getStatementPoolingCacheSize
int getStatementPoolingCacheSize()
Returns the size of the prepared statement cache for this connection. A value less than 1 means no cache.- Returns:
- Returns the current setting per the description.
-
isStatementPoolingEnabled
boolean isStatementPoolingEnabled()
Returns whether statement pooling is enabled or not for this connection.- Returns:
- Returns the current setting per the description.
-
getStatementHandleCacheEntryCount
int getStatementHandleCacheEntryCount()
Returns the current number of pooled prepared statement handles.- Returns:
- Returns the current setting per the description.
-
setDisableStatementPooling
void setDisableStatementPooling(boolean value)
Sets the value to Disable/enable statement pooling.- Parameters:
value
- true to disable statement pooling, false to enable it.
-
getDisableStatementPooling
boolean getDisableStatementPooling()
Returns the value whether statement pooling is disabled.- Returns:
- true if statement pooling is disabled, false if it is enabled.
-
getUseFmtOnly
boolean getUseFmtOnly()
Returns the current flag value for useFmtOnly.- Returns:
- 'useFmtOnly' property value.
-
setUseFmtOnly
void setUseFmtOnly(boolean useFmtOnly)
Specifies the flag to use FMTONLY for parameter metadata queries.- Parameters:
useFmtOnly
- boolean value for 'useFmtOnly'.
-
getDelayLoadingLobs
boolean getDelayLoadingLobs()
Returns the current flag value for delayLoadingLobs.- Returns:
- 'delayLoadingLobs' property value.
-
setDelayLoadingLobs
void setDelayLoadingLobs(boolean delayLoadingLobs)
Specifies the flag to immediately load LOB objects into memory.- Parameters:
delayLoadingLobs
- boolean value for 'delayLoadingLobs'.
-
setIPAddressPreference
void setIPAddressPreference(String iPAddressPreference)
Sets the name of the preferred type of IP Address.- Parameters:
iPAddressPreference
- A String that contains the preferred type of IP Address.
-
getIPAddressPreference
String getIPAddressPreference()
Gets the name of the preferred type of IP Address.- Returns:
- IPAddressPreference A String that contains the preferred type of IP Address.
-
getMsiTokenCacheTtl
@Deprecated(since="12.1.0", forRemoval=true) int getMsiTokenCacheTtl()
Deprecated, for removal: This API element is subject to removal in a future version.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.- Returns:
- Method will always return 0.
-
setMsiTokenCacheTtl
@Deprecated(since="12.1.0", forRemoval=true) void setMsiTokenCacheTtl(int timeToLive)
Deprecated, for removal: This API element is subject to removal in a future version.Time-to-live is no longer supported for the cached Managed Identity tokens.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
- Time-to-live is no longer supported.
-
getAccessTokenCallbackClass
String getAccessTokenCallbackClass()
Returns the fully qualified class name of the implementing class forSQLServerAccessTokenCallback
.- Returns:
- accessTokenCallbackClass
-
setAccessTokenCallbackClass
void setAccessTokenCallbackClass(String accessTokenCallbackClass)
Sets 'accessTokenCallbackClass' to the fully qualified class name of the implementing class forSQLServerAccessTokenCallback
.- Parameters:
accessTokenCallbackClass
-
-
-