org.jboss.dna.graph.connector
Class RepositoryConnectionPool

java.lang.Object
  extended by org.jboss.dna.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.


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 .
 
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
 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.
 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(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 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.
 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.
 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.
 void setCorePoolSize(int corePoolSize)
          Sets the core number of connections.
 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 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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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

getRepositorySource

public final RepositorySource getRepositorySource()
Get the RepositorySource that's used by this pool.

Returns:
the repository source; never null

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

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)

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

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


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