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

## Class SQLServerConnection

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

All Implemented Interfaces:
  `ISQLServerConnection`, `Serializable`, `AutoCloseable`, `Connection`, `Wrapper`

Direct Known Subclasses:
  `SQLServerConnection43`

    public class SQLServerConnection
    extends Object
    implements ISQLServerConnection, 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

See Also:
  Serialized Form

### Field Summary

### Fields inherited from interface java.sql.Connection

`TRANSACTION_NONE, TRANSACTION_READ_COMMITTED, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE`

### Fields inherited from interface com.microsoft.sqlserver.jdbc.ISQLServerConnection

`TRANSACTION_SNAPSHOT`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
`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.
`Array` `createArrayOf​(String typeName, Object[] elements)`
`Blob` `createBlob()`
`Clob` `createClob()`
`NClob` `createNClob()`
`SQLXML` `createSQLXML()`
`Statement` `createStatement()`
`Statement` `createStatement​(int resultSetType, int resultSetConcurrency)`
`Statement` `createStatement​(int nType, int nConcur, int resultSetHoldability)`
`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.
`Struct` `createStruct​(String typeName, Object[] attributes)`
`boolean` `getAutoCommit()`
`String` `getCatalog()`
`UUID` `getClientConnectionId()` Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.
`Properties` `getClientInfo()`
`String` `getClientInfo​(String name)`
`static Map<String,​List<String>>` `getColumnEncryptionTrustedMasterKeyPaths()` Returns the Trusted Master Key Paths.
`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()`
`String` `getIPAddressPreference()` Gets the name of the preferred type of IP Address.
`DatabaseMetaData` `getMetaData()`
`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.
`int` `getNetworkTimeout()`
`String` `getPrepareMethod()` Returns the behavior for a specific connection instance.
`String` `getSchema()`
`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.
`int` `getTransactionIsolation()`
`Map<String,​Class<?>>` `getTypeMap()`
`boolean` `getUseBulkCopyForBatchInsert()` Returns the useBulkCopyForBatchInsert value.
`boolean` `getUseFmtOnly()` Returns the current flag value for useFmtOnly.
`SQLWarning` `getWarnings()`
`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)`
`String` `nativeSQL​(String sql)`
`protected boolean` `needsReconnect()` Returns if Federated Authentication is in use or is about to expire soon
`CallableStatement` `prepareCall​(String sql)`
`CallableStatement` `prepareCall​(String sql, int resultSetType, int resultSetConcurrency)`
`CallableStatement` `prepareCall​(String sql, int nType, int nConcur, int resultSetHoldability)`
`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.
`PreparedStatement` `prepareStatement​(String sql)`
`PreparedStatement` `prepareStatement​(String sql, int flag)`
`PreparedStatement` `prepareStatement​(String sql, int[] columnIndexes)`
`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.
`PreparedStatement` `prepareStatement​(String sql, int resultSetType, int resultSetConcurrency)`
`PreparedStatement` `prepareStatement​(String sql, int nType, int nConcur, int resultSetHoldability)`
`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.
`PreparedStatement` `prepareStatement​(String sql, int flag, SQLServerStatementColumnEncryptionSetting stmtColEncSetting)` Creates a default `PreparedStatement` object that has the capability to retrieve auto-generated keys.
`PreparedStatement` `prepareStatement​(String sql, String[] columnNames)`
`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.
`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)`
`static void` `removeColumnEncryptionTrustedMasterKeyPaths​(String server)` Removes the trusted Master key Path from the columnEncryptionTrustedMasterKeyPaths.
`void` `rollback()`
`void` `rollback​(Savepoint s)`
`void` `setAutoCommit​(boolean newAutoCommitMode)`
`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` `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` `setNetworkTimeout​(Executor executor, int timeout)`
`void` `setPrepareMethod​(String prepareMethod)` Sets the behavior for the prepare method.
`void` `setReadOnly​(boolean readOnly)`
`Savepoint` `setSavepoint()`
`Savepoint` `setSavepoint​(String sName)`
`void` `setSchema​(String schema)`
`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` `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` `setUseFmtOnly​(boolean useFmtOnly)` Specifies the flag to use FMTONLY for parameter metadata queries.
`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.
`<T> T` `unwrap​(Class<T> iface)`
`static void` `updateColumnEncryptionTrustedMasterKeyPaths​(String server, List<String> trustedKeyPaths)` Updates the columnEncryptionTrustedMasterKeyPaths with the new Server and trustedKeyPaths.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface java.sql.Connection

`beginRequest, endRequest, setShardingKey, setShardingKey, setShardingKeyIfValid, setShardingKeyIfValid`

### Method Detail

#### getUseBulkCopyForBatchInsert

    public boolean getUseBulkCopyForBatchInsert()

Returns the useBulkCopyForBatchInsert value.

Returns:
  flag for using Bulk Copy API for batch insert operations.

#### setUseBulkCopyForBatchInsert

    public void setUseBulkCopyForBatchInsert​(boolean useBulkCopyForBatchInsert)

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

Parameters:
  `useBulkCopyForBatchInsert` - boolean value for useBulkCopyForBatchInsert.

#### getSendTimeAsDatetime

    public final boolean getSendTimeAsDatetime()

Description copied from interface: `ISQLServerConnection`
Returns the value of the sendTimeAsDatetime property.

Specified by:
  `getSendTimeAsDatetime` in interface `ISQLServerConnection`
Returns:
  boolean value of sendTimeAsDatetime

#### getDatetimeParameterType

    public final String getDatetimeParameterType()

Description copied from interface: `ISQLServerConnection`
Returns the value of the datetimeParameterType property.

Specified by:
  `getDatetimeParameterType` in interface `ISQLServerConnection`
Returns:
  The string value of the datetimeParameterType property.

#### getDelayLoadingLobs

    public boolean getDelayLoadingLobs()

Description copied from interface: `ISQLServerConnection`
Returns the current flag value for delayLoadingLobs.

Specified by:
  `getDelayLoadingLobs` in interface `ISQLServerConnection`
Returns:
  'delayLoadingLobs' property value.

#### setDelayLoadingLobs

    public void setDelayLoadingLobs​(boolean b)

Description copied from interface: `ISQLServerConnection`
Specifies the flag to immediately load LOB objects into memory.

Specified by:
  `setDelayLoadingLobs` in interface `ISQLServerConnection`
Parameters:
  `b` - boolean value for 'delayLoadingLobs'.

#### registerColumnEncryptionKeyStoreProviders

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

Registers key store providers in the globalCustomColumnEncryptionKeyStoreProviders.

Parameters:
  `clientKeyStoreProviders` - a map containing the store providers information.
Throws:
  `SQLServerException` - when an error occurs

#### unregisterColumnEncryptionKeyStoreProviders

    public static void unregisterColumnEncryptionKeyStoreProviders()

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

#### registerColumnEncryptionKeyStoreProvidersOnConnection

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

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

#### 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

#### 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

#### removeColumnEncryptionTrustedMasterKeyPaths

    public static void removeColumnEncryptionTrustedMasterKeyPaths​(String server)

Removes the trusted Master key Path from the columnEncryptionTrustedMasterKeyPaths.

Parameters:
  `server` - String server name

#### getColumnEncryptionTrustedMasterKeyPaths

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

Returns the Trusted Master Key Paths.

Returns:
  columnEncryptionTrustedMasterKeyPaths.

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

#### getClientConnectionId

    public UUID getClientConnectionId()
                               throws SQLServerException

Description copied from interface: `ISQLServerConnection`
Returns the connection ID of the most recent connection attempt, regardless of whether the attempt succeeded or failed.

Specified by:
  `getClientConnectionId` in interface `ISQLServerConnection`
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.

#### toString

    public String toString()

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

Overrides:
  `toString` in class `Object`

#### needsReconnect

    protected boolean needsReconnect()

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

Returns:
  true/false

#### createStatement

    public Statement createStatement()
                              throws SQLServerException

Specified by:
  `createStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql)
                                       throws SQLServerException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareCall

    public CallableStatement prepareCall​(String sql)
                                  throws SQLServerException

Specified by:
  `prepareCall` in interface `Connection`
Throws:
  `SQLServerException`

#### nativeSQL

    public String nativeSQL​(String sql)
                     throws SQLServerException

Specified by:
  `nativeSQL` in interface `Connection`
Throws:
  `SQLServerException`

#### setAutoCommit

    public void setAutoCommit​(boolean newAutoCommitMode)
                       throws SQLServerException

Specified by:
  `setAutoCommit` in interface `Connection`
Throws:
  `SQLServerException`

#### getAutoCommit

    public boolean getAutoCommit()
                          throws SQLServerException

Specified by:
  `getAutoCommit` in interface `Connection`
Throws:
  `SQLServerException`

#### commit

    public void commit()
                throws SQLServerException

Specified by:
  `commit` in interface `Connection`
Throws:
  `SQLServerException`

#### commit

    public void commit​(boolean delayedDurability)
                throws SQLServerException

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

#### rollback

    public void rollback()
                  throws SQLServerException

Specified by:
  `rollback` in interface `Connection`
Throws:
  `SQLServerException`

#### abort

    public void abort​(Executor executor)
               throws SQLException

Specified by:
  `abort` in interface `Connection`
Throws:
  `SQLException`

#### close

    public void close()
               throws SQLServerException

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Connection`
Throws:
  `SQLServerException`

#### isClosed

    public boolean isClosed()
                     throws SQLServerException

Specified by:
  `isClosed` in interface `Connection`
Throws:
  `SQLServerException`

#### getMetaData

    public DatabaseMetaData getMetaData()
                                 throws SQLServerException

Specified by:
  `getMetaData` in interface `Connection`
Throws:
  `SQLServerException`

#### setReadOnly

    public void setReadOnly​(boolean readOnly)
                     throws SQLServerException

Specified by:
  `setReadOnly` in interface `Connection`
Throws:
  `SQLServerException`

#### isReadOnly

    public boolean isReadOnly()
                       throws SQLServerException

Specified by:
  `isReadOnly` in interface `Connection`
Throws:
  `SQLServerException`

#### setCatalog

    public void setCatalog​(String catalog)
                    throws SQLServerException

Specified by:
  `setCatalog` in interface `Connection`
Throws:
  `SQLServerException`

#### getCatalog

    public String getCatalog()
                      throws SQLServerException

Specified by:
  `getCatalog` in interface `Connection`
Throws:
  `SQLServerException`

#### setTransactionIsolation

    public void setTransactionIsolation​(int level)
                                 throws SQLServerException

Specified by:
  `setTransactionIsolation` in interface `Connection`
Throws:
  `SQLServerException`

#### getTransactionIsolation

    public int getTransactionIsolation()
                                throws SQLServerException

Specified by:
  `getTransactionIsolation` in interface `Connection`
Throws:
  `SQLServerException`

#### getWarnings

    public SQLWarning getWarnings()
                           throws SQLServerException

Specified by:
  `getWarnings` in interface `Connection`
Throws:
  `SQLServerException`

#### clearWarnings

    public void clearWarnings()
                       throws SQLServerException

Specified by:
  `clearWarnings` in interface `Connection`
Throws:
  `SQLServerException`

#### createStatement

    public Statement createStatement​(int resultSetType,
                                     int resultSetConcurrency)
                              throws SQLServerException

Specified by:
  `createStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              int resultSetType,
                                              int resultSetConcurrency)
                                       throws SQLServerException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareCall

    public CallableStatement prepareCall​(String sql,
                                         int resultSetType,
                                         int resultSetConcurrency)
                                  throws SQLServerException

Specified by:
  `prepareCall` in interface `Connection`
Throws:
  `SQLServerException`

#### setTypeMap

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

Specified by:
  `setTypeMap` in interface `Connection`
Throws:
  `SQLException`

#### getTypeMap

    public Map<String,​Class<?>> getTypeMap()
                                          throws SQLServerException

Specified by:
  `getTypeMap` in interface `Connection`
Throws:
  `SQLServerException`

#### createStatement

    public Statement createStatement​(int nType,
                                     int nConcur,
                                     int resultSetHoldability)
                              throws SQLServerException

Specified by:
  `createStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### createStatement

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

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `createStatement` in interface `ISQLServerConnection`
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 `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

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

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareStatement

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

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `prepareStatement` in interface `ISQLServerConnection`
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

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

Specified by:
  `prepareCall` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareCall

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

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `prepareCall` in interface `ISQLServerConnection`
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`
  `resultSetHoldability` - one of the following `ResultSet` constants: `ResultSet.HOLD_CURSORS_OVER_COMMIT` or `ResultSet.CLOSE_CURSORS_AT_COMMIT`
  `stmtColEncSetiing` - 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

#### prepareStatement

    public PreparedStatement prepareStatement​(String sql,
                                              int flag)
                                       throws SQLServerException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareStatement

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

Description copied from interface: `ISQLServerConnection`
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()`.

Specified by:
  `prepareStatement` in interface `ISQLServerConnection`
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

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

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareStatement

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

Description copied from interface: `ISQLServerConnection`
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()`.

Specified by:
  `prepareStatement` in interface `ISQLServerConnection`
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

    public PreparedStatement prepareStatement​(String sql,
                                              String[] columnNames)
                                       throws SQLServerException

Specified by:
  `prepareStatement` in interface `Connection`
Throws:
  `SQLServerException`

#### prepareStatement

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

Description copied from interface: `ISQLServerConnection`
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()`.

Specified by:
  `prepareStatement` in interface `ISQLServerConnection`
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

#### releaseSavepoint

    public void releaseSavepoint​(Savepoint savepoint)
                          throws SQLException

Specified by:
  `releaseSavepoint` in interface `Connection`
Throws:
  `SQLException`

#### setSavepoint

    public Savepoint setSavepoint​(String sName)
                           throws SQLServerException

Specified by:
  `setSavepoint` in interface `Connection`
Throws:
  `SQLServerException`

#### setSavepoint

    public Savepoint setSavepoint()
                           throws SQLServerException

Specified by:
  `setSavepoint` in interface `Connection`
Throws:
  `SQLServerException`

#### rollback

    public void rollback​(Savepoint s)
                  throws SQLServerException

Specified by:
  `rollback` in interface `Connection`
Throws:
  `SQLServerException`

#### getHoldability

    public int getHoldability()
                       throws SQLServerException

Specified by:
  `getHoldability` in interface `Connection`
Throws:
  `SQLServerException`

#### setHoldability

    public void setHoldability​(int holdability)
                        throws SQLServerException

Specified by:
  `setHoldability` in interface `Connection`
Throws:
  `SQLServerException`

#### getNetworkTimeout

    public int getNetworkTimeout()
                          throws SQLException

Specified by:
  `getNetworkTimeout` in interface `Connection`
Throws:
  `SQLException`

#### setNetworkTimeout

    public void setNetworkTimeout​(Executor executor,
                                  int timeout)
                           throws SQLException

Specified by:
  `setNetworkTimeout` in interface `Connection`
Throws:
  `SQLException`

#### getSchema

    public String getSchema()
                     throws SQLException

Specified by:
  `getSchema` in interface `Connection`
Throws:
  `SQLException`

#### setSchema

    public void setSchema​(String schema)
                   throws SQLException

Specified by:
  `setSchema` in interface `Connection`
Throws:
  `SQLException`

#### setSendTimeAsDatetime

    public void setSendTimeAsDatetime​(boolean sendTimeAsDateTimeValue)

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `setSendTimeAsDatetime` in interface `ISQLServerConnection`
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.

#### setDatetimeParameterType

    public void setDatetimeParameterType​(String datetimeParameterTypeValue)
                                  throws SQLServerException

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `setDatetimeParameterType` in interface `ISQLServerConnection`
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

#### setUseFmtOnly

    public void setUseFmtOnly​(boolean useFmtOnly)

Description copied from interface: `ISQLServerConnection`
Specifies the flag to use FMTONLY for parameter metadata queries.

Specified by:
  `setUseFmtOnly` in interface `ISQLServerConnection`
Parameters:
  `useFmtOnly` - boolean value for 'useFmtOnly'.

#### getUseFmtOnly

    public final boolean getUseFmtOnly()

Description copied from interface: `ISQLServerConnection`
Returns the current flag value for useFmtOnly.

Specified by:
  `getUseFmtOnly` in interface `ISQLServerConnection`
Returns:
  'useFmtOnly' property value.

#### createArrayOf

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

Specified by:
  `createArrayOf` in interface `Connection`
Throws:
  `SQLException`

#### createBlob

    public Blob createBlob()
                    throws SQLException

Specified by:
  `createBlob` in interface `Connection`
Throws:
  `SQLException`

#### createClob

    public Clob createClob()
                    throws SQLException

Specified by:
  `createClob` in interface `Connection`
Throws:
  `SQLException`

#### createNClob

    public NClob createNClob()
                      throws SQLException

Specified by:
  `createNClob` in interface `Connection`
Throws:
  `SQLException`

#### createSQLXML

    public SQLXML createSQLXML()
                        throws SQLException

Specified by:
  `createSQLXML` in interface `Connection`
Throws:
  `SQLException`

#### createStruct

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

Specified by:
  `createStruct` in interface `Connection`
Throws:
  `SQLException`

#### getClientInfo

    public Properties getClientInfo()
                             throws SQLException

Specified by:
  `getClientInfo` in interface `Connection`
Throws:
  `SQLException`

#### getClientInfo

    public String getClientInfo​(String name)
                         throws SQLException

Specified by:
  `getClientInfo` in interface `Connection`
Throws:
  `SQLException`

#### setClientInfo

    public void setClientInfo​(Properties properties)
                       throws SQLClientInfoException

Specified by:
  `setClientInfo` in interface `Connection`
Throws:
  `SQLClientInfoException`

#### setClientInfo

    public void setClientInfo​(String name,
                              String value)
                       throws SQLClientInfoException

Specified by:
  `setClientInfo` in interface `Connection`
Throws:
  `SQLClientInfoException`

#### isValid

    public boolean isValid​(int timeout)
                    throws SQLException

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.

Specified by:
  `isValid` in interface `Connection`
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:
  `SQLException` - if the value supplied for the timeout is less than 0.

#### isWrapperFor

    public boolean isWrapperFor​(Class<?> iface)
                         throws SQLException

Specified by:
  `isWrapperFor` in interface `Wrapper`
Throws:
  `SQLException`

#### unwrap

    public <T> T unwrap​(Class<T> iface)
                 throws SQLException

Specified by:
  `unwrap` in interface `Wrapper`
Throws:
  `SQLException`

#### setColumnEncryptionKeyCacheTtl

    public static void setColumnEncryptionKeyCacheTtl​(int columnEncryptionKeyCacheTTL,
                                                      TimeUnit unit)
                                               throws SQLServerException

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

#### getDiscardedServerPreparedStatementCount

    public int getDiscardedServerPreparedStatementCount()

Description copied from interface: `ISQLServerConnection`
Returns the number of currently outstanding prepared statement un-prepare actions.

Specified by:
  `getDiscardedServerPreparedStatementCount` in interface `ISQLServerConnection`
Returns:
  Returns the current value per the description.

#### closeUnreferencedPreparedStatementHandles

    public void closeUnreferencedPreparedStatementHandles()

Description copied from interface: `ISQLServerConnection`
Forces the un-prepare requests for any outstanding discarded prepared statements to be executed.

Specified by:
  `closeUnreferencedPreparedStatementHandles` in interface `ISQLServerConnection`

#### getEnablePrepareOnFirstPreparedStatementCall

    public boolean getEnablePrepareOnFirstPreparedStatementCall()

Description copied from interface: `ISQLServerConnection`
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().

Specified by:
  `getEnablePrepareOnFirstPreparedStatementCall` in interface `ISQLServerConnection`
Returns:
  Returns the current setting per the description.

#### setEnablePrepareOnFirstPreparedStatementCall

    public void setEnablePrepareOnFirstPreparedStatementCall​(boolean value)

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `setEnablePrepareOnFirstPreparedStatementCall` in interface `ISQLServerConnection`
Parameters:
  `value` - Changes the setting per the description.

#### getPrepareMethod

    public String getPrepareMethod()

Description copied from interface: `ISQLServerConnection`
Returns the behavior for a specific connection instance. `PrepareMethod`

Specified by:
  `getPrepareMethod` in interface `ISQLServerConnection`
Returns:
  Returns current setting for prepareMethod connection property.

#### setPrepareMethod

    public void setPrepareMethod​(String prepareMethod)

Description copied from interface: `ISQLServerConnection`
Sets the behavior for the prepare method. `PrepareMethod`

Specified by:
  `setPrepareMethod` in interface `ISQLServerConnection`
Parameters:
  `prepareMethod` - Changes the setting as per description

#### getServerPreparedStatementDiscardThreshold

    public int getServerPreparedStatementDiscardThreshold()

Description copied from interface: `ISQLServerConnection`
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().

Specified by:
  `getServerPreparedStatementDiscardThreshold` in interface `ISQLServerConnection`
Returns:
  Returns the current setting per the description.

#### setServerPreparedStatementDiscardThreshold

    public void setServerPreparedStatementDiscardThreshold​(int value)

Description copied from interface: `ISQLServerConnection`
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.

Specified by:
  `setServerPreparedStatementDiscardThreshold` in interface `ISQLServerConnection`
Parameters:
  `value` - Changes the setting per the description.

#### getDisableStatementPooling

    public boolean getDisableStatementPooling()

Description copied from interface: `ISQLServerConnection`
Returns the value whether statement pooling is disabled.

Specified by:
  `getDisableStatementPooling` in interface `ISQLServerConnection`
Returns:
  true if statement pooling is disabled, false if it is enabled.

#### setDisableStatementPooling

    public void setDisableStatementPooling​(boolean value)

Description copied from interface: `ISQLServerConnection`
Sets the value to Disable/enable statement pooling.

Specified by:
  `setDisableStatementPooling` in interface `ISQLServerConnection`
Parameters:
  `value` - true to disable statement pooling, false to enable it.

#### getStatementPoolingCacheSize

    public int getStatementPoolingCacheSize()

Description copied from interface: `ISQLServerConnection`
Returns the size of the prepared statement cache for this connection. A value less than 1 means no cache.

Specified by:
  `getStatementPoolingCacheSize` in interface `ISQLServerConnection`
Returns:
  Returns the current setting per the description.

#### getStatementHandleCacheEntryCount

    public int getStatementHandleCacheEntryCount()

Description copied from interface: `ISQLServerConnection`
Returns the current number of pooled prepared statement handles.

Specified by:
  `getStatementHandleCacheEntryCount` in interface `ISQLServerConnection`
Returns:
  Returns the current setting per the description.

#### isStatementPoolingEnabled

    public boolean isStatementPoolingEnabled()

Description copied from interface: `ISQLServerConnection`
Returns whether statement pooling is enabled or not for this connection.

Specified by:
  `isStatementPoolingEnabled` in interface `ISQLServerConnection`
Returns:
  Returns the current setting per the description.

#### setStatementPoolingCacheSize

    public void setStatementPoolingCacheSize​(int value)

Description copied from interface: `ISQLServerConnection`
Sets the size of the prepared statement cache for this connection. A value less than 1 means no cache.

Specified by:
  `setStatementPoolingCacheSize` in interface `ISQLServerConnection`
Parameters:
  `value` - The new cache size.

#### getMsiTokenCacheTtl

    @Deprecated(since="12.1.0",
                forRemoval=true)
    public 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.
Description copied from interface: `ISQLServerConnection`
This method will always return 0 and is for backwards compatibility only.

Specified by:
  `getMsiTokenCacheTtl` in interface `ISQLServerConnection`
Returns:
  Method will always return 0.

#### setMsiTokenCacheTtl

    @Deprecated(since="12.1.0",
                forRemoval=true)
    public 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. This method is a no-op for backwards compatibility only.
Description copied from interface: `ISQLServerConnection`
Time-to-live is no longer supported for the cached Managed Identity tokens. This method is a no-op for backwards compatibility only.

Specified by:
  `setMsiTokenCacheTtl` in interface `ISQLServerConnection`
Parameters:
  `timeToLive` - Time-to-live is no longer supported.

#### setIPAddressPreference

    public void setIPAddressPreference​(String iPAddressPreference)

Description copied from interface: `ISQLServerConnection`
Sets the name of the preferred type of IP Address.

Specified by:
  `setIPAddressPreference` in interface `ISQLServerConnection`
Parameters:
  `iPAddressPreference` - A String that contains the preferred type of IP Address.

#### getIPAddressPreference

    public String getIPAddressPreference()

Description copied from interface: `ISQLServerConnection`
Gets the name of the preferred type of IP Address.

Specified by:
  `getIPAddressPreference` in interface `ISQLServerConnection`
Returns:
  IPAddressPreference A String that contains the preferred type of IP Address.