The Spring Framework provides extensive support for integrating with messaging systems,
from simplified use of the JMS API using JmsTemplate to a complete infrastructure to
receive messages asynchronously. Spring AMQP provides a similar feature set for the
Advanced Message Queuing Protocol. Spring Boot also provides auto-configuration
options for RabbitTemplate and RabbitMQ. Spring WebSocket natively includes support for
STOMP messaging, and Spring Boot has support for that through starters and a small amount
of auto-configuration. Spring Boot also has support for Apache Kafka.
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 need not use it directly yourself and
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
When ActiveMQ is available on the classpath, Spring Boot can
also configure a ConnectionFactory. If the broker is present, an embedded broker is
automatically started and configured (provided no broker URL is specified through
configuration).
Note
If you use spring-boot-starter-activemq, the necessary dependencies to connect or
embed an ActiveMQ instance are provided, as is 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:
You can also pool JMS resources by adding a dependency to
org.apache.activemq:activemq-pool and configuring the PooledConnectionFactory
accordingly, as shown in the following example:
See
ActiveMQProperties
for more of the supported options. You can also register an arbitrary number of beans
that implement ActiveMQConnectionFactoryCustomizer for more advanced customizations.
By default, ActiveMQ creates a destination if it does not yet exist so that destinations
are resolved against their provided names.
32.1.2 Artemis Support
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 automatically started and configured (unless the mode
property has been explicitly set). The supported modes are embedded (to make explicit
that an embedded broker is required and that an error should occur if the broker is not
available on the classpath) and native (to connect to a broker using the netty
transport protocol). When the latter is configured, Spring Boot configures a
ConnectionFactory that connects to a broker running on the local machine with the
default settings.
Note
If you use 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 lets you use embedded mode.
Artemis configuration is controlled by external configuration properties in
spring.artemis.*. For example, you might declare the following section in
application.properties:
When embedding the broker, you can choose if you want to enable persistence and list the
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.
No JNDI lookup is involved, and destinations are resolved against their names, using
either the name attribute in the Artemis configuration or the names provided through
configuration.
32.1.3 Using a JNDI ConnectionFactory
If you are running your application in an application server, Spring Boot tries to
locate a JMS ConnectionFactory by using JNDI. By default, the java:/JmsXA and
java:/XAConnectionFactory location are checked. You can use the spring.jms.jndi-name
property if you need to specify an alternative location, as shown in the following
example:
spring.jms.jndi-name=java:/MyConnectionFactory
32.1.4 Sending a Message
Spring’s JmsTemplate is auto-configured, and you can autowire it directly into your own
beans, as shown in the following example:
JmsMessagingTemplate can
be injected in a similar manner. If a DestinationResolver or a MessageConverter bean
is defined, it is associated automatically to the auto-configured JmsTemplate.
32.1.5 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 a
MessageConverter beans is defined, it is associated automatically to the default
factory.
By default, the default factory is transactional. If you run in an infrastructure where a
JtaTransactionManager is present, it is associated to the listener container by default.
If not, the sessionTransacted flag is 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 ensures 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:
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 example exposes another factory that uses a specific
MessageConverter:
The Advanced Message Queuing Protocol (AMQP) is a platform-neutral, wire-level protocol
for message-oriented middleware. The Spring AMQP project applies core Spring concepts to
the development of AMQP-based messaging solutions. Spring Boot offers several conveniences
for working with AMQP through RabbitMQ, including the spring-boot-starter-amqp
“Starter”.
32.2.1 RabbitMQ support
RabbitMQ is a lightweight, reliable, scalable, and portable
message broker based on the AMQP protocol. Spring uses RabbitMQ to communicate through
the AMQP protocol.
RabbitMQ configuration is controlled by external configuration properties in
spring.rabbitmq.*. For example, you might declare the following section in
application.properties:
If a ConnectionNameStrategy bean exists in the context, it will be automatically used to
name connections created by the auto-configured ConnectionFactory. See
RabbitProperties for more
of the supported options.
RabbitMessagingTemplate
can be injected in a similar manner. If a MessageConverter bean is defined, it is
associated automatically to the auto-configured AmqpTemplate.
If necessary, any org.springframework.amqp.core.Queue that is defined as a bean is
automatically used to declare a corresponding queue on the RabbitMQ instance.
To retry operations, you can enable retries on the AmqpTemplate (for example, in the
event that the broker connection is lost). Retries are disabled by default.
32.2.3 Receiving a Message
When the Rabbit infrastructure is present, any bean can be annotated with
@RabbitListener to create a listener endpoint. If no RabbitListenerContainerFactory
has been defined, a default SimpleRabbitListenerContainerFactory is automatically
configured and you can switch to a direct container using the
spring.rabbitmq.listener.type property. If a MessageConverter or a MessageRecoverer
bean is defined, it is automatically associated with the default factory.
The following sample component creates a listener endpoint on the someQueue queue:
If you need to create more RabbitListenerContainerFactory instances or if you want to
override the default, Spring Boot provides a
SimpleRabbitListenerContainerFactoryConfigurer and a
DirectRabbitListenerContainerFactoryConfigurer that you can use to initialize a
SimpleRabbitListenerContainerFactory and a DirectRabbitListenerContainerFactory with
the same settings as the factories used by the auto-configuration.
Tip
It does not matter which container type you chose. Those two beans are exposed by
the auto-configuration.
For instance, the following configuration class exposes another factory that uses a
specific MessageConverter:
You can enable retries to handle situations where your listener throws an exception. By
default, RejectAndDontRequeueRecoverer is used, but you can define a MessageRecoverer
of your own. When retries are exhausted, the message is rejected and either dropped or
routed to a dead-letter exchange if the broker is configured to do so. By default,
retries are disabled.
Important
By default, if retries are disabled and the listener throws an exception, the
delivery is retried indefinitely. You can modify this behavior in two ways: Set the
defaultRequeueRejected property to false so that zero re-deliveries are attempted or
throw an AmqpRejectAndDontRequeueException to signal the message should be rejected.
The latter is the mechanism used when retries are enabled and the maximum number of
delivery attempts is reached.
32.3 Apache Kafka Support
Apache Kafka is supported by providing auto-configuration of
the spring-kafka project.
Kafka configuration is controlled by external configuration properties in
spring.kafka.*. For example, you might declare the following section in
application.properties:
If the property spring.kafka.producer.transaction-id-prefix is defined, a
KafkaTransactionManager is automatically configured. Also, if a RecordMessageConverter
bean is defined, it is automatically associated to the auto-configured KafkaTemplate.
32.3.2 Receiving a Message
When the Apache Kafka infrastructure is present, any bean can be annotated with
@KafkaListener to create a listener endpoint. If no KafkaListenerContainerFactory has
been defined, a default one is automatically configured with keys defined in
spring.kafka.listener.*. Also, if a RecordMessageConverter bean is defined, it is
automatically associated to the default factory.
The following component creates a listener endpoint on the someTopic topic:
The properties supported by auto configuration are shown in
Appendix A, Common application properties. Note that, for the most part, these properties
(hyphenated or camelCase) map directly to the Apache Kafka dotted properties. Refer to the
Apache Kafka documentation for details.
The first few of these properties apply to both producers and consumers but can be
specified at the producer or consumer level if you wish to use different values for each.
Apache Kafka designates properties with an importance of HIGH, MEDIUM, or LOW. Spring Boot
auto-configuration supports all HIGH importance properties, some selected MEDIUM and LOW
properties, and any properties that do not have a default value.
Only a subset of the properties supported by Kafka are available through the
KafkaProperties class. If you wish to configure the producer or consumer with additional
properties that are not directly supported, use the following properties:
This sets the common prop.one Kafka property to first (applies to producers,
consumers and admins), the prop.two admin property to second, the prop.three
consumer property to third and the prop.four producer property to fourth.
You can also configure the Spring Kafka JsonDeserializer as follows: