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