Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.modeshape.graph.connector
Class RepositoryConnectionPool

    java.lang.Object
      org.modeshape.graph.connector.RepositoryConnectionPool

    @ThreadSafe
    public class RepositoryConnectionPool

extends Object

A reusable implementation of a managed pool of connections that is optimized for safe concurrent operations.

Nested Class Summary
`protected class` | `RepositoryConnectionPool.ConnectionWrapper`

Field Summary
`static int` | `DEFAULT_CORE_POOL_SIZE` The core pool size for default-constructed pools is 1 .
`static long` | `DEFAULT_KEEP_ALIVE_TIME_IN_SECONDS` The keep-alive time for connections in default-constructed pools is * * * * 30L seconds.
`static int` | `DEFAULT_MAXIMUM_POOL_SIZE` The maximum pool size for default-constructed pools is 10 .
`static long` | `DEFAULT_TIME_TO_WAIT` The default time to wait for ping when called from a client.
`static TimeUnit` | `DEFAULT_TIME_UNIT` The default TimeUnit to wait for ping when called from a client.

Constructor Summary
`RepositoryConnectionPool(RepositorySource source)` Create the pool to use the supplied connection factory, which is typically a `RepositorySource`.
`RepositoryConnectionPool(RepositorySource source, int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit)` Create the pool to use the supplied connection factory, which is typically a `RepositorySource`.

Method Summary
`protected boolean` | `addConnectionIfUnderCorePoolSize()`
`protected int` | `addConnectionsIfUnderCorePoolSize()`
`boolean` | `awaitTermination(long timeout, TimeUnit unit)` Method that can be called after `shutdown()` or `shutdownNow()` to wait until all connections in use at the time those methods were called have been closed normally.
`protected void` | `closeConnection(RepositoryConnectionPool.ConnectionWrapper wrapper)` Close a connection that is in the pool but no longer in the `available connections`.
`protected int` | `drainUnusedConnections(int count)`
`protected void` | `finalize()` Invokes `shutdown` when this pool is no longer referenced.
`RepositoryConnection` | `getConnection()` Get a connection from the pool.
`int` | `getCorePoolSize()` Returns the core number of connections.
`int` | `getInUseCount()` Returns the approximate number of connections that are currently checked out from the pool.
`long` | `getKeepAliveTime()` Returns the connection keep-alive time, which is the amount of time which connections in excess of the core pool size may remain idle before being closed.
`long` | `getKeepAliveTime(TimeUnit unit)` Returns the connection keep-alive time, which is the amount of time which connections in excess of the core pool size may remain idle before being closed.
`int` | `getMaxFailedAttemptsBeforeError()`
`int` | `getMaximumPoolSize()`
`long` | `getPingTimeout()` The ping timeout, in seconds.
`long` | `getPingTimeoutInNanos()`
`int` | `getPoolSize()` Returns the current number of connections in the pool, including those that are checked out (in use) and those that are not being used.
`RepositorySource` | `getRepositorySource()` Get the `RepositorySource` that's used by this pool.
`protected String` | `getSourceName()` Get the name of this pool, which delegates to the connection factory.
`long` | `getTotalConnectionsCreated()` Get the total number of connections that have been created by this pool.
`long` | `getTotalConnectionsUsed()` Get the total number of times connections have been `getConnection()` used.
`boolean` | `getValidateConnectionBeforeUse()`
`boolean` | `isRunning()` Return whether this connection pool is running and is able to `provide connections`.
`boolean` | `isShutdown()` Return whether this connection pool is in the process of shutting down or has already been shut down.
`boolean` | `isTerminated()` Return true if this pool has completed its termination and no longer has any open connections.
`boolean` | `isTerminating()` Returns true if this pool is in the process of terminating after `shutdown()` or `shutdownNow()` has been called but has not completely terminated.
`protected RepositoryConnectionPool.ConnectionWrapper` | `newWrappedConnection()` Obtain a new connection wrapped in a `RepositoryConnectionPool.ConnectionWrapper`.
`boolean` | `ping()` Used to get and test a connection in the pool with default wait and time unit values
`boolean` | `ping(long time, TimeUnit unit)` Used to get and test a connection in the pool
`int` | `prestartAllCoreConnections()` Starts all core connections, causing them to idly wait for use.
`boolean` | `prestartCoreConnection()` Starts a core connection, causing it to idly wait for use.
`protected void` | `returnConnection(RepositoryConnectionPool.ConnectionWrapper wrapper)` This method is automatically called by the `RepositoryConnectionPool.ConnectionWrapper` when it is `closed`.
`void` | `setCorePoolSize(int corePoolSize)` Sets the core number of connections.
`void` | `setKeepAliveTime(long time)` Sets the time limit for which connections may remain idle before being closed.
`void` | `setKeepAliveTime(long time, TimeUnit unit)` Sets the time limit for which connections may remain idle before being closed.
`void` | `setMaxFailedAttemptsBeforeError(int maxFailedAttemptsBeforeError)`
`void` | `setMaximumPoolSize(int maximumPoolSize)` Sets the maximum allowed number of connections.
`void` | `setPingTimeout(long pingTimeoutInSeconds)` Sets the ping timeout, in seconds.
`void` | `setPingTimeout(long pingTimeout, TimeUnit unit)`
`void` | `setValidateConnectionBeforeUse(boolean validateConnectionBeforeUse)`
`void` | `shutdown()` Initiates an orderly shutdown of the pool in which connections that are currently in use are allowed to be used and closed as normal, but no new connections will be created.
`void` | `shutdownNow()` Attempts to close all connections in the pool, including those connections currently in use, and prevent the use of other connections.
`protected void` | `terminated()` Method invoked when the pool has terminated.
`protected RepositoryConnectionPool.ConnectionWrapper` | `validateConnection(RepositoryConnectionPool.ConnectionWrapper connection)` Validate the supplied connection, returning the connection if valid or null if the connection is not valid.

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

Field Detail

### DEFAULT_TIME_TO_WAIT

    public static final long DEFAULT_TIME_TO_WAIT

  The default time to wait for ping when called from a client.

  See Also:
    Constant Field Values

### DEFAULT_TIME_UNIT

    public static final TimeUnit DEFAULT_TIME_UNIT

  The default TimeUnit to wait for ping when called from a client.

### DEFAULT_CORE_POOL_SIZE

    public static final int DEFAULT_CORE_POOL_SIZE

  The core pool size for default-constructed pools is 1 .

  See Also:
    Constant Field Values

### DEFAULT_MAXIMUM_POOL_SIZE

    public static final int DEFAULT_MAXIMUM_POOL_SIZE

  The maximum pool size for default-constructed pools is 10 .

  See Also:
    Constant Field Values

### DEFAULT_KEEP_ALIVE_TIME_IN_SECONDS

    public static final long DEFAULT_KEEP_ALIVE_TIME_IN_SECONDS

  The keep-alive time for connections in default-constructed pools is * * * * 30L seconds.

  See Also:
    Constant Field Values

Constructor Detail

### RepositoryConnectionPool

    public RepositoryConnectionPool(RepositorySource source)

  Create the pool to use the supplied connection factory, which is typically a `RepositorySource`. This constructor uses the `default core pool size`, `default maximum pool size`, and `default keep-alive time (in seconds)`.

  Parameters:
    `source` - the source for connections
  Throws:
    `IllegalArgumentException` - if the connection factory is null or any of the supplied arguments are invalid

### RepositoryConnectionPool

    public RepositoryConnectionPool(RepositorySource source,
                                    int corePoolSize,
                                    int maximumPoolSize,
                                    long keepAliveTime,
                                    TimeUnit unit)

  Create the pool to use the supplied connection factory, which is typically a `RepositorySource`.

  Parameters:
    `source` - the source for connections
    `corePoolSize` - the number of connections to keep in the pool, even if they are idle.
    `maximumPoolSize` - the maximum number of connections to allow in the pool.
    `keepAliveTime` - when the number of connection is greater than the core, this is the maximum time that excess idle connections will be kept before terminating.
    `unit` - the time unit for the keepAliveTime argument.
  Throws:
    `IllegalArgumentException` - if the connection factory is null or any of the supplied arguments are invalid

Method Detail

### ping

    public boolean ping(long time,
                        TimeUnit unit)
                 throws InterruptedException

  Used to get and test a connection in the pool

  Parameters:
    `time` -
    `unit` -
  Returns:
    boolean
  Throws:
    `InterruptedException`

### ping

    public boolean ping()
                 throws InterruptedException

  Used to get and test a connection in the pool with default wait and time unit values

  Returns:
    boolean
  Throws:
    `InterruptedException`

### getRepositorySource

    public final RepositorySource getRepositorySource()

  Get the `RepositorySource` that's used by this pool.

  Returns:
    the repository source; never null

### getSourceName

    protected String getSourceName()

  Get the name of this pool, which delegates to the connection factory.

  Returns:
    the name of the source

### getValidateConnectionBeforeUse

    public boolean getValidateConnectionBeforeUse()

  Returns:
    validateConnectionBeforeUse

### setValidateConnectionBeforeUse

    public void setValidateConnectionBeforeUse(boolean validateConnectionBeforeUse)

  Parameters:
    `validateConnectionBeforeUse` - Sets validateConnectionBeforeUse to the specified value.

### getPingTimeoutInNanos

    public long getPingTimeoutInNanos()

  Returns:
    pingTimeout

### setPingTimeout

    public void setPingTimeout(long pingTimeout,
                               TimeUnit unit)

  Parameters:
    `pingTimeout` - the time to wait for a ping to complete
    `unit` - the time unit of the time argument

### getPingTimeout

    public long getPingTimeout()

  The ping timeout, in seconds.

  Returns:
    pingTimeout

### setPingTimeout

    public void setPingTimeout(long pingTimeoutInSeconds)

  Sets the ping timeout, in seconds.

  Parameters:
    `pingTimeoutInSeconds` - the time to wait for a ping to complete

### getMaxFailedAttemptsBeforeError

    public int getMaxFailedAttemptsBeforeError()

  Returns:
    maxFailedAttemptsBeforeError

### setMaxFailedAttemptsBeforeError

    public void setMaxFailedAttemptsBeforeError(int maxFailedAttemptsBeforeError)

  Parameters:
    `maxFailedAttemptsBeforeError` - Sets maxFailedAttemptsBeforeError to the specified value.

### setKeepAliveTime

    public void setKeepAliveTime(long time,
                                 TimeUnit unit)

  Sets the time limit for which connections may remain idle before being closed. If there are more than the core number of connections currently in the pool, after waiting this amount of time without being used, excess threads will be terminated. This overrides any value set in the constructor.

  Parameters:
    `time` - the time to wait. A time value of zero will cause excess connections to terminate immediately after being returned.
    `unit` - the time unit of the time argument
  Throws:
    `IllegalArgumentException` - if time less than zero
  See Also:
    `getKeepAliveTime(java.util.concurrent.TimeUnit)`

### getKeepAliveTime

    public long getKeepAliveTime(TimeUnit unit)

  Returns the connection keep-alive time, which is the amount of time which connections in excess of the core pool size may remain idle before being closed.

  Parameters:
    `unit` - the desired time unit of the result
  Returns:
    the time limit
  See Also:
    `setKeepAliveTime(long, java.util.concurrent.TimeUnit)`

### getKeepAliveTime

    public long getKeepAliveTime()

  Returns the connection keep-alive time, which is the amount of time which connections in excess of the core pool size may remain idle before being closed.

  Returns:
    the time limit in seconds
  See Also:
    `setKeepAliveTime(long, java.util.concurrent.TimeUnit)`

### setKeepAliveTime

    public void setKeepAliveTime(long time)

  Sets the time limit for which connections may remain idle before being closed. If there are more than the core number of connections currently in the pool, after waiting this amount of time without being used, excess threads will be terminated. This overrides any value set in the constructor.

  Parameters:
    `time` - the time to wait, in seconds. A time value of zero will cause excess connections to terminate immediately after being returned.
  Throws:
    `IllegalArgumentException` - if time less than zero
  See Also:
    `getKeepAliveTime(java.util.concurrent.TimeUnit)`

### getMaximumPoolSize

    public int getMaximumPoolSize()

  Returns:
    maximumPoolSize

### setMaximumPoolSize

    public void setMaximumPoolSize(int maximumPoolSize)

  Sets the maximum allowed number of connections. This overrides any value set in the constructor. If the new value is smaller than the current value, excess existing but unused connections will be closed.

  Parameters:
    `maximumPoolSize` - the new maximum
  Throws:
    `IllegalArgumentException` - if maximumPoolSize less than zero or the `core pool size`
  See Also:
    `getMaximumPoolSize()`

### getCorePoolSize

    public int getCorePoolSize()

  Returns the core number of connections.

  Returns:
    the core number of connections
  See Also:
    `setCorePoolSize(int)`

### setCorePoolSize

    public void setCorePoolSize(int corePoolSize)
                         throws RepositorySourceException,
                                InterruptedException

  Sets the core number of connections. This overrides any value set in the constructor. If the new value is smaller than the current value, excess existing and unused connections will be closed. If larger, new connections will, if needed, be created.

  Parameters:
    `corePoolSize` - the new core size
  Throws:
    `RepositorySourceException` - if there was an error obtaining the new connection
    `InterruptedException` - if the thread was interrupted during the operation
    `IllegalArgumentException` - if `corePoolSize` less than zero
  See Also:
    `getCorePoolSize()`

### getPoolSize

    public int getPoolSize()

  Returns the current number of connections in the pool, including those that are checked out (in use) and those that are not being used.

  Returns:
    the number of connections

### getInUseCount

    public int getInUseCount()

  Returns the approximate number of connections that are currently checked out from the pool.

  Returns:
    the number of checked-out connections

### getTotalConnectionsCreated

    public long getTotalConnectionsCreated()

  Get the total number of connections that have been created by this pool.

  Returns:
    the total number of connections created by this pool

### getTotalConnectionsUsed

    public long getTotalConnectionsUsed()

  Get the total number of times connections have been `getConnection()` used.

  Returns:
    the total number

### prestartCoreConnection

    public boolean prestartCoreConnection()
                                   throws RepositorySourceException,
                                          InterruptedException

  Starts a core connection, causing it to idly wait for use. This overrides the default policy of starting core connections only when they are `needed`. This method will return `false` if all core connections have already been started.

  Returns:
    true if a connection was started
  Throws:
    `RepositorySourceException` - if there was an error obtaining the new connection
    `InterruptedException` - if the thread was interrupted during the operation

### prestartAllCoreConnections

    public int prestartAllCoreConnections()
                                   throws RepositorySourceException,
                                          InterruptedException

  Starts all core connections, causing them to idly wait for use. This overrides the default policy of starting core connections only when they are `needed`.

  Returns:
    the number of connections started.
  Throws:
    `RepositorySourceException` - if there was an error obtaining the new connection
    `InterruptedException` - if the thread was interrupted during the operation

### shutdown

    public void shutdown()

  Initiates an orderly shutdown of the pool in which connections that are currently in use are allowed to be used and closed as normal, but no new connections will be created. Invocation has no additional effect if already shut down.

  Once the pool has been shutdown, it may not be used to `get connections`.

  Throws:
    `SecurityException` - if a security manager exists and shutting down this pool may manipulate threads that the caller is not permitted to modify because it does not hold `RuntimePermission` `("modifyThread")`, or the security manager's `checkAccess` method denies access.
  See Also:
    `shutdownNow()`

### shutdownNow

    public void shutdownNow()

  Attempts to close all connections in the pool, including those connections currently in use, and prevent the use of other connections.

  Throws:
    `SecurityException` - if a security manager exists and shutting down this pool may manipulate threads that the caller is not permitted to modify because it does not hold `RuntimePermission` `("modifyThread")`, or the security manager's `checkAccess` method denies access.
  See Also:
    `shutdown()`

### isRunning

    public boolean isRunning()

  Return whether this connection pool is running and is able to `provide connections`. Note that this method is effectively `!isShutdown()`.

  Returns:
    true if this pool is running, or false otherwise
  See Also:
    `isShutdown()`, `isTerminated()`, `isTerminating()`

### isShutdown

    public boolean isShutdown()

  Return whether this connection pool is in the process of shutting down or has already been shut down. A result of `true` signals that the pool may no longer be used. Note that this method is effectively `!isRunning()`.

  Returns:
    true if this pool has been shut down, or false otherwise
  See Also:
    `isShutdown()`, `isTerminated()`, `isTerminating()`

### isTerminating

    public boolean isTerminating()

  Returns true if this pool is in the process of terminating after `shutdown()` or `shutdownNow()` has been called but has not completely terminated. This method may be useful for debugging. A return of `true` reported a sufficient period after shutdown may indicate that submitted tasks have ignored or suppressed interruption, causing this executor not to properly terminate.

  Returns:
    true if terminating but not yet terminated, or false otherwise
  See Also:
    `isTerminated()`

### isTerminated

    public boolean isTerminated()

  Return true if this pool has completed its termination and no longer has any open connections.

  Returns:
    true if terminated, or false otherwise
  See Also:
    `isTerminating()`

### awaitTermination

    public boolean awaitTermination(long timeout,
                                    TimeUnit unit)
                             throws InterruptedException

  Method that can be called after `shutdown()` or `shutdownNow()` to wait until all connections in use at the time those methods were called have been closed normally. This method accepts a maximum time duration, after which it will return even if all connections have not been closed.

  Parameters:
    `timeout` - the maximum time to wait for all connections to be closed and returned to the pool
    `unit` - the time unit for `timeout`
  Returns:
    true if the pool was terminated in the supplied time (or was already terminated), or false if the timeout occurred before all the connections were closed
  Throws:
    `InterruptedException` - if the thread was interrupted

### terminated

    protected void terminated()

  Method invoked when the pool has terminated. Default implementation does nothing. Note: To properly nest multiple overridings, subclasses should generally invoke `super.terminated` within this method.

### finalize

    protected void finalize()

  Invokes `shutdown` when this pool is no longer referenced.

  Overrides:
    `finalize` in class `Object`

### getConnection

    public RepositoryConnection getConnection()
                                       throws RepositorySourceException

  Get a connection from the pool. This method either returns an unused connection if one is available, creates a connection if there is still room in the pool, or blocks until a connection becomes available if the pool already contains the maximum number of connections and all connections are currently being used.

  Returns:
    a connection
  Throws:
    `RepositorySourceException` - if there is a problem obtaining a connection
    `IllegalStateException` - if the factory is not in a state to create or return connections

### returnConnection

    protected void returnConnection(RepositoryConnectionPool.ConnectionWrapper wrapper)

  This method is automatically called by the `RepositoryConnectionPool.ConnectionWrapper` when it is `closed`.

  Parameters:
    `wrapper` - the wrapper to the connection that is being returned to the pool

### validateConnection

    protected RepositoryConnectionPool.ConnectionWrapper validateConnection(RepositoryConnectionPool.ConnectionWrapper connection)
                                                                     throws InterruptedException

  Validate the supplied connection, returning the connection if valid or null if the connection is not valid.

  Parameters:
    `connection` - the connection to be validated; may not be null
  Returns:
    the validated connection, or null if the connection did not validate and was removed from the pool
  Throws:
    `InterruptedException` - if the thread is interrupted while validating the connection

### newWrappedConnection

    protected RepositoryConnectionPool.ConnectionWrapper newWrappedConnection()
                                                                       throws RepositorySourceException

  Obtain a new connection wrapped in a `RepositoryConnectionPool.ConnectionWrapper`. This method does not check whether creating the new connection would violate the `maximum pool size` nor does it add the new connection to the `available connections` (as the caller may want it immediately), but it does increment the `pool size`.

  Returns:
    the connection wrapper with a new connection
  Throws:
    `RepositorySourceException` - if there was an error obtaining the new connection

### closeConnection

    protected void closeConnection(RepositoryConnectionPool.ConnectionWrapper wrapper)

  Close a connection that is in the pool but no longer in the `available connections`. This method does decrement the `pool size`.

  Parameters:
    `wrapper` - the wrapper for the connection to be closed

### drainUnusedConnections

    protected int drainUnusedConnections(int count)

### addConnectionIfUnderCorePoolSize

    protected boolean addConnectionIfUnderCorePoolSize()
                                                throws RepositorySourceException

  Throws:
    `RepositorySourceException`

### addConnectionsIfUnderCorePoolSize

    protected int addConnectionsIfUnderCorePoolSize()
                                             throws RepositorySourceException

  Throws:
    `RepositorySourceException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2008-2011 JBoss, a division of Red Hat. All Rights Reserved.