org.apache.activemq.pool
Class PooledConnectionFactory

java.lang.Object
  org.apache.activemq.pool.PooledConnectionFactory

All Implemented Interfaces:

javax.jms.ConnectionFactory, org.apache.activemq.Service

Direct Known Subclasses:

AmqJNDIPooledConnectionFactory, XaPooledConnectionFactory

public class PooledConnectionFactory
extends Object
implements javax.jms.ConnectionFactory, org.apache.activemq.Service

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 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.

Constructor Summary

PooledConnectionFactory()
Creates new PooledConnectionFactory with a default ActiveMQConnectionFactory instance.

PooledConnectionFactory(org.apache.activemq.ActiveMQConnectionFactory connectionFactory)
Creates a new PooledConnectionFactory that will use the given ActiveMQConnectionFactory to create new ActiveMQConnection instances that will be pooled.

PooledConnectionFactory(String brokerURL)
Creates a new PooledConnectionFactory that will use the given broker URI to connect to ActiveMQ.

Method Summary

void	clear() Clears all connections from the pool.
javax.jms.Connection	createConnection()
protected org.apache.activemq.ActiveMQConnection	createConnection(ConnectionKey key)
javax.jms.Connection	createConnection(String userName, String password)
javax.jms.ConnectionFactory	getConnectionFactory()
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	getMaximumActive() Deprecated. use getMaximumActiveSessionPerConnection()
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()
org.apache.commons.pool.ObjectPoolFactory<?>	getPoolFactory() Deprecated.
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()
void	setBlockIfSessionPoolIsFull(boolean block) Controls the behavior of the internal session pool.
void	setConnectionFactory(javax.jms.ConnectionFactory connectionFactory) 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, defaults to 30 seconds.
void	setMaxConnections(int maxConnections) Sets the maximum number of pooled Connections (defaults to one).
void	setMaximumActive(int maximumActive) Deprecated. use setMaximumActiveSessionPerConnection(int)
void	setMaximumActiveSessionPerConnection(int maximumActiveSessionPerConnection) Sets the maximum number of active sessions per connection
void	setPoolFactory(org.apache.commons.pool.ObjectPoolFactory<?> factory) Deprecated.
long	setTimeBetweenExpirationCheckMillis()
void	setTimeBetweenExpirationCheckMillis(long timeBetweenExpirationCheckMillis) Sets the number of milliseconds to sleep between runs of the idle Connection eviction thread.
void	start()
void	stop()

Methods inherited from class java.lang.Object

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

Constructor Detail

PooledConnectionFactory

public PooledConnectionFactory()

Creates new PooledConnectionFactory with a default ActiveMQConnectionFactory instance.

The URI used to connect to ActiveMQ comes from the default value of ActiveMQConnectionFactory.

PooledConnectionFactory

public PooledConnectionFactory(String brokerURL)

Creates a new PooledConnectionFactory that will use the given broker URI to connect to ActiveMQ.

Parameters:

brokerURL - The URI to use to configure the internal ActiveMQConnectionFactory.

PooledConnectionFactory

public PooledConnectionFactory(org.apache.activemq.ActiveMQConnectionFactory connectionFactory)

Creates a new PooledConnectionFactory that will use the given ActiveMQConnectionFactory to create new ActiveMQConnection instances that will be pooled.

Parameters:

connectionFactory - The ActiveMQConnectionFactory to create new Connections for this pool.

Method Detail

getConnectionFactory

public javax.jms.ConnectionFactory getConnectionFactory()

Returns:

the currently configured ConnectionFactory used to create the pooled Connections.

setConnectionFactory

public void setConnectionFactory(javax.jms.ConnectionFactory connectionFactory)

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:

connectionFactory - 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

getPoolFactory

public org.apache.commons.pool.ObjectPoolFactory<?> getPoolFactory()

Deprecated.

createConnection

protected org.apache.activemq.ActiveMQConnection createConnection(ConnectionKey key)
                                                           throws javax.jms.JMSException

Throws:

javax.jms.JMSException

start

public void start()

Specified by:

start in interface org.apache.activemq.Service

stop

public void stop()

Specified by:

stop in interface org.apache.activemq.Service

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.

getMaximumActive

@Deprecated
public int getMaximumActive()

Deprecated. use getMaximumActiveSessionPerConnection()

setMaximumActive

@Deprecated
public void setMaximumActive(int maximumActive)

Deprecated. use setMaximumActiveSessionPerConnection(int)

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:

setIdleTimeout

public void setIdleTimeout(int idleTimeout)

Sets the idle timeout value for Connection's that are created by this pool, 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

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.

setTimeBetweenExpirationCheckMillis

public long setTimeBetweenExpirationCheckMillis()

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

setPoolFactory

public void setPoolFactory(org.apache.commons.pool.ObjectPoolFactory<?> factory)

Deprecated.