Class JMSListenerRegistry

java.lang.Object

io.micronaut.jms.listener.JMSListenerRegistry

@Singleton
public class JMSListenerRegistry
extends Object

Registry for all JMSListeners managed by Micronaut JMS. Listeners can be dynamically registered using the register(Connection, JMSDestinationType, String, boolean, int, MessageListener, ExecutorService, boolean, Optional) method. When the application context closes, all open connections, listeners, and sessions, are closed.

The registry listens for the errors that the JMS provider reports on the connections of the listeners it creates. After an error, each listener of the connection checks its session, and one whose session no longer works closes its session and consumer and creates them again on the same connection, retrying with a growing delay as configured until it succeeds or the listener shuts down.

Since:

2.1.1

Author:

Elliott Pope

Constructor Summary

Constructors

Constructor	Description
JMSListenerRegistry(Collection<GlobalJMSListenerSuccessHandler> globalSuccessHandlers, Collection<GlobalJMSListenerErrorHandler> globalErrorHandlers)	Deprecated, for removal: This API element is subject to removal in a future version. Use JMSListenerRegistry(Collection, Collection, Collection, JMSListenerRecoveryConfiguration) instead
JMSListenerRegistry(Collection<GlobalJMSListenerSuccessHandler> globalSuccessHandlers, Collection<GlobalJMSListenerErrorHandler> globalErrorHandlers, Collection<JMSMessageObserver> observers, JMSListenerRecoveryConfiguration recoveryConfiguration)

Method Summary

Modifier and Type	Method	Description
void	register(JMSListener listener, boolean autoStart)	Registers a new listener to be managed by Micronaut JMS.
JMSListener	register(JMSConnectionPool connectionPool, JMSDestinationType destinationType, String destination, boolean transacted, int acknowledgeMode, jakarta.jms.MessageListener delegate, ExecutorService executor, boolean autoStart, Optional<String> messageSelector, @Nullable JMSTopicSubscription subscription)	Creates and registers a new listener to be managed by Micronaut JMS, optionally with a named topic subscription, on a connection the registry opens.
List<JMSListener>	register(JMSConnectionPool connectionPool, JMSDestinationType destinationType, String destination, boolean transacted, int acknowledgeMode, jakarta.jms.MessageListener delegate, ExecutorService executor, boolean autoStart, Optional<String> messageSelector, @Nullable JMSTopicSubscription subscription, int consumers)	Creates and registers the consumers of a destination, each a listener with its own session, on one connection that the registry opens: a connection from the pool, unless the subscription requires a dedicated connection, in which case it is a new connection from the pool's factory with the subscription's client ID.
JMSListener	register(jakarta.jms.Connection connection, JMSDestinationType destinationType, String destination, boolean transacted, int acknowledgeMode, jakarta.jms.MessageListener delegate, ExecutorService executor, boolean autoStart, Optional<String> messageSelector)	Creates and registers a new listener to be managed by Micronaut JMS.
JMSListener	register(jakarta.jms.Connection connection, JMSDestinationType destinationType, String destination, boolean transacted, int acknowledgeMode, jakarta.jms.MessageListener delegate, ExecutorService executor, boolean autoStart, Optional<String> messageSelector, @Nullable JMSTopicSubscription subscription)	Creates and registers a new listener to be managed by Micronaut JMS, optionally with a named topic subscription.
void	shutdown()	Shuts down all registered JMSListeners, returns the pooled connections they were registered with to their pool and closes their dedicated connections, each connection once however many listeners share it.

Methods inherited from class Object

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

Constructor Details

JMSListenerRegistry

@Deprecated(since="5.2.0",
            forRemoval=true)
public JMSListenerRegistry(Collection<GlobalJMSListenerSuccessHandler> globalSuccessHandlers,
 Collection<GlobalJMSListenerErrorHandler> globalErrorHandlers)

Deprecated, for removal: This API element is subject to removal in a future version.

Use JMSListenerRegistry(Collection, Collection, Collection, JMSListenerRecoveryConfiguration) instead

Parameters:

globalSuccessHandlers - The success handlers of every listener

globalErrorHandlers - The error handlers of every listener

JMSListenerRegistry

@Inject
public JMSListenerRegistry(Collection<GlobalJMSListenerSuccessHandler> globalSuccessHandlers,
 Collection<GlobalJMSListenerErrorHandler> globalErrorHandlers,
 Collection<JMSMessageObserver> observers,
 JMSListenerRecoveryConfiguration recoveryConfiguration)

Parameters:

globalSuccessHandlers - The success handlers of every listener

globalErrorHandlers - The error handlers of every listener

observers - The observers of the messages of every listener

recoveryConfiguration - How listeners recover from a failed session

Throws:

io.micronaut.context.exceptions.ConfigurationException - if a recovery delay isn't positive, the maximum delay is shorter than the initial delay, or the number of warning attempts is less than 1

Since:

5.2.0

Method Details

register

public void register(JMSListener listener,
 boolean autoStart)
              throws jakarta.jms.JMSException

Registers a new listener to be managed by Micronaut JMS.

Parameters:

listener - - the listener to be registered

autoStart - - whether the listener should be automatically started when registered

Throws:

jakarta.jms.JMSException - - if the listener fails to start

register

public JMSListener register(jakarta.jms.Connection connection,
 JMSDestinationType destinationType,
 String destination,
 boolean transacted,
 int acknowledgeMode,
 jakarta.jms.MessageListener delegate,
 ExecutorService executor,
 boolean autoStart,
 Optional<String> messageSelector)
                     throws jakarta.jms.JMSException

Creates and registers a new listener to be managed by Micronaut JMS.

Parameters:

connection - - the Connection the listener will be linked to

destinationType - - the JMSDestinationType of the target destination

destination - - the name of the target destination

transacted - - whether the listener should commit the transaction once the message is received

acknowledgeMode - - whether the message receipt should be acknowledged

delegate - - the underlying handler to delegate to

executor - - the ExecutorService to perform the message handling logic on.

autoStart - - whether the listener should be automatically started when registered

messageSelector - - the message selector for the listener

Returns:

the listener that has been registered

Throws:

jakarta.jms.JMSException - - if the listener fails to start

register

public JMSListener register(jakarta.jms.Connection connection,
 JMSDestinationType destinationType,
 String destination,
 boolean transacted,
 int acknowledgeMode,
 jakarta.jms.MessageListener delegate,
 ExecutorService executor,
 boolean autoStart,
 Optional<String> messageSelector,
 @Nullable JMSTopicSubscription subscription)
                     throws jakarta.jms.JMSException

Creates and registers a new listener to be managed by Micronaut JMS, optionally with a named topic subscription. When the subscription requires a dedicated connection, the given connection must not be pooled: the registry closes it when the listener shuts down. If registration fails, the caller still owns the connection and must close it.

Parameters:

connection - - the Connection the listener will be linked to

destinationType - - the JMSDestinationType of the target destination

destination - - the name of the target destination

transacted - - whether the listener should commit the transaction once the message is received

acknowledgeMode - - whether the message receipt should be acknowledged

delegate - - the underlying handler to delegate to

executor - - the ExecutorService to perform the message handling logic on.

autoStart - - whether the listener should be automatically started when registered

messageSelector - - the message selector for the listener

subscription - - the named topic subscription, or null

Returns:

the listener that has been registered

Throws:

jakarta.jms.JMSException - - if the listener fails to start

Since:

5.2.0

register

public JMSListener register(JMSConnectionPool connectionPool,
 JMSDestinationType destinationType,
 String destination,
 boolean transacted,
 int acknowledgeMode,
 jakarta.jms.MessageListener delegate,
 ExecutorService executor,
 boolean autoStart,
 Optional<String> messageSelector,
 @Nullable JMSTopicSubscription subscription)
                     throws jakarta.jms.JMSException

Creates and registers a new listener to be managed by Micronaut JMS, optionally with a named topic subscription, on a connection the registry opens. The connection comes from the pool, unless the subscription requires a dedicated connection: then it is a new connection from the pool's factory with the subscription's client ID, which the registry closes when the listener shuts down or when registration fails. A pooled connection is returned to its pool when registration fails.

Parameters:

connectionPool - - the pool that provides the listener's connection

destinationType - - the JMSDestinationType of the target destination

destination - - the name of the target destination

transacted - - whether the listener should commit the transaction once the message is received

acknowledgeMode - - whether the message receipt should be acknowledged

delegate - - the underlying handler to delegate to

executor - - the ExecutorService to perform the message handling logic on.

autoStart - - whether the listener should be automatically started when registered

messageSelector - - the message selector for the listener

subscription - - the named topic subscription, or null

Returns:

the listener that has been registered

Throws:

jakarta.jms.JMSException - - if the connection cannot be opened or the listener fails to start

Since:

5.2.0

register

public List<JMSListener> register(JMSConnectionPool connectionPool,
 JMSDestinationType destinationType,
 String destination,
 boolean transacted,
 int acknowledgeMode,
 jakarta.jms.MessageListener delegate,
 ExecutorService executor,
 boolean autoStart,
 Optional<String> messageSelector,
 @Nullable JMSTopicSubscription subscription,
 int consumers)
                           throws jakarta.jms.JMSException

Creates and registers the consumers of a destination, each a listener with its own session, on one connection that the registry opens: a connection from the pool, unless the subscription requires a dedicated connection, in which case it is a new connection from the pool's factory with the subscription's client ID. All the consumers share that connection, so they take a single pooled connection however many there are.

Registration stops at the first consumer that fails: the consumers already registered are stopped, the connection is returned to its pool or closed, and the failure is thrown, so that either every consumer is registered or none is.

Parameters:

connectionPool - - the pool that provides the listeners' connection

destinationType - - the JMSDestinationType of the target destination

destination - - the name of the target destination

transacted - - whether the listener should commit the transaction once the message is received

acknowledgeMode - - whether the message receipt should be acknowledged

delegate - - the underlying handler to delegate to, called by every consumer

executor - - the ExecutorService to perform the message handling logic on.

autoStart - - whether the listeners should be automatically started when registered

messageSelector - - the message selector for the listeners

subscription - - the named topic subscription, or null

consumers - - the number of consumers, at least 1

Returns:

the listeners that have been registered, one per consumer

Throws:

jakarta.jms.JMSException - - if the connection cannot be opened or a listener fails to start

IllegalArgumentException - - if consumers is less than 1

Since:

5.2.0

shutdown

@PreDestroy
public void shutdown()

Shuts down all registered JMSListeners, returns the pooled connections they were registered with to their pool and closes their dedicated connections, each connection once however many listeners share it. If a listener fails to shut down then it is logged and skipped, and its pooled connection is not returned to the pool, since it may still hold the listener's session.