Package com.isomorphic.datasource

# Class DataSourceManager

java.lang.Object
com.isomorphic.base.Base
com.isomorphic.datasource.DataSourceManager

All Implemented Interfaces:
  `com.isomorphic.base.IAutoConfigurable`

public class DataSourceManager extends com.isomorphic.base.Base
This class contains static utility methods for obtaining a DataSource instance from the pool, and returning those instances. Note that you need to take care to free (return) every DataSource object you obtain using these APIs, or you will leak objects.

Note that these APIs are only intended for use in cases where your code is not running in the context of an `RPCManager`, such as a non-servlet application or some init-time logic. For normal client-server transaction code that has access to an RPCManager, use `RPCManager.getDataSource()` instead; this API tracks and frees all DataSource instances it returns at the end of the transaction cycle, so you don't need to worry about your application code leaking DataSource objects.

Scan the client-side documentation for "standaloneDataSource" for details and examples of how to use DataSource features in a non-servlet application

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `clearPooledInstances(String dsName)`
  Clears all instances of the named DataSource from the pool
  `static void`
  `free(DataSource ds)`
  Frees the parameter DataSource object by returning it to the pool.
  `static void`
  `freeDataSource(DataSource ds)`
  Frees the parameter DataSource object by returning it to the pool
  `static DataSource`
  `get(String name)`
  Returns a DataSource object from the pool, creating a new instance if necessary.
  `static DataSource`
  `getDataSource(String name)`
  Returns a DataSource object from the pool, creating a new instance if necessary.
  `static Set<String>`
  `getDefinedDataSourceIdentifiers()`
  Returns a Set containing the identifiers of each datasource known to the DataSourceManager.
  `static com.isomorphic.pool.PoolManager`
  `hotSwapPool()`
  Replaces the global DataSource pool with a new one.
  `static void`
  `restartPoolManager()`
  Restarts DataSource pooling.

- ## Method Details

  - ### restartPoolManager

    public static void restartPoolManager() throws Exception
    Restarts DataSource pooling. This operation creates a new pool environment, effectively clearing all instances of all DataSources from the pool. This is an inherently dangerous method and should not be called in a production environment - instead, use `hotSwapPool()`
    Throws:
      `Exception`

  - ### hotSwapPool

    public static com.isomorphic.pool.PoolManager hotSwapPool()
    Replaces the global DataSource pool with a new one. Existing queues that have already captured a reference to the old pool continue to borrow from and return to it until they complete; new queues will use the replacement pool. When the last RCS scope referencing the old pool ends, the old pool is closed automatically.

    This is the safe alternative to `restartPoolManager()` for concurrent environments. Unlike restartPoolManager(), it does not close the old pool immediately, so in-flight requests are not disrupted.

    Returns:
      the old PoolManager (for diagnostics/testing; callers should not close it or otherwise attempt to make any use of it)

  - ### clearPooledInstances

    public static void clearPooledInstances(String dsName) throws Exception
    Clears all instances of the named DataSource from the pool
    Parameters:
      `dsName` - The name of the DataSource for which we should clear instances
    Throws:
      `Exception`

  - ### getDataSource

    public static DataSource getDataSource(String name) throws Exception
    Returns a DataSource object from the pool, creating a new instance if necessary. Note that you must be careful to return the DataSource object to the pool using the `free(com.isomorphic.datasource.DataSource)` method, or you will leak objects.
    Parameters:
      `name` - The name of the DataSource to return an instance of
    Throws:
      `Exception`

  - ### get

    public static DataSource get(String name) throws Exception
    Returns a DataSource object from the pool, creating a new instance if necessary. This method is identical to `getDataSource(java.lang.String)`.
    Parameters:
      `name` - The name of the DataSource to return an instance of
    Throws:
      `Exception`

  - ### freeDataSource

    public static void freeDataSource(DataSource ds)
    Frees the parameter DataSource object by returning it to the pool
    Parameters:
      `ds` - The DataSource instance to free (return to the pool)

  - ### free

    public static void free(DataSource ds)
    Frees the parameter DataSource object by returning it to the pool. This method is identical to `freeDataSource(com.isomorphic.datasource.DataSource)`.
    Parameters:
      `ds` - The DataSource instance to free (return to the pool)

  - ### getDefinedDataSourceIdentifiers

    public static Set<String> getDefinedDataSourceIdentifiers()
    Returns a Set containing the identifiers of each datasource known to the DataSourceManager.
    Returns:
      a Set containing the identifiers of each datasource known to the DataSourceManager