Module com.microsoft.sqlserver.jdbc
Package com.microsoft.sqlserver.jdbc

Interface ISQLServerConnection

All Superinterfaces:
java.lang.AutoCloseable, java.sql.Connection, java.sql.Wrapper
All Known Subinterfaces:
ISQLServerConnection43
All Known Implementing Classes:
SQLServerConnection, SQLServerConnection43
public interface ISQLServerConnection
extends java.sql.Connection
Provides an interface to the SQLServerConnection and SQLServerConnectionPoolProxy 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

    Modifier and Type Method Description
    void closeUnreferencedPreparedStatementHandles()
    Forces the un-prepare requests for any outstanding discarded prepared statements to be executed.
    java.sql.Statement createStatement​(int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
    Creates a Statement object that will generate ResultSet objects with the given type, concurrency, and holdability.
    java.util.UUID getClientConnectionId()
    Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.
    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.
    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.
    java.sql.CallableStatement prepareCall​(java.lang.String sql, int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
    Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency.
    java.sql.PreparedStatement prepareStatement​(java.lang.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​(java.lang.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​(java.lang.String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
    Creates a default PreparedStatement object that has the capability to retrieve auto-generated keys.
    java.sql.PreparedStatement prepareStatement​(java.lang.String sql, java.lang.String[] columnNames, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)
    Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array.
    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 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 Details

    • TRANSACTION_SNAPSHOT

      static final int TRANSACTION_SNAPSHOT
      Transaction types "TRANSACTION_SNAPSHOT corresponds to" "SET TRANSACTION ISOLATION LEVEL SNAPSHOT"
      See Also:
      Constant Field Values

  • Method Details

    • getClientConnectionId

      java.util.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

      java.sql.Statement createStatement​(int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
      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 - one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
      nConcur - one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
      nHold - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.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 generate ResultSet 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 not ResultSet constants indicating type, concurrency, and holdability

    • prepareStatement

      java.sql.PreparedStatement prepareStatement​(java.lang.String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
      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 Connection.getHoldability().

      Parameters:
      sql - an SQL statement that may contain one or more '?' IN parameter placeholders
      flag - a flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.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 a Statement constant indicating whether auto-generated keys should be returned

    • prepareStatement

      java.sql.PreparedStatement prepareStatement​(java.lang.String sql, int[] columnIndexes, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
      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 Connection.getHoldability().

      Parameters:
      sql - an SQL statement that may contain one or more '?' IN parameter placeholders
      columnIndexes - an array of column indexes indicating the columns that should be returned from the inserted row or rows
      stmtColEncSetting - 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

      java.sql.PreparedStatement prepareStatement​(java.lang.String sql, java.lang.String[] columnNames, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
      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 Connection.getHoldability().

      Parameters:
      sql - an SQL statement that may contain one or more '?' IN parameter placeholders
      columnNames - an array of column names indicating the columns that should be returned from the inserted row or rows
      stmtColEncSetting - 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

      java.sql.PreparedStatement prepareStatement​(java.lang.String sql, int nType, int nConcur, int resultSetHoldability, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
      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 - a String object that is the SQL statement to be sent to the database; may contain one or more '?' IN parameters
      nType - one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
      nConcur - one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
      resultSetHoldability - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.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 generate ResultSet 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 not ResultSet constants indicating type, concurrency, and holdability

    • prepareCall

      java.sql.CallableStatement prepareCall​(java.lang.String sql, int nType, int nConcur, int nHold, SQLServerStatementColumnEncryptionSetting stmtColEncSetting) throws SQLServerException
      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 - a String object that is the SQL statement to be sent to the database; may contain on or more '?' parameters
      nType - one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
      nConcur - one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
      nHold - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.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 generate ResultSet 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 not ResultSet 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

    • 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

    • 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.

    • 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 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. 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'.