ConnectionPool (org.attribyte)

java.lang.Object
- org.attribyte.sql.pool.ConnectionPool

All Implemented Interfaces:: ConnectionSupplier

public class ConnectionPool
extends java.lang.Object
implements ConnectionSupplier

Provides logical database connections to an application from a pool of physical connections that are maintained by the pool.

Connection pools are composed of segments that are used, activated and deactivated in sequence in response to connection demand. When active, a segment provides logical connections from a fixed-size pool of physical connections.

Connection pools may be created using XML or property-based configuration, as well as programmatically using an Initializer.

Configuration Parameters

name: The pool name. Required.
minActiveSegments: The minimum number of active segments. Default 1.
saturatedAcquireTimeout: The maximum amount of time to block waiting for an available connection. Default 0ms.
idleCheckInterval: The time between idle segment checks. Default 60s.
segments: The number of segments. Default 1.
activeSegments: The number of segments active on start. Default 1.
connection.user: The database user.
connection.password: The database password.
connection.url: The database connection string.
connection.testSQL: SQL used for connection tests.
connection.debug: Is connection debug mode turned on?
connection.testInterval: The interval between connection tests. Default 60s.
connection.maxWait: The maximum amount of time to wait for a database connection before giving up. Default 0s.
segment.size: The number of connections in each segment. Required.
segment.closeConcurrency: The number of background threads processing connection close. If 0, close blocks in the application thread. Default 0.
segment.reconnectConcurrency: The maximum number of concurrent database reconnects. Default 1.
segment.testOnLogicalOpen: Should connections be tested when they are acquired? Default false.
segment.testOnLogicalClose: Should connections be tested when they are released? Default false.
segment.acquireTimeout: The maximum amount of time to wait for a segment connection to become available. Default 0ms.
segment.activeTimeout: The maximum amount of time a logical connection may be open before it is forcibly closed. Default 5m.
segment.connectionLifetime: The maximum amount of time a physical connection may be open. Default 1h.
segment.maxReconnectWait: The maximum amount of time to wait between physical connection attempts on failure. Default 30s.

Sample Properties Configuration File

 driver.mysql.class=com.mysql.jdbc.Driver

 logger.class=org.attribyte.api.ConsoleLogger

 property.std.useUnicode=true
 property.std.characterEncoding=utf8

 connection.local.user=apprw
 connection.local.password=secret
 connection.local.connectionString=jdbc:mysql://127.0.0.1/attribyte
 connection.local.testSQL=SELECT 1 FROM test
 connection.local.testInterval=30s
 connection.local.createTimeout=60s
 connection.local.debug=true
 connection.local.properties=std

 connection.remote.user=apprw
 connection.remote.password=secret
 connection.remote.connectionString=jdbc:mysql://127.0.0.1/attribyte
 connection.remote.testSQL=SELECT 1 FROM test
 connection.remote.testInterval=30s
 connection.remote.createTimeout=60s
 connection.remote.debug=true
 connection.remote.properties=std

 pool.localPool.minActiveSegments=1
 pool.localPool.idleCheckInterval=30s
 pool.localPool.saturatedAcquireTimeout=1s

 pool.localPool.segment0.size=5
 pool.localPool.segment0.closeConcurrency=2
 pool.localPool.segment0.testOnLogicalOpen=true
 pool.localPool.segment0.testOnLogicalClose=true
 pool.localPool.segment0.connectionName=local
 pool.localPool.segment0.acquireTimeout=10ms
 pool.localPool.segment0.activeTimeout=60s
 pool.localPool.segment0.connectionLifetime=15m
 pool.localPool.segment0.idleTimeBeforeShutdown=30s
 pool.localPool.segment0.minActiveTime=30s
 pool.localPool.segment0.reconnectConcurrency=2
 pool.localPool.segment0.reconnectMaxWaitTime=1m
 pool.localPool.segment0.activeTimeoutMonitorFrequency=30s

 pool.localPool.segment1.clone=segment0
 pool.localPool.segment1.acquireTimeout=10ms
 pool.localPool.segment1.size=10

 pool.localPool.segment2.clone=segment0
 pool.localPool.segment2.acquireTimeout=50ms

 pool.remotePool.minActiveSegments=1
 pool.remotePool.idleCheckInterval=30s
 pool.remotePool.saturatedAcquireTimeout=1s

 pool.remotePool.segment0.size=5
 pool.remotePool.segment0.closeConcurrency=2
 pool.remotePool.segment0.testOnLogicalOpen=true
 pool.remotePool.segment0.testOnLogicalClose=true
 pool.remotePool.segment0.connectionName=local
 pool.remotePool.segment0.acquireTimeout=10ms
 pool.remotePool.segment0.activeTimeout=60s
 pool.remotePool.segment0.connectionLifetime=15m
 pool.remotePool.segment0.idleTimeBeforeShutdown=30s
 pool.remotePool.segment0.minActiveTime=30s
 pool.remotePool.segment0.reconnectConcurrency=2
 pool.remotePool.segment0.reconnectMaxWaitTime=1m
 pool.remotePool.segment0.activeTimeoutMonitorFrequency=30s

 pool.remotePool.segment1.clone=segment0
 pool.remotePool.segment1.acquireTimeout=10ms
 pool.remotePool.segment1.size=10

Author:: Matt Hamer - Attribyte, LLC

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ConnectionPool.Initializer` Initializes and creates connection pools.
`static class`	`ConnectionPool.Stats` Pool statistics.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`closeUnmanagedConnection(java.sql.Connection conn)` Closes an unumanged connection.
`int`	`getActiveConnections()` Gets the number of connections that are currently active.
`int`	`getActiveSegments()` Gets the current number of active segments.
`<any>`	`getAKA()` Gets an unmodifiable set of alias names for this pool.
`int`	`getAvailableConnections()` Gets the number of connections that are currently available.
`java.sql.Connection`	`getConnection()` Gets a connection.
`<any>`	`getFutureConnection(ListeningExecutorService executor)` Gets a connection future.
`MetricSet`	`getMetrics()` Gets the metrics for this pool.
`int`	`getMinActiveSegments()` Gets the minimum number of active segments.
`java.lang.String`	`getName()` Gets the name of the pool.
`ConnectionPool.Stats`	`getStats()` Gets a snapshot of statistics for this pool.
`int`	`getTotalSegments()` Gets the total number of segments (active + reserve).
`java.sql.Connection`	`getUnmanagedConnection()` Gets a new connection that is not managed by the pool.
`boolean`	`isIdle()` Is the pool currently idle?
`static ConnectionPool.Initializer`	`newInitializer()` Creates an empty initializer.
`MetricRegistry`	`registerMetrics(MetricRegistry registry)` Registers all metrics for this cache with the prefix 'org.attribyte.sql.pool.ConnectionPool.[pool name]'.
`void`	`shutdown()` Shutdown the pool.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - newInitializer
```
public static ConnectionPool.Initializer newInitializer()
```
    Creates an empty initializer.
    
    Returns:
    
    The initializer.
  - getUnmanagedConnection
```
public final java.sql.Connection getUnmanagedConnection()
                                                 throws java.sql.SQLException
```
    Gets a new connection that is not managed by the pool.
    The connection is created directly by the driver/datasource as configured for the first segment. Caller must call closeUnmanagedConnection for this connection when complete.
    
    Returns:
    
    The unmanaged connection.
    
    Throws:
    
    java.sql.SQLException - If no connection is available.
  - closeUnmanagedConnection
```
public final void closeUnmanagedConnection(java.sql.Connection conn)
                                    throws java.sql.SQLException
```
    Closes an unumanged connection.
    
    Parameters:
    
    conn - The conneciton.
    
    Throws:
    
    java.sql.SQLException - If close fails.
  - getConnection
```
public final java.sql.Connection getConnection()
                                        throws java.sql.SQLException
```
    Gets a connection.
    
    Specified by:
    
    getConnection in interface ConnectionSupplier
    
    Returns:
    
    The connection
    
    Throws:
    
    java.sql.SQLException - If no connection is available.
  - getFutureConnection
```
public final <any> getFutureConnection(ListeningExecutorService executor)
```
    Gets a connection future. See Listenable Future - Explained
    
    Parameters:
    
    executor - The executor service used to complete the future.
    
    Returns:
    
    The (listenable) connection future.
  - shutdown
```
public final void shutdown()
```
    Shutdown the pool.
  - getName
```
public java.lang.String getName()
```
    Gets the name of the pool.
    
    Returns:
    
    The pool name.
  - getAKA
```
public <any> getAKA()
```
    Gets an unmodifiable set of alias names for this pool.
    
    Returns:
    
    The set of names.
  - getActiveSegments
```
public int getActiveSegments()
```
    Gets the current number of active segments.
    
    Returns:
    
    The number of active segments.
  - getTotalSegments
```
public int getTotalSegments()
```
    Gets the total number of segments (active + reserve).
    
    Returns:
    
    The total number of segments.
  - getMinActiveSegments
```
public int getMinActiveSegments()
```
    Gets the minimum number of active segments.
    
    Returns:
    
    The minimum number of active segments.
  - getActiveConnections
```
public int getActiveConnections()
```
    Gets the number of connections that are currently active.
    
    Returns:
    
    The number of active connections.
  - getAvailableConnections
```
public int getAvailableConnections()
```
    Gets the number of connections that are currently available.
    
    Returns:
    
    The number of available.
  - isIdle
```
public boolean isIdle()
```
    Is the pool currently idle?
    
    Returns:
    
    Is the pool idle.
  - getStats
```
public ConnectionPool.Stats getStats()
```
    Gets a snapshot of statistics for this pool.
    
    Returns:
    
    The statistics.
  - getMetrics
```
public MetricSet getMetrics()
```
    Gets the metrics for this pool.
    
    Returns:
    
    The metrics.
  - registerMetrics
```
public MetricRegistry registerMetrics(MetricRegistry registry)
```
    Registers all metrics for this cache with the prefix 'org.attribyte.sql.pool.ConnectionPool.[pool name]'.
    
    Parameters:
    
    registry - The registry to which metrics are added.
    
    Returns:
    
    The input registry.

Class ConnectionPool

Configuration Parameters

Sample Properties Configuration File

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

newInitializer

getUnmanagedConnection

closeUnmanagedConnection

getConnection

getFutureConnection

shutdown

getName

getAKA

getActiveSegments

getTotalSegments

getMinActiveSegments

getActiveConnections

getAvailableConnections

isIdle

getStats

getMetrics

registerMetrics