Split spring boot features into multiple sections
See gh-27132
This commit is contained in:
Madhura Bhave
@@ -0,0 +1,123 @@
|
||||
[[messaging.amqp]]
|
||||
== AMQP
|
||||
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`".
|
||||
|
||||
|
||||
|
||||
[[messaging.amqp.rabbitmq]]
|
||||
=== RabbitMQ support
|
||||
https://www.rabbitmq.com/[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`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
host: "localhost"
|
||||
port: 5672
|
||||
username: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
Alternatively, you could configure the same connection using the `addresses` attribute:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
addresses: "amqp://admin:secret@localhost"
|
||||
----
|
||||
|
||||
NOTE: When specifying addresses that way, the `host` and `port` properties are ignored.
|
||||
If the address uses the `amqps` protocol, SSL support is enabled automatically.
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/amqp/RabbitProperties.java[`RabbitProperties`] for more of the supported property-based configuration options.
|
||||
To configure lower-level details of the RabbitMQ `ConnectionFactory` that is used by Spring AMQP, define a `ConnectionFactoryCustomizer` bean.
|
||||
|
||||
If a `ConnectionNameStrategy` bean exists in the context, it will be automatically used to name connections created by the auto-configured `CachingConnectionFactory`.
|
||||
|
||||
TIP: See https://spring.io/blog/2010/06/14/understanding-amqp-the-protocol-used-by-rabbitmq/[Understanding AMQP, the protocol used by RabbitMQ] for more details.
|
||||
|
||||
|
||||
|
||||
[[messaging.amqp.sending]]
|
||||
=== Sending a Message
|
||||
Spring's `AmqpTemplate` and `AmqpAdmin` are auto-configured, and you can autowire them directly into your own beans, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/amqp/sending/MyBean.java[]
|
||||
----
|
||||
|
||||
NOTE: {spring-amqp-api}/rabbit/core/RabbitMessagingTemplate.html[`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):
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rabbitmq:
|
||||
template:
|
||||
retry:
|
||||
enabled: true
|
||||
initial-interval: "2s"
|
||||
----
|
||||
|
||||
Retries are disabled by default.
|
||||
You can also customize the `RetryTemplate` programmatically by declaring a `RabbitRetryTemplateCustomizer` bean.
|
||||
|
||||
If you need to create more `RabbitTemplate` instances or if you want to override the default, Spring Boot provides a `RabbitTemplateConfigurer` bean that you can use to initialize a `RabbitTemplate` with the same settings as the factories used by the auto-configuration.
|
||||
|
||||
|
||||
|
||||
[[messaging.amqp.receiving]]
|
||||
=== 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 configprop: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:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/amqp/receiving/MyBean.java[]
|
||||
----
|
||||
|
||||
TIP: See {spring-amqp-api}/rabbit/annotation/EnableRabbit.html[the Javadoc of `@EnableRabbit`] for more details.
|
||||
|
||||
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`:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/amqp/receiving/custom/MyRabbitConfiguration.java[]
|
||||
----
|
||||
|
||||
Then you can use the factory in any `@RabbitListener`-annotated method, as follows:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/amqp/receiving/custom/MyBean.java[]
|
||||
----
|
||||
|
||||
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.
|
||||
You can also customize the `RetryTemplate` programmatically by declaring a `RabbitRetryTemplateCustomizer` bean.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,175 @@
|
||||
[[messaging.jms]]
|
||||
== 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 {spring-framework-docs}/integration.html#jms[relevant section] of the Spring Framework reference documentation for details.)
|
||||
Spring Boot also auto-configures the necessary infrastructure to send and receive messages.
|
||||
|
||||
|
||||
|
||||
[[messaging.jms.activemq]]
|
||||
=== ActiveMQ Support
|
||||
When https://activemq.apache.org/[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`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
activemq:
|
||||
broker-url: "tcp://192.168.1.210:9876"
|
||||
user: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jms:
|
||||
cache:
|
||||
session-cache-size: 5
|
||||
----
|
||||
|
||||
If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
activemq:
|
||||
pool:
|
||||
enabled: true
|
||||
max-connections: 50
|
||||
----
|
||||
|
||||
TIP: See {spring-boot-autoconfigure-module-code}/jms/activemq/ActiveMQProperties.java[`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.
|
||||
|
||||
|
||||
|
||||
[[messaging.jms.artemis]]
|
||||
=== ActiveMQ Artemis Support
|
||||
Spring Boot can auto-configure a `ConnectionFactory` when it detects that https://activemq.apache.org/components/artemis/[ActiveMQ 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 ActiveMQ 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.
|
||||
|
||||
ActiveMQ Artemis configuration is controlled by external configuration properties in `+spring.artemis.*+`.
|
||||
For example, you might declare the following section in `application.properties`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
artemis:
|
||||
mode: native
|
||||
broker-url: "tcp://192.168.1.210:9876"
|
||||
user: "admin"
|
||||
password: "secret"
|
||||
----
|
||||
|
||||
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.
|
||||
|
||||
By default, a `CachingConnectionFactory` wraps the native `ConnectionFactory` with sensible settings that you can control by external configuration properties in `+spring.jms.*+`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jms:
|
||||
cache:
|
||||
session-cache-size: 5
|
||||
----
|
||||
|
||||
If you'd rather use native pooling, you can do so by adding a dependency to `org.messaginghub:pooled-jms` and configuring the `JmsPoolConnectionFactory` accordingly, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
artemis:
|
||||
pool:
|
||||
enabled: true
|
||||
max-connections: 50
|
||||
----
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/jms/artemis/ArtemisProperties.java[`ArtemisProperties`] for more supported options.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
[[messaging.jms.jndi]]
|
||||
=== 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 configprop:spring.jms.jndi-name[] property if you need to specify an alternative location, as shown in the following example:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
jms:
|
||||
jndi-name: "java:/MyConnectionFactory"
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[messaging.jms.sending]]
|
||||
=== 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:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/jms/sending/MyBean.java[]
|
||||
----
|
||||
|
||||
NOTE: {spring-framework-api}/jms/core/JmsMessagingTemplate.html[`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`.
|
||||
|
||||
|
||||
|
||||
[[messaging.jms.receiving]]
|
||||
=== 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`, a `MessageConverter`, or a `javax.jms.ExceptionListener` beans are defined, they are associated automatically with 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:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/jms/receiving/MyBean.java[]
|
||||
----
|
||||
|
||||
TIP: See {spring-framework-api}/jms/annotation/EnableJms.html[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 example exposes another factory that uses a specific `MessageConverter`:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/jms/receiving/custom/MyJmsConfiguration.java[]
|
||||
----
|
||||
|
||||
Then you can use the factory in any `@JmsListener`-annotated method as follows:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/jms/receiving/custom/MyBean.java[]
|
||||
----
|
||||
@@ -0,0 +1,178 @@
|
||||
[[messaging.kafka]]
|
||||
== Apache Kafka Support
|
||||
https://kafka.apache.org/[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`:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
bootstrap-servers: "localhost:9092"
|
||||
consumer:
|
||||
group-id: "myGroup"
|
||||
----
|
||||
|
||||
TIP: To create a topic on startup, add a bean of type `NewTopic`.
|
||||
If the topic already exists, the bean is ignored.
|
||||
|
||||
See {spring-boot-autoconfigure-module-code}/kafka/KafkaProperties.java[`KafkaProperties`] for more supported options.
|
||||
|
||||
|
||||
|
||||
[[messaging.kafka.sending]]
|
||||
=== Sending a Message
|
||||
Spring's `KafkaTemplate` is auto-configured, and you can autowire it directly in your own beans, as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/kafka/sending/MyBean.java[]
|
||||
----
|
||||
|
||||
NOTE: If the property configprop: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`.
|
||||
|
||||
|
||||
|
||||
[[messaging.kafka.receiving]]
|
||||
=== 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.*`.
|
||||
|
||||
The following component creates a listener endpoint on the `someTopic` topic:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/kafka/receiving/MyBean.java[]
|
||||
----
|
||||
|
||||
If a `KafkaTransactionManager` bean is defined, it is automatically associated to the container factory.
|
||||
Similarly, if a `RecordFilterStrategy`, `ErrorHandler`, `AfterRollbackProcessor` or `ConsumerAwareRebalanceListener` bean is defined, it is automatically associated to the default factory.
|
||||
|
||||
Depending on the listener type, a `RecordMessageConverter` or `BatchMessageConverter` bean is associated to the default factory.
|
||||
If only a `RecordMessageConverter` bean is present for a batch listener, it is wrapped in a `BatchMessageConverter`.
|
||||
|
||||
TIP: A custom `ChainedKafkaTransactionManager` must be marked `@Primary` as it usually references the auto-configured `KafkaTransactionManager` bean.
|
||||
|
||||
|
||||
|
||||
[[messaging.kafka.streams]]
|
||||
=== Kafka Streams
|
||||
Spring for Apache Kafka provides a factory bean to create a `StreamsBuilder` object and manage the lifecycle of its streams.
|
||||
Spring Boot auto-configures the required `KafkaStreamsConfiguration` bean as long as `kafka-streams` is on the classpath and Kafka Streams is enabled via the `@EnableKafkaStreams` annotation.
|
||||
|
||||
Enabling Kafka Streams means that the application id and bootstrap servers must be set.
|
||||
The former can be configured using `spring.kafka.streams.application-id`, defaulting to `spring.application.name` if not set.
|
||||
The latter can be set globally or specifically overridden only for streams.
|
||||
|
||||
Several additional properties are available using dedicated properties; other arbitrary Kafka properties can be set using the `spring.kafka.streams.properties` namespace.
|
||||
See also <<features#messaging.kafka.additional-properties>> for more information.
|
||||
|
||||
To use the factory bean, wire `StreamsBuilder` into your `@Bean` as shown in the following example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/kafka/streams/MyKafkaStreamsConfiguration.java[]
|
||||
----
|
||||
|
||||
By default, the streams managed by the `StreamBuilder` object it creates are started automatically.
|
||||
You can customize this behavior using the configprop:spring.kafka.streams.auto-startup[] property.
|
||||
|
||||
|
||||
|
||||
[[messaging.kafka.additional-properties]]
|
||||
=== Additional Kafka Properties
|
||||
The properties supported by auto configuration are shown in <<application-properties#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 all components (producers, consumers, admins, and streams) but can be specified at the component level if you wish to use different values.
|
||||
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 directly 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:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
properties:
|
||||
"[prop.one]": "first"
|
||||
admin:
|
||||
properties:
|
||||
"[prop.two]": "second"
|
||||
consumer:
|
||||
properties:
|
||||
"[prop.three]": "third"
|
||||
producer:
|
||||
properties:
|
||||
"[prop.four]": "fourth"
|
||||
streams:
|
||||
properties:
|
||||
"[prop.five]": "fifth"
|
||||
----
|
||||
|
||||
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`, the `prop.four` producer property to `fourth` and the `prop.five` streams property to `fifth`.
|
||||
|
||||
You can also configure the Spring Kafka `JsonDeserializer` as follows:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
consumer:
|
||||
value-deserializer: "org.springframework.kafka.support.serializer.JsonDeserializer"
|
||||
properties:
|
||||
"[spring.json.value.default.type]": "com.example.Invoice"
|
||||
"[spring.json.trusted.packages]": "com.example.main,com.example.another"
|
||||
----
|
||||
|
||||
Similarly, you can disable the `JsonSerializer` default behavior of sending type information in headers:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
producer:
|
||||
value-serializer: "org.springframework.kafka.support.serializer.JsonSerializer"
|
||||
properties:
|
||||
"[spring.json.add.type.headers]": false
|
||||
----
|
||||
|
||||
IMPORTANT: Properties set in this way override any configuration item that Spring Boot explicitly supports.
|
||||
|
||||
|
||||
|
||||
[[messaging.kafka.embedded]]
|
||||
=== Testing with Embedded Kafka
|
||||
Spring for Apache Kafka provides a convenient way to test projects with an embedded Apache Kafka broker.
|
||||
To use this feature, annotate a test class with `@EmbeddedKafka` from the `spring-kafka-test` module.
|
||||
For more information, please see the Spring for Apache Kafka {spring-kafka-docs}#embedded-kafka-annotation[reference manual].
|
||||
|
||||
To make Spring Boot auto-configuration work with the aforementioned embedded Apache Kafka broker, you need to remap a system property for embedded broker addresses (populated by the `EmbeddedKafkaBroker`) into the Spring Boot configuration property for Apache Kafka.
|
||||
There are several ways to do that:
|
||||
|
||||
* Provide a system property to map embedded broker addresses into configprop:spring.kafka.bootstrap-servers[] in the test class:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/kafka/embedded/property/MyTest.java[tag=*]
|
||||
----
|
||||
|
||||
* Configure a property name on the `@EmbeddedKafka` annotation:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/messaging/kafka/embedded/annotation/MyTest.java[]
|
||||
----
|
||||
|
||||
* Use a placeholder in configuration properties:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
kafka:
|
||||
bootstrap-servers: "${spring.embedded.kafka.brokers}"
|
||||
----
|
||||
@@ -0,0 +1,86 @@
|
||||
[[messaging.rsocket]]
|
||||
== RSocket
|
||||
https://rsocket.io[RSocket] is a binary protocol for use on byte stream transports.
|
||||
It enables symmetric interaction models via async message passing over a single connection.
|
||||
|
||||
|
||||
The `spring-messaging` module of the Spring Framework provides support for RSocket requesters and responders, both on the client and on the server side.
|
||||
See the {spring-framework-docs}/web-reactive.html#rsocket-spring[RSocket section] of the Spring Framework reference for more details, including an overview of the RSocket protocol.
|
||||
|
||||
|
||||
|
||||
[[messaging.rsocket.strategies-auto-configuration]]
|
||||
=== RSocket Strategies Auto-configuration
|
||||
Spring Boot auto-configures an `RSocketStrategies` bean that provides all the required infrastructure for encoding and decoding RSocket payloads.
|
||||
By default, the auto-configuration will try to configure the following (in order):
|
||||
|
||||
. https://cbor.io/[CBOR] codecs with Jackson
|
||||
. JSON codecs with Jackson
|
||||
|
||||
The `spring-boot-starter-rsocket` starter provides both dependencies.
|
||||
Check out the <<features#features.json.jackson,Jackson support section>> to know more about customization possibilities.
|
||||
|
||||
Developers can customize the `RSocketStrategies` component by creating beans that implement the `RSocketStrategiesCustomizer` interface.
|
||||
Note that their `@Order` is important, as it determines the order of codecs.
|
||||
|
||||
|
||||
|
||||
[[messaging.rsocket.server-auto-configuration]]
|
||||
=== RSocket server Auto-configuration
|
||||
Spring Boot provides RSocket server auto-configuration.
|
||||
The required dependencies are provided by the `spring-boot-starter-rsocket`.
|
||||
|
||||
Spring Boot allows exposing RSocket over WebSocket from a WebFlux server, or standing up an independent RSocket server.
|
||||
This depends on the type of application and its configuration.
|
||||
|
||||
For WebFlux application (i.e. of type `WebApplicationType.REACTIVE`), the RSocket server will be plugged into the Web Server only if the following properties match:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rsocket:
|
||||
server:
|
||||
mapping-path: "/rsocket"
|
||||
transport: "websocket"
|
||||
----
|
||||
|
||||
WARNING: Plugging RSocket into a web server is only supported with Reactor Netty, as RSocket itself is built with that library.
|
||||
|
||||
Alternatively, an RSocket TCP or websocket server is started as an independent, embedded server.
|
||||
Besides the dependency requirements, the only required configuration is to define a port for that server:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
rsocket:
|
||||
server:
|
||||
port: 9898
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[messaging.rsocket.messaging]]
|
||||
=== Spring Messaging RSocket support
|
||||
Spring Boot will auto-configure the Spring Messaging infrastructure for RSocket.
|
||||
|
||||
This means that Spring Boot will create a `RSocketMessageHandler` bean that will handle RSocket requests to your application.
|
||||
|
||||
|
||||
|
||||
[[messaging.rsocket.requester]]
|
||||
=== Calling RSocket Services with RSocketRequester
|
||||
Once the `RSocket` channel is established between server and client, any party can send or receive requests to the other.
|
||||
|
||||
As a server, you can get injected with an `RSocketRequester` instance on any handler method of an RSocket `@Controller`.
|
||||
As a client, you need to configure and establish an RSocket connection first.
|
||||
Spring Boot auto-configures an `RSocketRequester.Builder` for such cases with the expected codecs and apply any `RSocketConnectorConfigurer` bean.
|
||||
|
||||
The `RSocketRequester.Builder` instance is a prototype bean, meaning each injection point will provide you with a new instance .
|
||||
This is done on purpose since this builder is stateful and you shouldn't create requesters with different setups using the same instance.
|
||||
|
||||
The following code shows a typical example:
|
||||
|
||||
[source,java,indent=0,subs="verbatim"]
|
||||
----
|
||||
include::{docs-java}/features/rsocket//requester/MyService.java[]
|
||||
----
|
||||
@@ -0,0 +1,50 @@
|
||||
[[messaging.spring-integration]]
|
||||
== Spring Integration
|
||||
Spring Boot offers several conveniences for working with {spring-integration}[Spring Integration], including the `spring-boot-starter-integration` "`Starter`".
|
||||
Spring Integration provides abstractions over messaging and also other transports such as HTTP, TCP, and others.
|
||||
If Spring Integration is available on your classpath, it is initialized through the `@EnableIntegration` annotation.
|
||||
|
||||
Spring Integration polling logic relies <<features#features.task-execution-and-scheduling,on the auto-configured `TaskScheduler`>>.
|
||||
|
||||
Spring Boot also configures some features that are triggered by the presence of additional Spring Integration modules.
|
||||
If `spring-integration-jmx` is also on the classpath, message processing statistics are published over JMX.
|
||||
If `spring-integration-jdbc` is available, the default database schema can be created on startup, as shown in the following line:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
spring:
|
||||
integration:
|
||||
jdbc:
|
||||
initialize-schema: "always"
|
||||
----
|
||||
|
||||
If `spring-integration-rsocket` is available, developers can configure an RSocket server using `"spring.rsocket.server.*"` properties and let it use `IntegrationRSocketEndpoint` or `RSocketOutboundGateway` components to handle incoming RSocket messages.
|
||||
This infrastructure can handle Spring Integration RSocket channel adapters and `@MessageMapping` handlers (given `"spring.integration.rsocket.server.message-mapping-enabled"` is configured).
|
||||
|
||||
Spring Boot can also auto-configure an `ClientRSocketConnector` using configuration properties:
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
# Connecting to a RSocket server over TCP
|
||||
spring:
|
||||
integration:
|
||||
rsocket:
|
||||
client:
|
||||
host: "example.org"
|
||||
port: 9898
|
||||
----
|
||||
|
||||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||||
----
|
||||
# Connecting to a RSocket Server over WebSocket
|
||||
spring:
|
||||
integration:
|
||||
rsocket:
|
||||
client:
|
||||
uri: "ws://example.org"
|
||||
----
|
||||
|
||||
See the {spring-boot-autoconfigure-module-code}/integration/IntegrationAutoConfiguration.java[`IntegrationAutoConfiguration`] and {spring-boot-autoconfigure-module-code}/integration/IntegrationProperties.java[`IntegrationProperties`] classes for more details.
|
||||
|
||||
By default, if a Micrometer `meterRegistry` bean is present, Spring Integration metrics will be managed by Micrometer.
|
||||
If you wish to use legacy Spring Integration metrics, add a `DefaultMetricsFactory` bean to the application context.
|
||||
@@ -0,0 +1,16 @@
|
||||
[[features.websockets]]
|
||||
== WebSockets
|
||||
Spring Boot provides WebSockets auto-configuration for embedded Tomcat, Jetty, and Undertow.
|
||||
If you deploy a war file to a standalone container, Spring Boot assumes that the container is responsible for the configuration of its WebSocket support.
|
||||
|
||||
Spring Framework provides {spring-framework-docs}/web.html#websocket[rich WebSocket support] for MVC web applications that can be easily accessed through the `spring-boot-starter-websocket` module.
|
||||
|
||||
WebSocket support is also available for {spring-framework-docs}/web-reactive.html#webflux-websocket[reactive web applications] and requires to include the WebSocket API alongside `spring-boot-starter-webflux`:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>javax.websocket</groupId>
|
||||
<artifactId>javax.websocket-api</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
Reference in New Issue
Block a user