org.apache.activemq.jms.pool

Class PooledConnectionFactory

java.lang.Object

org.apache.activemq.jms.pool.PooledConnectionFactory

All Implemented Interfaces:

javax.jms.ConnectionFactory

Direct Known Subclasses:

XaPooledConnectionFactory

public class PooledConnectionFactory
extends Object
implements javax.jms.ConnectionFactory

A JMS provider which pools Connection, Session and MessageProducer instances so it can be used with tools like Camel and Spring's JmsTemplate and MessagListenerContainer. Connections, sessions and producers are returned to a pool after use so that they can be reused later without having to undergo the cost of creating them again. b>NOTE: while this implementation does allow the creation of a collection of active consumers, it does not 'pool' consumers. Pooling makes sense for connections, sessions and producers, which are expensive to create and can remain idle a minimal cost. Consumers, on the other hand, are usually just created at startup and left active, handling incoming messages as they come. When a consumer is complete, it is best to close it rather than return it to a pool for later reuse: this is because, even if a consumer is idle, ActiveMQ will keep delivering messages to the consumer's prefetch buffer, where they'll get held until the consumer is active again. If you are creating a collection of consumers (for example, for multi-threaded message consumption), you might want to consider using a lower prefetch value for each consumer (e.g. 10 or 20), to ensure that all messages don't end up going to just one of the consumers. See this FAQ entry for more detail: http://activemq.apache.org/i-do-not-receive-messages-in-my-second-consumer.html Optionally, one may configure the pool to examine and possibly evict objects as they sit idle in the pool. This is performed by an "idle object eviction" thread, which runs asynchronously. Caution should be used when configuring this optional feature. Eviction runs contend with client threads for access to objects in the pool, so if they run too frequently performance issues may result. The idle object eviction thread may be configured using the setTimeBetweenExpirationCheckMillis(long) method. By default the value is -1 which means no eviction thread will be run. Set to a non-negative value to configure the idle eviction thread to run.

Field Summary

Fields

Modifier and Type	Field and Description
protected AtomicBoolean	stopped

Constructor Summary

Constructors

Constructor and Description
PooledConnectionFactory()

Method Summary

Methods

Modifier and Type	Method and Description
void	clear() Clears all connections from the pool.
javax.jms.Connection	createConnection()
protected javax.jms.Connection	createConnection(ConnectionKey key)
javax.jms.Connection	createConnection(String userName, String password)
protected ConnectionPool	createConnectionPool(javax.jms.Connection connection) Delegate that creates each instance of an ConnectionPool object.
javax.jms.ConnectionFactory	getConnectionFactory()
protected org.apache.commons.pool.impl.GenericKeyedObjectPool<ConnectionKey,ConnectionPool>	getConnectionsPool() Gets the Pool of ConnectionPool instances which are keyed by different ConnectionKeys.
long	getExpiryTimeout()
int	getIdleTimeout() Gets the Idle timeout value applied to new Connection's that are created by this pool.
int	getMaxConnections() Returns the maximum number to pooled Connections that this factory will allow before it begins to return connections from the pool on calls to (createConnection.
int	getMaximumActiveSessionPerConnection() Returns the currently configured maximum number of sessions a pooled Connection will create before it either blocks or throws an exception when a new session is requested, depending on configuration.
int	getNumConnections()
long	getTimeBetweenExpirationCheckMillis()
void	initConnectionsPool()
boolean	isBlockIfSessionPoolIsFull() Returns whether a pooled Connection will enter a blocked state or will throw an Exception once the maximum number of sessions has been borrowed from the the Session Pool.
boolean	isCreateConnectionOnStartup()
boolean	isUseAnonymousProducers() Should Sessions use one anonymous producer for all producer requests or should a new MessageProducer be created for each request to create a producer object, default is true.
protected javax.jms.Connection	newPooledConnection(ConnectionPool connection)
void	setBlockIfSessionPoolIsFull(boolean block) Controls the behavior of the internal session pool.
void	setConnectionFactory(javax.jms.ConnectionFactory toUse) Sets the ConnectionFactory used to create new pooled Connections.
void	setCreateConnectionOnStartup(boolean createConnectionOnStartup) Whether to create a connection on starting this PooledConnectionFactory.
void	setExpiryTimeout(long expiryTimeout) allow connections to expire, irrespective of load or idle time.
void	setIdleTimeout(int idleTimeout) Sets the idle timeout value for Connection's that are created by this pool in Milliseconds, defaults to 30 seconds.
void	setMaxConnections(int maxConnections) Sets the maximum number of pooled Connections (defaults to one).
void	setMaximumActiveSessionPerConnection(int maximumActiveSessionPerConnection) Sets the maximum number of active sessions per connection
void	setTimeBetweenExpirationCheckMillis(long timeBetweenExpirationCheckMillis) Sets the number of milliseconds to sleep between runs of the idle Connection eviction thread.
void	setUseAnonymousProducers(boolean value) Sets whether a PooledSession uses only one anonymous MessageProducer instance or creates a new MessageProducer for each call the create a MessageProducer.
void	start()
void	stop()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

stopped

protected final AtomicBoolean stopped

Constructor Detail

PooledConnectionFactory

public PooledConnectionFactory()

Method Detail

initConnectionsPool

public void initConnectionsPool()

getConnectionFactory

public javax.jms.ConnectionFactory getConnectionFactory()

Returns:

the currently configured ConnectionFactory used to create the pooled Connections.

setConnectionFactory

public void setConnectionFactory(javax.jms.ConnectionFactory toUse)

Sets the ConnectionFactory used to create new pooled Connections.

Updates to this value do not affect Connections that were previously created and placed into the pool. In order to allocate new Connections based off this new ConnectionFactory it is first necessary to clear the pooled Connections.

Parameters:

toUse - The factory to use to create pooled Connections.

createConnection

public javax.jms.Connection createConnection()
                                      throws javax.jms.JMSException

Specified by:

createConnection in interface javax.jms.ConnectionFactory

Throws:

javax.jms.JMSException

createConnection

public javax.jms.Connection createConnection(String userName,
                                    String password)
                                      throws javax.jms.JMSException

Specified by:

createConnection in interface javax.jms.ConnectionFactory

Throws:

javax.jms.JMSException

newPooledConnection

protected javax.jms.Connection newPooledConnection(ConnectionPool connection)

createConnection

protected javax.jms.Connection createConnection(ConnectionKey key)
                                         throws javax.jms.JMSException

Throws:

javax.jms.JMSException

start

public void start()

stop

public void stop()

clear

public void clear()

Clears all connections from the pool. Each connection that is currently in the pool is closed and removed from the pool. A new connection will be created on the next call to createConnection. Care should be taken when using this method as Connections that are in use be client's will be closed.

getMaximumActiveSessionPerConnection

public int getMaximumActiveSessionPerConnection()

Returns the currently configured maximum number of sessions a pooled Connection will create before it either blocks or throws an exception when a new session is requested, depending on configuration.

Returns:

the number of session instances that can be taken from a pooled connection.

setMaximumActiveSessionPerConnection

public void setMaximumActiveSessionPerConnection(int maximumActiveSessionPerConnection)

Sets the maximum number of active sessions per connection

Parameters:

maximumActiveSessionPerConnection - The maximum number of active session per connection in the pool.

setBlockIfSessionPoolIsFull

public void setBlockIfSessionPoolIsFull(boolean block)

Controls the behavior of the internal session pool. By default the call to Connection.getSession() will block if the session pool is full. If the argument false is given, it will change the default behavior and instead the call to getSession() will throw a JMSException. The size of the session pool is controlled by the @see #maximumActive property.

Parameters:

block - - if true, the call to getSession() blocks if the pool is full until a session object is available. defaults to true.

isBlockIfSessionPoolIsFull

public boolean isBlockIfSessionPoolIsFull()

Returns whether a pooled Connection will enter a blocked state or will throw an Exception once the maximum number of sessions has been borrowed from the the Session Pool.

Returns:

true if the pooled Connection createSession method will block when the limit is hit.

See Also:

setBlockIfSessionPoolIsFull

getMaxConnections

public int getMaxConnections()

Returns the maximum number to pooled Connections that this factory will allow before it begins to return connections from the pool on calls to (createConnection.

Returns:

the maxConnections that will be created for this pool.

setMaxConnections

public void setMaxConnections(int maxConnections)

Sets the maximum number of pooled Connections (defaults to one). Each call to createConnection will result in a new Connection being create up to the max connections value.

Parameters:

maxConnections - the maxConnections to set

getIdleTimeout

public int getIdleTimeout()

Gets the Idle timeout value applied to new Connection's that are created by this pool.

The idle timeout is used determine if a Connection instance has sat to long in the pool unused and if so is closed and removed from the pool. The default value is 30 seconds.

Returns:

idle timeout value (milliseconds)

setIdleTimeout

public void setIdleTimeout(int idleTimeout)

Sets the idle timeout value for Connection's that are created by this pool in Milliseconds, defaults to 30 seconds.

For a Connection that is in the pool but has no current users the idle timeout determines how long the Connection can live before it is eligible for removal from the pool. Normally the connections are tested when an attempt to check one out occurs so a Connection instance can sit in the pool much longer than its idle timeout if connections are used infrequently.

Parameters:

idleTimeout - The maximum time a pooled Connection can sit unused before it is eligible for removal.

setExpiryTimeout

public void setExpiryTimeout(long expiryTimeout)

allow connections to expire, irrespective of load or idle time. This is useful with failover to force a reconnect from the pool, to reestablish load balancing or use of the master post recovery

Parameters:

expiryTimeout - non zero in milliseconds

getExpiryTimeout

public long getExpiryTimeout()

Returns:

the configured expiration timeout for connections in the pool.

isCreateConnectionOnStartup

public boolean isCreateConnectionOnStartup()

Returns:

true if a Connection is created immediately on a call to start.

setCreateConnectionOnStartup

public void setCreateConnectionOnStartup(boolean createConnectionOnStartup)

Whether to create a connection on starting this PooledConnectionFactory.

This can be used to warm-up the pool on startup. Notice that any kind of exception happens during startup is logged at WARN level and ignored.

Parameters:

createConnectionOnStartup - true to create a connection on startup

isUseAnonymousProducers

public boolean isUseAnonymousProducers()

Should Sessions use one anonymous producer for all producer requests or should a new MessageProducer be created for each request to create a producer object, default is true. When enabled the session only needs to allocate one MessageProducer for all requests and the MessageProducer#send(destination, message) method can be used. Normally this is the right thing to do however it does result in the Broker not showing the producers per destination.

Returns:

true if a PooledSession will use only a single anonymous message producer instance.

setUseAnonymousProducers

public void setUseAnonymousProducers(boolean value)

Sets whether a PooledSession uses only one anonymous MessageProducer instance or creates a new MessageProducer for each call the create a MessageProducer.

Parameters:

value - Boolean value that configures whether anonymous producers are used.

getConnectionsPool

protected org.apache.commons.pool.impl.GenericKeyedObjectPool<ConnectionKey,ConnectionPool> getConnectionsPool()

Gets the Pool of ConnectionPool instances which are keyed by different ConnectionKeys.

Returns:

this factories pool of ConnectionPool instances.

setTimeBetweenExpirationCheckMillis

public void setTimeBetweenExpirationCheckMillis(long timeBetweenExpirationCheckMillis)

Sets the number of milliseconds to sleep between runs of the idle Connection eviction thread. When non-positive, no idle object eviction thread will be run, and Connections will only be checked on borrow to determine if they have sat idle for too long or have failed for some other reason.

By default this value is set to -1 and no expiration thread ever runs.

Parameters:

timeBetweenExpirationCheckMillis - The time to wait between runs of the idle Connection eviction thread.

getTimeBetweenExpirationCheckMillis

public long getTimeBetweenExpirationCheckMillis()

Returns:

the number of milliseconds to sleep between runs of the idle connection eviction thread.

getNumConnections

public int getNumConnections()

Returns:

the number of Connections currently in the Pool

createConnectionPool

protected ConnectionPool createConnectionPool(javax.jms.Connection connection)

Delegate that creates each instance of an ConnectionPool object. Subclasses can override this method to customize the type of connection pool returned.

Parameters:

connection -

Returns:

instance of a new ConnectionPool.