org.messaginghub.pooled.jms

Class JmsPoolConnectionFactory

java.lang.Object

org.messaginghub.pooled.jms.JmsPoolConnectionFactory

All Implemented Interfaces:

javax.jms.ConnectionFactory, javax.jms.QueueConnectionFactory, javax.jms.TopicConnectionFactory

Direct Known Subclasses:

JmsPoolXAConnectionFactory

public class JmsPoolConnectionFactory
extends Object
implements javax.jms.ConnectionFactory, javax.jms.QueueConnectionFactory, javax.jms.TopicConnectionFactory

A JMS provider which pools Connection, Session and MessageProducer instances so it can be used with tools like Camel or any other project that is configured using JMS ConnectionFactory resources, 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. 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, the broker may 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 a "connection check" thread, which runs asynchronously. Caution should be used when configuring this optional feature. Connection check runs contend with client threads for access to resources in the pool, so if they run too frequently performance issues may result. The connection check thread may be configured using the setConnectionCheckInterval(long) method. By default the value is -1 which means no connection check thread will be run. Set to a non-negative value to configure the connection check thread to run.

Field Summary

Fields

Modifier and Type	Field and Description
protected Object	connectionFactory
static int	DEFAULT_MAX_CONNECTIONS
protected boolean	jmsContextSupported
protected AtomicBoolean	stopped

Constructor Summary

Constructors

Constructor and Description
JmsPoolConnectionFactory()

Method Summary

Modifier and Type	Method and Description
void	clear() Clears all connections from the pool.
javax.jms.Connection	createConnection()
javax.jms.Connection	createConnection(String userName, String password)
javax.jms.JMSContext	createContext()
javax.jms.JMSContext	createContext(int sessionMode)
javax.jms.JMSContext	createContext(String username, String password)
javax.jms.JMSContext	createContext(String username, String password, int sessionMode)
protected PooledConnection	createPooledConnection(javax.jms.Connection connection) Delegate that creates each instance of an ConnectionPool object.
protected javax.jms.Connection	createProviderConnection(PooledConnectionKey key) Given a PooledConnectionKey create a JMS Connection using the configuration from the key and the assigned JMS ConnectionFactory instance.
protected javax.jms.JMSContext	createProviderContext(String username, String password, int sessionMode) Create a new JMSContext using the provided credentials and Session mode
javax.jms.QueueConnection	createQueueConnection()
javax.jms.QueueConnection	createQueueConnection(String userName, String password)
javax.jms.TopicConnection	createTopicConnection()
javax.jms.TopicConnection	createTopicConnection(String userName, String password)
long	getBlockIfSessionPoolIsFullTimeout() Returns the timeout to use for blocking creating new sessions
long	getConnectionCheckInterval()
Object	getConnectionFactory()
int	getConnectionIdleTimeout() Gets the idle timeout value applied to Connection's that are created by this pool but are not currently in use.
protected org.apache.commons.pool2.impl.GenericKeyedObjectPool<PooledConnectionKey,PooledConnection>	getConnectionsPool() Gets the Pool of ConnectionPool instances which are keyed by different ConnectionKeys.
int	getExplicitProducerCacheSize() Returns the currently configured producer cache size that will be used in a pooled Session when the pooled Session is not configured to use a single anonymous producer.
int	getMaxConnections() Returns the maximum number to pooled Connections that this factory will allow before it begins to return existing connections from the pool on calls to (createConnection().
int	getMaxSessionsPerConnection() 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()
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	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.
boolean	isUseProviderJMSContext()
protected JmsPoolJMSContext	newPooledConnectionContext(JmsPoolConnection connection, int sessionMode) Allows subclasses to create an appropriate JmsPoolJMSContext wrapper for the newly create JMSContext such as one that provides support for XA Transactions.
protected JmsPoolConnection	newPooledConnectionWrapper(PooledConnection connection) Allows subclasses to create an appropriate JmsPoolConnection wrapper for the newly create connection such as one that provides support for XA Transactions.
protected void	populateProperties(Properties props) Called by any superclass that implements a JNDI Referenceable or similar that needs to collect the properties of this class for storage etc.
void	setBlockIfSessionPoolIsFull(boolean block) Controls the behavior of the internal session pool.
void	setBlockIfSessionPoolIsFullTimeout(long blockIfSessionPoolIsFullTimeout) Controls the behavior of the internal Session pool.
void	setConnectionCheckInterval(long connectionCheckInterval) Sets the number of milliseconds to sleep between runs of the Connection check thread.
void	setConnectionFactory(Object factory) Sets the ConnectionFactory used to create new pooled Connections.
void	setConnectionIdleTimeout(int connectionIdleTimeout) Sets the idle timeout value for Connection's that are created by this pool but not in use in Milliseconds (defaults to 30 seconds).
void	setExplicitProducerCacheSize(int cacheSize) Sets whether a pooled Session uses a cache for MessageProducer instances that are created against an explicit destination instead of creating new MessageProducer on each call to Session.createProducer(javax.jms.Destination).
void	setMaxConnections(int maxConnections) Sets the maximum number of pooled Connections (defaults to one).
void	setMaxSessionsPerConnection(int maxSessionsPerConnection) Sets the maximum number of pooled sessions per connection in the pool.
void	setUseAnonymousProducers(boolean value) Sets whether a pooled Session uses only one anonymous MessageProducer instance or creates a new MessageProducer for each call the create a MessageProducer.
void	setUseProviderJMSContext(boolean useProviderJMSContext) Controls the behavior of the createContext() methods.
void	start() Starts the Connection pool.
void	stop() Stops the pool from providing any new connections and closes all pooled Connections.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_CONNECTIONS

public static final int DEFAULT_MAX_CONNECTIONS

See Also:

Constant Field Values

stopped

protected final AtomicBoolean stopped

connectionFactory

protected Object connectionFactory

jmsContextSupported

protected boolean jmsContextSupported

Constructor Detail

JmsPoolConnectionFactory

public JmsPoolConnectionFactory()

Method Detail

initConnectionsPool

public void initConnectionsPool()

getConnectionFactory

public Object getConnectionFactory()

Returns:

the currently configured ConnectionFactory used to create the pooled Connections.

setConnectionFactory

public void setConnectionFactory(Object factory)

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:

factory - The factory to use to create pooled Connections.

createQueueConnection

public javax.jms.QueueConnection createQueueConnection()
                                                throws javax.jms.JMSException

Specified by:

createQueueConnection in interface javax.jms.QueueConnectionFactory

Throws:

javax.jms.JMSException

createQueueConnection

public javax.jms.QueueConnection createQueueConnection(String userName,
                                                       String password)
                                                throws javax.jms.JMSException

Specified by:

createQueueConnection in interface javax.jms.QueueConnectionFactory

Throws:

javax.jms.JMSException

createTopicConnection

public javax.jms.TopicConnection createTopicConnection()
                                                throws javax.jms.JMSException

Specified by:

createTopicConnection in interface javax.jms.TopicConnectionFactory

Throws:

javax.jms.JMSException

createTopicConnection

public javax.jms.TopicConnection createTopicConnection(String userName,
                                                       String password)
                                                throws javax.jms.JMSException

Specified by:

createTopicConnection in interface javax.jms.TopicConnectionFactory

Throws:

javax.jms.JMSException

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

createContext

public javax.jms.JMSContext createContext()

Specified by:

createContext in interface javax.jms.ConnectionFactory

createContext

public javax.jms.JMSContext createContext(int sessionMode)

Specified by:

createContext in interface javax.jms.ConnectionFactory

createContext

public javax.jms.JMSContext createContext(String username,
                                          String password)

Specified by:

createContext in interface javax.jms.ConnectionFactory

createContext

public javax.jms.JMSContext createContext(String username,
                                          String password,
                                          int sessionMode)

Specified by:

createContext in interface javax.jms.ConnectionFactory

start

public void start()

Starts the Connection pool.

If configured to do so this method will attempt to create an initial Connection to place into the pool using the default ConnectionFactory.createConnection() from the configured provider ConnectionFactory.

stop

public void stop()

Stops the pool from providing any new connections and closes all pooled Connections.

This method stops services from the JMS Connection Pool closing down any Connections in the pool regardless of them being loaned out at the time. The pool cannot be restarted after a call to 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() if the pool has not been stopped. Care should be taken when using this method as Connections that are in use by the client will be closed.

getMaxSessionsPerConnection

public int getMaxSessionsPerConnection()

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.

setMaxSessionsPerConnection

public void setMaxSessionsPerConnection(int maxSessionsPerConnection)

Sets the maximum number of pooled sessions per connection in the pool.

A Connection that is created from this JMS Connection pool can limit the number of Sessions that are created and loaned out. When a limit is in place the client application must be prepared to respond to failures or hangs of the various Connection.createSession() methods.

Because Connections can be borrowed and returned at will the available Sessions for a Connection in the pool can change dynamically so even on fresh checkout from this pool a Connection may not have any available Session instances to loan out if a limit is configured.

Parameters:

maxSessionsPerConnection - The maximum number of pooled sessions 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.createSession() will block if the session pool is full. If the block options is set to false, it will change the default behavior and instead the call to create a Session will throw a JMSException.

The size of the session pool is controlled by the getMaxSessionsPerConnection() configuration property.

Parameters:

block - if true, the call to Connection.createSession() blocks if the session pool is full until a session 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(boolean)

getMaxConnections

public int getMaxConnections()

Returns the maximum number to pooled Connections that this factory will allow before it begins to return existing 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 created up to the max connections value, once the maximum Connections have been created Connections are served in a last in first out ordering.

Parameters:

maxConnections - the maximum Connections to pool for a given user / password combination.

getConnectionIdleTimeout

public int getConnectionIdleTimeout()

Gets the idle timeout value applied to Connection's that are created by this pool but are not currently in use.

Returns:

the connection idle timeout value in (milliseconds).

setConnectionIdleTimeout

public void setConnectionIdleTimeout(int connectionIdleTimeout)

Sets the idle timeout value for Connection's that are created by this pool but not in use 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. To evict idle connections in a more timely manner the setConnectionCheckInterval(long) can be configured to a non-zero value and the pool will actively check for idle connections that have exceeded their idle timeout value.

Parameters:

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

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 pooled Session will use only a single anonymous message producer instance.

setUseAnonymousProducers

public void setUseAnonymousProducers(boolean value)

Sets whether a pooled Session 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.

getExplicitProducerCacheSize

public int getExplicitProducerCacheSize()

Returns the currently configured producer cache size that will be used in a pooled Session when the pooled Session is not configured to use a single anonymous producer.

Returns:

the current explicit producer cache size.

setExplicitProducerCacheSize

public void setExplicitProducerCacheSize(int cacheSize)

Sets whether a pooled Session uses a cache for MessageProducer instances that are created against an explicit destination instead of creating new MessageProducer on each call to Session.createProducer(javax.jms.Destination).

When caching explicit producers the cache will hold up to the configured number of producers and if more producers are created than the configured cache size the oldest or lest recently used producers are evicted from the cache and will be closed when all references to that producer are explicitly closed or when the pooled session instance is closed. By default this value is set to zero and no caching is done for explicit producers created by the pooled session.

This caching would only be done when the setUseAnonymousProducers(boolean) configuration option is disabled.

Parameters:

cacheSize - The number of explicit producers to cache in the pooled Session

setConnectionCheckInterval

public void setConnectionCheckInterval(long connectionCheckInterval)

Sets the number of milliseconds to sleep between runs of the Connection check thread. When non-positive, no connection check thread will be run, and Connections will only be checked on borrow to determine if they are still valid and can continue to be used or should be closed and or evicted from the pool.

By default this value is set to -1 and a connection check thread is not started.

Parameters:

connectionCheckInterval - The time to wait between runs of the Connection check thread.

getConnectionCheckInterval

public long getConnectionCheckInterval()

Returns:

the number of milliseconds to sleep between runs of the connection check thread.

getNumConnections

public int getNumConnections()

Returns:

the number of Connections currently in the Pool

getBlockIfSessionPoolIsFullTimeout

public long getBlockIfSessionPoolIsFullTimeout()

Returns the timeout to use for blocking creating new sessions

Returns:

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

See Also:

setBlockIfSessionPoolIsFull(boolean)

setBlockIfSessionPoolIsFullTimeout

public void setBlockIfSessionPoolIsFullTimeout(long blockIfSessionPoolIsFullTimeout)

Controls the behavior of the internal Session pool. By default the call to Connection.getSession() will block if the Session pool is full. This setting will affect how long it blocks and throws an exception after the timeout.

The size of the session pool is controlled by the setMaxSessionsPerConnection(int) value that has been configured. Whether or not the call to create session blocks is controlled by the setBlockIfSessionPoolIsFull(boolean) property.

By default the timeout defaults to -1 and a blocked call to create a Session will wait indefinitely for a new Session

Parameters:

blockIfSessionPoolIsFullTimeout - if blockIfSessionPoolIsFullTimeout is true then use this setting to configure how long to block before an error is thrown.

isUseProviderJMSContext

public boolean isUseProviderJMSContext()

Returns:

the true if the pool is using the provider's JMSContext instead of a pooled version.

setUseProviderJMSContext

public void setUseProviderJMSContext(boolean useProviderJMSContext)

Controls the behavior of the createContext() methods.

By default this value is set to false and the JMS Pool will use n pooled version of a JMSContext to wrap Connections from the pool. These pooled JMSContext objects have certain limitations which may not be desirable in some cases. To use the JMSContext implementation from the underlying JMS provider this option can be set to true however in that case no pooling will be applied to the JMSContext's create or their underlying connections.

Parameters:

useProviderJMSContext - Boolean value indicating whether the pool should include JMSContext in the pooling.

getConnectionsPool

protected org.apache.commons.pool2.impl.GenericKeyedObjectPool<PooledConnectionKey,PooledConnection> getConnectionsPool()

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

Returns:

this factories pool of ConnectionPool instances.

createPooledConnection

protected PooledConnection createPooledConnection(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 - The connection that is being added into the pool.

Returns:

instance of a new ConnectionPool.

newPooledConnectionWrapper

protected JmsPoolConnection newPooledConnectionWrapper(PooledConnection connection)

Allows subclasses to create an appropriate JmsPoolConnection wrapper for the newly create connection such as one that provides support for XA Transactions.

Parameters:

connection - The PooledConnection to wrap.

Returns:

a new JmsPoolConnection that wraps the given PooledConnection

newPooledConnectionContext

protected JmsPoolJMSContext newPooledConnectionContext(JmsPoolConnection connection,
                                                       int sessionMode)

Allows subclasses to create an appropriate JmsPoolJMSContext wrapper for the newly create JMSContext such as one that provides support for XA Transactions.

Parameters:

connection - The JmsPoolConnection to use in the JMSContext wrapper.

sessionMode - The JMS Session acknowledgement mode to use in the JMSContext

Returns:

a new JmsPoolJMSContext that wraps the given JmsPoolConnection

createProviderConnection

protected javax.jms.Connection createProviderConnection(PooledConnectionKey key)
                                                 throws javax.jms.JMSException

Given a PooledConnectionKey create a JMS Connection using the configuration from the key and the assigned JMS ConnectionFactory instance.

Parameters:

key - The PooledSessionKey to use as configuration for the new JMS Connection.

Returns:

a new JMS Connection created using the configured JMS ConnectionFactory.

Throws:

javax.jms.JMSException - if an error occurs while creating the new JMS Connection.

createProviderContext

protected javax.jms.JMSContext createProviderContext(String username,
                                                     String password,
                                                     int sessionMode)

Create a new JMSContext using the provided credentials and Session mode

Parameters:

username - The user name to use when creating the context.

password - The password to use when creating the context.

sessionMode - The session mode to use when creating the context.

Returns:

a new JMSContext created using the given configuration data..

Throws:

javax.jms.JMSRuntimeException - if an error occurs while creating the new JMS Context.

populateProperties

protected void populateProperties(Properties props)

Called by any superclass that implements a JNDI Referenceable or similar that needs to collect the properties of this class for storage etc. This method should be updated any time there is a new property added.

Parameters:

props - a properties object that should be filled in with this objects property values.