Package 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 Details

    • DEFAULT_MAX_SESSIONS_PER_CONNECTION

      public static final int DEFAULT_MAX_SESSIONS_PER_CONNECTION
      See Also:

    • DEFAULT_MAX_CONNECTIONS

      public static final int DEFAULT_MAX_CONNECTIONS
      See Also:

    • stopped

      protected final AtomicBoolean stopped

    • connectionFactory

      protected Object connectionFactory

    • jmsContextSupported

      protected boolean jmsContextSupported

  • Constructor Details

    • JmsPoolConnectionFactory

      public JmsPoolConnectionFactory()

  • Method Details

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

    • getMaxIdleSessionsPerConnection

      public int getMaxIdleSessionsPerConnection()
      Returns the currently configured maximum idle sessions per connection which by default matches the configured maximum active sessions per connection.
      Returns:
      the number if idle sessions allowed per connection before they are closed.
      See Also:

    • setMaxIdleSessionsPerConnection

      public void setMaxIdleSessionsPerConnection(int maxIdleSessionsPerConnection)
      Sets the configured maximum idle sessions per connection which by default matches the configured maximum active sessions per connection. This option allows the pool to be configured to close sessions that are returned to the pool if the number of idle (not in use Sessions) exceeds this amount which can reduce the amount of resources that are allocated but not in use.

      If the application in use opens and closes large amounts of sessions then leaving this option at the default means that there is a higher chance that an idle session will be available in the pool without the need to create a new instance however this does allow for more idle resources to exist so in cases where turnover is low with only occasional bursts in workloads it can be advantageous to lower this value to allow sessions to be fully closed on return to the pool if there are already enough idle sessions to exceed this amount.

      If the max idle sessions per connection is configured larger than the max sessions value it will be truncated to the max sessions value to conform to the total limit on how many sessions can exists at any given time on a per connection basis.

      Parameters:
      maxIdleSessionsPerConnection - the number if idle sessions allowed per connection before they are closed.
      See Also:

    • 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.
      See Also:

    • setMaxSessionsPerConnection

      public void setMaxSessionsPerConnection(int maxSessionsPerConnection)
      Sets the maximum number of pooled sessions allowed per connection.

      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:

    • 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.
      See Also:

    • 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.
      See Also:

    • 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:

    • 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.
      See Also:

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