com.isomorphic.sql

## Class SQLConnectionManager

- java.lang.Object
- - com.isomorphic.base.Base
  - - com.isomorphic.sql.SQLConnectionManager

-     public class SQLConnectionManager
      extends Base

  `SQLConnectionManager` provides methods for initializing and getting connections to databases.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `free(java.sql.Connection conn)` Frees a connection previously obtained via SQLConnectionManager.
    `static java.sql.Connection` | `getConnection()` Gets a new connection to the default database given in the SmartClient configuration file.
    `static java.sql.Connection` | `getConnection(java.lang.String serverName)` Gets a new connection to the database given in the SmartClient configuration file by the parameter database name.

- - ### Method Detail

    - #### getConnection

          public static java.sql.Connection getConnection()
                                                   throws java.sql.SQLException

      Gets a new connection to the default database given in the SmartClient configuration file. The `server.properties` configuration file is located in the `isomorphicConfig` directory of the SmartClient installation, and contains the connection parameters for the database given by the `sql.defaultDatabase` property.

      This method returns a fresh connection to the database - either borrowed from the pool if connection pooling is switched on, or a completely new connection if pooling is off, or there are no free connections in the pool. The connection returned is not the same connection as that used to implement auto-managed transactions (see `DSRequest.shouldJoinTransaction()`), which leads to two considerations

      - Connections obtained by this method are not managed by framework code, so your application code must call `SQLConnectionManager.free(Connection)` to return the connection. Failure to do so will result in a connection leak
      - If you use a connection obtained by this method in the middle of a transactional update bear in mind that it will not have visibility of rows inserted or changed on the transactional connection. Also, be careful not to introduce deadlocks if running updates on a separate connection in the middle of a transactional update, especially if the same tables are involved

      If you instead want access to the database connection used by the framework for automatically managed transactions, see `DataSource.getTransactionObject(com.isomorphic.datasource.DSRequest)`, and also this Showcase example: Transactional User Operations. Note that you should not call `free()` on the connection returned by this method - it is managed by the framework.

      Returns:
        a `java.sql.Connection` session with the default database
      Throws:
        `java.sql.SQLException`
      See Also:
        `SQLConnectionManager.free(Connection conn)`

    - #### getConnection

          public static java.sql.Connection getConnection(java.lang.String serverName)
                                                   throws java.sql.SQLException

      Gets a new connection to the database given in the SmartClient configuration file by the parameter database name. The `server.properties` configuration file is located in the `isomorphicConfig` directory of the SmartClient installation, and contains the connection parameters for the database given by name.

      Note that the same caveats apply to this method as apply to the no-parameter version `SQLConnectionManager.getConnection()`

      Parameters:
        `serverName` - the name of the database as given in the configuration file
      Returns:
        a `java.sql.Connection` session with the database
      Throws:
        `java.sql.SQLException`
      See Also:
        `SQLConnectionManager.free(Connection conn)`

    - #### free

          public static void free(java.sql.Connection conn)
                           throws java.sql.SQLException

      Frees a connection previously obtained via SQLConnectionManager. Note that you are responsible for freeing any connections you borrow from the SQLConnectionManager; if you neglect to do so, you will cause connection leaks.
      Parameters:
        `conn` - The Connection object to free
      Throws:
        `java.sql.SQLException`
      See Also:
        `SQLConnectionManager.getConnection()`