32.1 JMS
The javax.jms.ConnectionFactory
interface provides a standard method of creating a javax.jms.Connection
for interacting with a JMS broker. Although Spring needs a ConnectionFactory
to work with JMS, you generally won’t need to use it directly yourself and you can instead rely on higher level messaging abstractions (see the relevant section of the Spring Framework reference documentation for details). Spring Boot also auto-configures the necessary infrastructure to send and receive messages.
32.1.1 ActiveMQ support
Spring Boot can also configure a ConnectionFactory
when it detects that ActiveMQ is available on the classpath. If the broker is present, an embedded broker is started and configured automatically (as long as no broker URL is specified through configuration).
Note | |
---|---|
If you are using spring-boot-starter-activemq the necessary dependencies to connect or embed an ActiveMQ instance are provided, as well as the Spring infrastructure to integrate with JMS. |
ActiveMQ configuration is controlled by external configuration properties in spring.activemq.*
. For example, you might declare the following section in application.properties
:
spring.activemq.broker-url=tcp://192.168.1.210:9876 spring.activemq.user=admin spring.activemq.password=secret
See ActiveMQProperties
for more of the supported options.
By default, ActiveMQ creates a destination if it does not exist yet, so destinations are resolved against their provided names.
32.1.2 Artemis support
Apache Artemis was formed in 2015 when HornetQ was donated to the Apache Foundation. Make sure to use that rather than the deprecated HornetQ support.
Note | |
---|---|
You should not try and use Artemis and HornetQ at the same time. |
Spring Boot can auto-configure a ConnectionFactory
when it detects that Artemis is available on the classpath. If the broker is present, an embedded broker is started and configured automatically (unless the mode property has been explicitly set). The supported modes are: embedded
(to make explicit that an embedded broker is required and should lead to an error if the broker is not available in the classpath), and native
to connect to a broker using the netty
transport protocol. When the latter is configured, Spring Boot configures a ConnectionFactory
connecting to a broker running on the local machine with the default settings.
Note | |
---|---|
If you are using spring-boot-starter-artemis the necessary dependencies to connect to an existing Artemis instance are provided, as well as the Spring infrastructure to integrate with JMS. Adding org.apache.activemq:artemis-jms-server to your application allows you to use the embedded mode. |
Artemis configuration is controlled by external configuration properties in spring.artemis.*
. For example, you might declare the following section in application.properties
:
spring.artemis.mode=native spring.artemis.host=192.168.1.210 spring.artemis.port=9876 spring.artemis.user=admin spring.artemis.password=secret
When embedding the broker, you can choose if you want to enable persistence, and the list of destinations that should be made available. These can be specified as a comma-separated list to create them with the default options; or you can define bean(s) of type org.apache.activemq.artemis.jms.server.config.JMSQueueConfiguration
or org.apache.activemq.artemis.jms.server.config.TopicConfiguration
, for advanced queue and topic configurations respectively.
See ArtemisProperties
for more of the supported options.
No JNDI lookup is involved at all and destinations are resolved against their names, either using the ‘name’ attribute in the Artemis configuration or the names provided through configuration.
32.1.3 HornetQ support
Note | |
---|---|
HornetQ is deprecated in 1.4, consider migrating to artemis |
Spring Boot can auto-configure a ConnectionFactory
when it detects that HornetQ is available on the classpath. If the broker is present, an embedded broker is started and configured automatically (unless the mode property has been explicitly set). The supported modes are: embedded
(to make explicit that an embedded broker is required and should lead to an error if the broker is not available in the classpath), and native
to connect to a broker using the netty
transport protocol. When the latter is configured, Spring Boot configures a ConnectionFactory
connecting to a broker running on the local machine with the default settings.
Note | |
---|---|
If you are using spring-boot-starter-hornetq the necessary dependencies to connect to an existing HornetQ instance are provided, as well as the Spring infrastructure to integrate with JMS. Adding org.hornetq:hornetq-jms-server to your application allows you to use the embedded mode. |
HornetQ configuration is controlled by external configuration properties in spring.hornetq.*
. For example, you might declare the following section in application.properties
:
spring.hornetq.mode=native spring.hornetq.host=192.168.1.210 spring.hornetq.port=9876 spring.hornetq.user=admin spring.hornetq.password=secret
When embedding the broker, you can choose if you want to enable persistence, and the list of destinations that should be made available. These can be specified as a comma-separated list to create them with the default options; or you can define bean(s) of type org.hornetq.jms.server.config.JMSQueueConfiguration
or org.hornetq.jms.server.config.TopicConfiguration
, for advanced queue and topic configurations respectively.
See HornetQProperties
for more of the supported options.
No JNDI lookup is involved at all and destinations are resolved against their names, either using the ‘name’ attribute in the HornetQ configuration or the names provided through configuration.
32.1.4 Using a JNDI ConnectionFactory
If you are running your application in an Application Server Spring Boot will attempt to locate a JMS ConnectionFactory
using JNDI. By default the locations java:/JmsXA
and java:/XAConnectionFactory
will be checked. You can use the spring.jms.jndi-name
property if you need to specify an alternative location:
spring.jms.jndi-name=java:/MyConnectionFactory
32.1.5 Sending a message
Spring’s JmsTemplate
is auto-configured and you can autowire it directly into your own beans:
import org.springframework.beans.factory.annotation.Autowired; import org.springframework.jms.core.JmsTemplate; import org.springframework.stereotype.Component; _@Component_ public class MyBean { private final JmsTemplate jmsTemplate; _@Autowired_ public MyBean(JmsTemplate jmsTemplate) { this.jmsTemplate = jmsTemplate; } // ... }
Note | |
---|---|
JmsMessagingTemplate can be injected in a similar manner. If a DestinationResolver or MessageConverter beans are defined, they are associated automatically to the auto-configured JmsTemplate . |
32.1.6 Receiving a message
When the JMS infrastructure is present, any bean can be annotated with @JmsListener
to create a listener endpoint. If no JmsListenerContainerFactory
has been defined, a default one is configured automatically. If a DestinationResolver
or MessageConverter
beans are defined, they are associated automatically to the default factory.
The default factory is transactional by default. If you are running in an infrastructure where a JtaTransactionManager
is present, it will be associated to the listener container by default. If not, the sessionTransacted
flag will be enabled. In that latter scenario, you can associate your local data store transaction to the processing of an incoming message by adding @Transactional
on your listener method (or a delegate thereof). This will make sure that the incoming message is acknowledged once the local transaction has completed. This also includes sending response messages that have been performed on the same JMS session.
The following component creates a listener endpoint on the someQueue
destination:
_@Component_ public class MyBean { _@JmsListener(destination = "someQueue")_ public void processMessage(String content) { // ... } }
Tip | |
---|---|
Check the Javadoc of @EnableJms for more details. |
If you need to create more JmsListenerContainerFactory
instances or if you want to override the default, Spring Boot provides a DefaultJmsListenerContainerFactoryConfigurer
that you can use to initialize a DefaultJmsListenerContainerFactory
with the same settings as the one that is auto-configured.
For instance, the following exposes another factory that uses a specific MessageConverter
:
_@Configuration_ static class JmsConfiguration { _@Bean_ public DefaultJmsListenerContainerFactory myFactory( DefaultJmsListenerContainerFactoryConfigurer configurer) { DefaultJmsListenerContainerFactory factory = new DefaultJmsListenerContainerFactory(); configurer.configure(factory, connectionFactory()); factory.setMessageConverter(myMessageConverter()); return factory; } }
Then you can use in any @JmsListener
-annotated method as follows:
_@Component_ public class MyBean { @JmsListener(destination = "someQueue", **containerFactory="myFactory"**) public void processMessage(String content) { // ... } }