Package org.apache.activemq.jms.pool

Class PooledConnectionFactory

  • All Implemented Interfaces:
    ConnectionFactory, QueueConnectionFactory, TopicConnectionFactory
    Direct Known Subclasses:
    PooledConnectionFactory, XaPooledConnectionFactory
    public class PooledConnectionFactory
extends Object
implements ConnectionFactory, QueueConnectionFactory, TopicConnectionFactory
    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 Detail

      • connectionFactory

        protected Object connectionFactory

    • Constructor Detail

      • PooledConnectionFactory

        public PooledConnectionFactory()

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

      • 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(boolean)

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

      • getConnectionTimeout

        public int getConnectionTimeout()
        Gets the connection timeout value. The maximum time waited to get a Connection from the pool. The default value is 30 seconds.
        Returns:
        connection timeout value (milliseconds)

      • setConnectionTimeout

        public void setConnectionTimeout​(int connectionTimeout)
        Sets the connection timeout value for getting Connections from this pool in Milliseconds, defaults to 30 seconds.
        Parameters:
        connectionTimeout - The maximum time to wait for getting a pooled Connection.

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

      • 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 @see #maximumActive property. Whether or not the call to create session blocks is controlled by the @see #blockIfSessionPoolIsFull property
        Parameters:
        blockIfSessionPoolIsFullTimeout - - if blockIfSessionPoolIsFullTimeout is true, then use this setting to configure how long to block before retry

      • isReconnectOnException

        public boolean isReconnectOnException()
        Returns:
        true if the underlying connection will be renewed on JMSException, false otherwise

      • setReconnectOnException

        public void setReconnectOnException​(boolean reconnectOnException)
        Controls weather the underlying connection should be reset (and renewed) on JMSException
        Parameters:
        reconnectOnException - Boolean value that configures whether reconnect on exception should happen

      • populateProperties

        protected void populateProperties​(Properties props)
        Called by any superclass that implements a JNDIReferencable 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.