Package org.messaginghub.pooled.jms

Class 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 Detail

      • DEFAULT_MAX_CONNECTIONS

        public static final int DEFAULT_MAX_CONNECTIONS
        See Also:
        Constant Field Values

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

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