From e2d177e90022cb177c4af0f7e751af480efa4935 Mon Sep 17 00:00:00 2001 From: Artem Bilan Date: Wed, 6 Feb 2019 11:21:33 -0500 Subject: [PATCH] Fix "One sentence per line" in docs --- src/reference/asciidoc/aggregator.adoc | 6 ++- src/reference/asciidoc/amqp.adoc | 37 ++++++++----------- src/reference/asciidoc/changes-1.0-2.0.adoc | 6 ++- src/reference/asciidoc/changes-2.1-2.2.adoc | 2 +- src/reference/asciidoc/changes-4.1-4.2.adoc | 3 +- src/reference/asciidoc/channel-adapter.adoc | 3 +- src/reference/asciidoc/channel.adoc | 3 +- src/reference/asciidoc/codec.adoc | 4 +- src/reference/asciidoc/dsl.adoc | 2 +- src/reference/asciidoc/endpoint.adoc | 6 ++- src/reference/asciidoc/file.adoc | 6 ++- src/reference/asciidoc/filter.adoc | 3 +- src/reference/asciidoc/ftp.adoc | 18 +++++---- src/reference/asciidoc/gateway.adoc | 3 +- src/reference/asciidoc/handler-advice.adoc | 9 +++-- src/reference/asciidoc/http.adoc | 12 ++++-- src/reference/asciidoc/ip.adoc | 23 +++++++----- src/reference/asciidoc/jmx.adoc | 6 ++- src/reference/asciidoc/jpa.adoc | 10 +++-- .../asciidoc/message-publishing.adoc | 3 +- src/reference/asciidoc/message-store.adoc | 6 ++- src/reference/asciidoc/message.adoc | 3 +- src/reference/asciidoc/meta-data-store.adoc | 4 +- src/reference/asciidoc/metrics.adoc | 6 ++- src/reference/asciidoc/mongodb.adoc | 11 ++++-- src/reference/asciidoc/mqtt.adoc | 15 +++++--- src/reference/asciidoc/overview.adoc | 6 +-- src/reference/asciidoc/polling-consumer.adoc | 3 +- src/reference/asciidoc/redis.adoc | 9 +++-- src/reference/asciidoc/resequencer.adoc | 21 +++++++---- src/reference/asciidoc/router.adoc | 6 ++- src/reference/asciidoc/samples.adoc | 6 ++- src/reference/asciidoc/service-activator.adoc | 3 +- src/reference/asciidoc/sftp.adoc | 13 ++++--- src/reference/asciidoc/testing.adoc | 6 ++- src/reference/asciidoc/transactions.adoc | 3 +- src/reference/asciidoc/transformer.adoc | 7 +++- src/reference/asciidoc/web-sockets.adoc | 2 +- src/reference/asciidoc/whats-new.adoc | 7 ++-- src/reference/asciidoc/ws.adoc | 9 +++-- src/reference/asciidoc/xml.adoc | 3 +- 41 files changed, 190 insertions(+), 124 deletions(-) diff --git a/src/reference/asciidoc/aggregator.adoc b/src/reference/asciidoc/aggregator.adoc index 82c31756f3..ba41e44285 100644 --- a/src/reference/asciidoc/aggregator.adoc +++ b/src/reference/asciidoc/aggregator.adoc @@ -188,7 +188,8 @@ However if, for some reason, you need to access the full `MessageGroup`, you sho When handling potentially large groups, you should understand how these methods are invoked, because the release strategy may be invoked multiple times before the group is released. The most efficient is an implementation of `ReleaseStrategy`, because the aggregator can invoke it directly. The second most efficient is a POJO method with a `Collection>` parameter type. -The least efficient is a POJO method with a `Collection` type. The framework has to copy the payloads from the messages in the group into a new collection (and possibly attempt conversion on the payloads to `Something`) every time the release strategy is called. +The least efficient is a POJO method with a `Collection` type. +The framework has to copy the payloads from the messages in the group into a new collection (and possibly attempt conversion on the payloads to `Something`) every time the release strategy is called. Using `Collection` avoids the conversion but still requires creating the new `Collection`. For these reasons, for large groups, we recommended that you implement `ReleaseStrategy`. @@ -597,7 +598,8 @@ Since Spring Integration 2.0, you can handle the various strategies (correlation Suppose you have a legacy component that was designed to receive an array of objects. We know that the default release strategy assembles all aggregated messages in the `List`. Now we have two problems. -First, we need to extract individual messages from the list. Second, we need to extract the payload of each message and assemble the array of objects. +First, we need to extract individual messages from the list. +Second, we need to extract the payload of each message and assemble the array of objects. The following example solves both problems: ==== diff --git a/src/reference/asciidoc/amqp.adoc b/src/reference/asciidoc/amqp.adoc index 25d6125b1e..0436b3b7c3 100644 --- a/src/reference/asciidoc/amqp.adoc +++ b/src/reference/asciidoc/amqp.adoc @@ -551,16 +551,14 @@ If that is not customized at all, the default is `PERSISTENT`. Optional. <10> An expression that defines correlation data. When provided, this configures the underlying AMQP template to receive publisher confirmations. -Requires a dedicated `RabbitTemplate` and a `CachingConnectionFactory` with the `publisherConfirms` property set to -`true`. When a publisher confirmation is received and correlation data is supplied, it is written to either the -`confirm-ack-channel` or the `confirm-nack-channel`, depending on the confirmation type. The payload of the confirmation is -the correlation data, as defined by this expression. +Requires a dedicated `RabbitTemplate` and a `CachingConnectionFactory` with the `publisherConfirms` property set to `true`. +When a publisher confirmation is received and correlation data is supplied, it is written to either the `confirm-ack-channel` or the `confirm-nack-channel`, depending on the confirmation type. +The payload of the confirmation is the correlation data, as defined by this expression. The message has an 'amqp_publishConfirm' header set to `true` (`ack`) or `false` (`nack`). Examples: `headers['myCorrelationData']` and `payload`. Version 4.1 introduced the `amqp_publishConfirmNackCause` message header. It contains the `cause` of a 'nack' for a publisher confirmation. -Starting with version 4.2, if the expression resolves to a `Message` instance (such as `#this`), the message -emitted on the `ack`/`nack` channel is based on that message, with the additional header(s) added. +Starting with version 4.2, if the expression resolves to a `Message` instance (such as `#this`), the message emitted on the `ack`/`nack` channel is based on that message, with the additional header(s) added. Previously, a new message was created with the correlation data as its payload, regardless of type. Optional. <11> The channel to which positive (`ack`) publisher confirms are sent. @@ -964,28 +962,25 @@ If that is not customized, the default is `PERSISTENT`. Optional. <13> An expression that defines correlation data. When provided, this configures the underlying AMQP template to receive publisher confirmations. -Requires a dedicated `RabbitTemplate` and a `CachingConnectionFactory` with its `publisherConfirms` property set to -`true`. When a publisher confirmation is received and correlation data is supplied, the confirmation is written to either the -`confirm-ack-channel` or the `confirm-nack-channel`, depending on the confirmation type. The payload of the confirmation is -the correlation data as defined by this expression, and the message has its 'amqp_publishConfirm' header set to `true` -(`ack`) or `false` (`nack`). +Requires a dedicated `RabbitTemplate` and a `CachingConnectionFactory` with its `publisherConfirms` property set to `true`. +When a publisher confirmation is received and correlation data is supplied, the confirmation is written to either the `confirm-ack-channel` or the `confirm-nack-channel`, depending on the confirmation type. +The payload of the confirmation is the correlation data as defined by this expression, and the message has its 'amqp_publishConfirm' header set to `true` (`ack`) or `false` (`nack`). For `nack` instances, an additional header (`amqp_publishConfirmNackCause`) is provided. Examples: `headers['myCorrelationData']`, `payload`. -If the expression resolves to a `Message` instance (such as "`#this`"), the message -emitted on the `ack`/`nack` channel is based on that message, with the additional headers added. +If the expression resolves to a `Message` instance (such as "`#this`"), the message emitted on the `ack`/`nack` channel is based on that message, with the additional headers added. Optional. <14> The channel to which positive (`ack`) publisher confirmations are sent. The payload is the correlation data defined by the `confirm-correlation-expression`. Requires the underlying `AsyncRabbitTemplate` to have its `enableConfirms` property set to `true`. Optional (the default is `nullChannel`). -<15> Since version 4.2. The channel to which negative (`nack`) publisher confirmations are sent. +<15> Since version 4.2. +The channel to which negative (`nack`) publisher confirmations are sent. The payload is the correlation data defined by the `confirm-correlation-expression`. Requires the underlying `AsyncRabbitTemplate` to have its `enableConfirms` property set to `true`. Optional (the default is `nullChannel`). <16> The channel to which returned messages are sent. When provided, the underlying AMQP template is configured to return undeliverable messages to the gateway. -The message is constructed from the data received from AMQP, with the following additional headers: -`amqp_returnReplyCode`, `amqp_returnReplyText`, `amqp_returnExchange`, and `amqp_returnRoutingKey`. +The message is constructed from the data received from AMQP, with the following additional headers: `amqp_returnReplyCode`, `amqp_returnReplyText`, `amqp_returnExchange`, and `amqp_returnRoutingKey`. Requires the underlying `AsyncRabbitTemplate` to have its `mandatory` property set to `true`. Optional. <17> When set to `false`, the endpoint tries to connect to the broker during application context initialization. @@ -1391,13 +1386,11 @@ It also does not map the `deliveryMode` to the `amqp_deliveryMode` header, to av Instead, this header is mapped to `amqp_receivedDeliveryMode`, which is not mapped on output. Starting with version 4.3, patterns in the header mappings can be negated by preceding the pattern with `!`. -Negated patterns get priority, so a list such as -`STANDARD_REQUEST_HEADERS,thing1,ba*,!thing2,!thing3,qux,!thing1` does not map `thing1` -(nor `thing2` nor `thing3`). +Negated patterns get priority, so a list such as `STANDARD_REQUEST_HEADERS,thing1,ba*,!thing2,!thing3,qux,!thing1` does not map `thing1` (nor `thing2` nor `thing3`). The standard headers plus `bad` and `qux` are mapped. -IMPORTANT: If you have a user-defined header that begins with `!` that you do wish to map, you need to escape it with -`\`, as follows: `STANDARD_REQUEST_HEADERS,\!myBangHeader`. The header named `!myBangHeader` is now mapped. +IMPORTANT: If you have a user-defined header that begins with `!` that you do wish to map, you need to escape it with `\`, as follows: `STANDARD_REQUEST_HEADERS,\!myBangHeader`. +The header named `!myBangHeader` is now mapped. NOTE: Starting with _version 5.1_, the `DefaultAmqpHeaderMapper` will fall back to mapping `MessageHeaders.ID` and `MessageHeaders.TIMESTAMP` to `MessageProperties.messageId` and `MessageProperties.timestamp` respectively, if the corresponding `amqp_messageId` or `amqp_timestamp` headers are not present on outbound messages. Inbound properties will be mapped to the `amqp_*` headers as before. @@ -1407,7 +1400,7 @@ It is useful to populate the `messageId` property when message consumers are usi ==== contentType Header Unlike other headers, the `AmqpHeaders.CONTENT_TYPE` is not prefixed with `amqp_`; this allows transparent passing of the contentType header across different technologies. -E.g. an inbound HTTP message sent to a RabbitMQ queue. +For example an inbound HTTP message sent to a RabbitMQ queue. The `contentType` header is mapped to Spring AMQP's `MessageProperties.contentType` property and that is subsequently mapped to RabbitMQ's `content_type` property. diff --git a/src/reference/asciidoc/changes-1.0-2.0.adoc b/src/reference/asciidoc/changes-1.0-2.0.adoc index 21c88860a8..11df62d98d 100644 --- a/src/reference/asciidoc/changes-1.0-2.0.adoc +++ b/src/reference/asciidoc/changes-1.0-2.0.adoc @@ -118,7 +118,8 @@ See <> for more details. [[new-other]] ==== Other Additions -Spring Integration adds a number of other features. This section describes them. +Spring Integration adds a number of other features. +This section describes them. [[new-groovy]] ===== Groovy Support @@ -165,7 +166,8 @@ We have also switched our build system to http://gradle.org/[Gradle]. ==== New Spring Integration Samples With Spring Integration 2.0, we have decoupled the samples from our main release distribution. -Please read the following blog to get more information: http://blog.springsource.com/2010/09/29/new-spring-integration-samples/[New Spring Integration Samples]. We have also created many new samples, including samples for every new adapter. +Please read the following blog to get more information: http://blog.springsource.com/2010/09/29/new-spring-integration-samples/[New Spring Integration Samples]. +We have also created many new samples, including samples for every new adapter. [[new-sts]] ==== Spring Tool Suite Visual Editor for Spring Integration diff --git a/src/reference/asciidoc/changes-2.1-2.2.adoc b/src/reference/asciidoc/changes-2.1-2.2.adoc index 6949163aed..c36faeb5d3 100644 --- a/src/reference/asciidoc/changes-2.1-2.2.adoc +++ b/src/reference/asciidoc/changes-2.1-2.2.adoc @@ -50,7 +50,7 @@ Spring Integration now uses Spring 3.1. The ability to add an `` to a poller has been available for some time. However, the behavior added by this affects the entire integration flow. It did not address the ability to add (for example) retry to an individual endpoint. -The 2.2. release introduced the `` to many endpoints. +The 2.2 release introduced the `` to many endpoints. In addition, we added three standard advice classes for this purpose: diff --git a/src/reference/asciidoc/changes-4.1-4.2.adoc b/src/reference/asciidoc/changes-4.1-4.2.adoc index 3c494ad5dd..d7d4e6cc78 100644 --- a/src/reference/asciidoc/changes-4.1-4.2.adoc +++ b/src/reference/asciidoc/changes-4.1-4.2.adoc @@ -213,7 +213,8 @@ See <> for more information. ===== Conversion Errors in Message-Driven Endpoints -The `error-channel` is now used for the conversion errors. In previous versions, they caused transaction rollback and message redelivery. +The `error-channel` is now used for the conversion errors. +In previous versions, they caused transaction rollback and message redelivery. See <> and <> for more information. diff --git a/src/reference/asciidoc/channel-adapter.adoc b/src/reference/asciidoc/channel-adapter.adoc index 33c967277a..7b3c91f9da 100644 --- a/src/reference/asciidoc/channel-adapter.adoc +++ b/src/reference/asciidoc/channel-adapter.adoc @@ -147,7 +147,8 @@ If you want the script to be checked on each poll, you would need to coordinate ==== See also the `cacheSeconds` property on the `ReloadableResourceBundleExpressionSource` when using the `` sub-element. -For more information regarding expressions, see <>. For scripts, see <> and <>. +For more information regarding expressions, see <>. +For scripts, see <> and <>. IMPORTANT: The `` is endpoint starts a message flow by periodically triggering to poll some underlying `MessageSource`. Since, at the time of polling, there is no message object, expressions and scripts do not have access to a root `Message`, so there are no payload or headers properties that are available in most other messaging SpEL expressions. diff --git a/src/reference/asciidoc/channel.adoc b/src/reference/asciidoc/channel.adoc index 9da01f65a1..600a05f2c6 100644 --- a/src/reference/asciidoc/channel.adoc +++ b/src/reference/asciidoc/channel.adoc @@ -857,7 +857,8 @@ Instead, Spring Integration focuses on a single unified approach to configuring What makes certain parts of the message flow synchronous or asynchronous is the type of Message Channel that has been configured within that flow. That is one of the primary benefits of the message channel abstraction. From the inception of the framework, we have always emphasized the need and the value of the message channel as a first-class citizen of the framework. -It is not just an internal, implicit realization of the EIP pattern. It is fully exposed as a configurable component to the end user. +It is not just an internal, implicit realization of the EIP pattern. +It is fully exposed as a configurable component to the end user. So, the wire tap component is only responsible for performing the following tasks: * Intercept a message flow by tapping into a channel (for example, `channelA`) diff --git a/src/reference/asciidoc/codec.adoc b/src/reference/asciidoc/codec.adoc index 8e1742abdd..4584df561d 100644 --- a/src/reference/asciidoc/codec.adoc +++ b/src/reference/asciidoc/codec.adoc @@ -54,8 +54,8 @@ The second and third are used with the `MessageCodec`, which is initialized with By default, Kryo delegates unknown Java types to its `FieldSerializer`. Kryo also registers default serializers for each primitive type, along with `String`, `Collection`, and `Map`. -`FieldSerializer` uses reflection to navigate the object graph. A more efficient approach is to implement a custom -serializer that is aware of the object's structure and can directly serialize selected primitive fields. +`FieldSerializer` uses reflection to navigate the object graph. +A more efficient approach is to implement a custom serializer that is aware of the object's structure and can directly serialize selected primitive fields. The following example shows such a serializer: ==== diff --git a/src/reference/asciidoc/dsl.adoc b/src/reference/asciidoc/dsl.adoc index 8922f1be85..9d7700efe7 100644 --- a/src/reference/asciidoc/dsl.adoc +++ b/src/reference/asciidoc/dsl.adoc @@ -301,7 +301,7 @@ public IntegrationFlow clientTcpFlow() { } ---- -i.e. they are not merged, only the `testAdvice()` bean is used in this case. +That is they are not merged, only the `testAdvice()` bean is used in this case. [[java-dsl-transformers]] === Transformers diff --git a/src/reference/asciidoc/endpoint.adoc b/src/reference/asciidoc/endpoint.adoc index e51d6d9330..b8e7d2a348 100644 --- a/src/reference/asciidoc/endpoint.adoc +++ b/src/reference/asciidoc/endpoint.adoc @@ -149,7 +149,8 @@ The `receiveTimeout` property specifies the amount of time the poller should wai For example, consider two options that seem similar on the surface but are actually quite different: The first has an interval trigger of 5 seconds and a receive timeout of 50 milliseconds, while the second has an interval trigger of 50 milliseconds and a receive timeout of 5 seconds. The first one may receive a message up to 4950 milliseconds later than it arrived on the channel (if that message arrived immediately after one of its poll calls returned). On the other hand, the second configuration never misses a message by more than 50 milliseconds. -The difference is that the second option requires a thread to wait. However, as a result, it can respond much more quickly to arriving messages. +The difference is that the second option requires a thread to wait. +However, as a result, it can respond much more quickly to arriving messages. This technique, known as "`long polling`", can be used to emulate event-driven behavior on a polled source. A polling consumer can also delegate to a Spring `TaskExecutor`, as the following example shows: @@ -770,7 +771,8 @@ public Map getEndpointsRunningStatus(String role) <4> <3> Returns `true` if none of the endpoints in the role are running. -<4> Returns a map of `component name : running status`. The component name is usually the bean name. +<4> Returns a map of `component name : running status`. +The component name is usually the bean name. [[leadership-event-handling]] === Leadership Event Handling diff --git a/src/reference/asciidoc/file.adoc b/src/reference/asciidoc/file.adoc index 22a432cc2d..10219cca2f 100644 --- a/src/reference/asciidoc/file.adoc +++ b/src/reference/asciidoc/file.adoc @@ -264,7 +264,8 @@ Therefore, you can also leave off the `prevent-duplicates` and `ignore-hidden` a [IMPORTANT] ===== -Spring Integration 4.2 introduced the `ignore-hidden` attribute. In prior versions, hidden files were included. +Spring Integration 4.2 introduced the `ignore-hidden` attribute. +In prior versions, hidden files were included. ===== The second channel adapter example uses a custom filter, the third uses the `filename-pattern` attribute to add an `AntPathMatcher` based filter, and the fourth uses the `filename-regex` attribute to add a regular expression pattern-based filter to the `FileReadingMessageSource`. @@ -754,7 +755,8 @@ However, this can cause data loss in the event of a failure. Spring Integration provides several flushing strategies to mitigate this data loss: -* Use `flushInterval`. If a file is not written to for this period of time, it is automatically flushed. +* Use `flushInterval`. +If a file is not written to for this period of time, it is automatically flushed. This is approximate and may be up to `1.33x` this time (with an average of `1.167x`). * Send a message containing a regular expression to the message handler's `trigger` method. Files with absolute path names matching the pattern are flushed. diff --git a/src/reference/asciidoc/filter.adoc b/src/reference/asciidoc/filter.adoc index c3404994e7..de5eda140c 100644 --- a/src/reference/asciidoc/filter.adoc +++ b/src/reference/asciidoc/filter.adoc @@ -154,7 +154,8 @@ All of this is demonstrated in the following configuration example, where the ex ---- ==== -If the `ExpressionSource` bean is named `expressionSource`, you need not provide the` source` attribute on the `` element. However, in the preceding example, we show it for completeness. +If the `ExpressionSource` bean is named `expressionSource`, you need not provide the` source` attribute on the `` element. +However, in the preceding example, we show it for completeness. The 'config/integration/expressions.properties' file (or any more-specific version with a locale extension to be resolved in the typical way that resource-bundles are loaded) can contain a key/value pair, as the following example shows: diff --git a/src/reference/asciidoc/ftp.adoc b/src/reference/asciidoc/ftp.adoc index 6f472602f8..40b181b694 100644 --- a/src/reference/asciidoc/ftp.adoc +++ b/src/reference/asciidoc/ftp.adoc @@ -395,7 +395,7 @@ The job of the inbound FTP adapter consists of two tasks: . Communicate with a remote server in order to transfer files from a remote directory to a local directory. . For each transferred file, generate a message with that file as a payload and send it to the channel identified by the 'channel' attribute. -That is why they are called "'channeladapters'" rather than just "'adapters'". +That is why they are called "'channel adapters'" rather than just "'adapters'". The main job of such an adapter is to generate a message to send to a message channel. Essentially, the second task takes precedence in such a way that, if your local directory already has one or more files, it first generates messages from those. Only when all local files have been processed does it initiate the remote communication to retrieve more files. @@ -1231,11 +1231,13 @@ The new path is in the `file_renameTo` header. The `get` and `mget` commands support the `local-filename-generator-expression` attribute. It defines a SpEL expression to generate the name of local files during the transfer. -The root object of the evaluation context is the request message. The `remoteFileName` variable, which is particularly useful for `mget`, is also available -- for example, `local-filename-generator-expression="#remoteFileName.toUpperCase() + headers.something"`. +The root object of the evaluation context is the request message. + The `remoteFileName` variable, which is particularly useful for `mget`, is also available -- for example, `local-filename-generator-expression="#remoteFileName.toUpperCase() + headers.something"`. The `get` and `mget` commands support the `local-directory-expression` attribute. It defines a SpEL expression to generate the name of local directories during the transfer. -The root object of the evaluation context is the request message but. The `remoteDirectory` variable, which is particularly useful for `mget`, is also available -- for example: `local-directory-expression="'/tmp/local/' + #remoteDirectory.toUpperCase() + headers.something"`. +The root object of the evaluation context is the request message but. +The `remoteDirectory` variable, which is particularly useful for `mget`, is also available -- for example: `local-directory-expression="'/tmp/local/' + #remoteDirectory.toUpperCase() + headers.something"`. This attribute is mutually exclusive with the `local-directory` attribute. For all commands, the 'expression' property of the gateway provides the path on which the command acts. @@ -1260,11 +1262,11 @@ The payload of the message sent to the `toSplitter` channel is a list of `String If the `command-options` attribute was omitted, it holds `FileInfo` objects. It uses space-delimited options -- for example, `command-options="-1 -dirs -links"`. -Starting with version 4.2, the `GET`, `MGET`, `PUT` and `MPUT` commands support a `FileExistsMode` property (`mode` -when using the namespace support). This affects the behavior when the local file exists (`GET` and `MGET`) or the remote -file exists (`PUT` and `MPUT`). Supported modes are `REPLACE`, `APPEND`, `FAIL`, and `IGNORE`. -For backwards compatibility, the default mode for `PUT` and `MPUT` operations is `REPLACE`. For `GET` and `MGET` -operations, the default is `FAIL`. +Starting with version 4.2, the `GET`, `MGET`, `PUT` and `MPUT` commands support a `FileExistsMode` property (`mode` when using the namespace support). +This affects the behavior when the local file exists (`GET` and `MGET`) or the remote file exists (`PUT` and `MPUT`). +Supported modes are `REPLACE`, `APPEND`, `FAIL`, and `IGNORE`. +For backwards compatibility, the default mode for `PUT` and `MPUT` operations is `REPLACE`. +For `GET` and `MGET` operations, the default is `FAIL`. Starting with version 5.0, the `setWorkingDirExpression()` (`working-dir-expression` in XML) option is provided on the `FtpOutboundGateway` (`` in XML). It lets you change the client working directory at runtime. diff --git a/src/reference/asciidoc/gateway.adoc b/src/reference/asciidoc/gateway.adoc index 6c805b03aa..a33037a927 100644 --- a/src/reference/asciidoc/gateway.adoc +++ b/src/reference/asciidoc/gateway.adoc @@ -584,7 +584,8 @@ result.addCallback(new ListenableFutureCallback() { By default, the `GatewayProxyFactoryBean` uses `org.springframework.core.task.SimpleAsyncTaskExecutor` when submitting internal `AsyncInvocationTask` instances for any gateway method whose return type is a `Future`. However, the `async-executor` attribute in the `` element's configuration lets you provide a reference to any implementation of `java.util.concurrent.Executor` available within the Spring application context. -The (default) `SimpleAsyncTaskExecutor` supports both `Future` and `ListenableFuture` return types, returning `FutureTask` or `ListenableFutureTask` respectively. See <>. +The (default) `SimpleAsyncTaskExecutor` supports both `Future` and `ListenableFuture` return types, returning `FutureTask` or `ListenableFutureTask` respectively. +See <>. Even though there is a default executor, it is often useful to provide an external one so that you can identify its threads in logs (when using XML, the thread name is based on the executor's bean name), as the following example shows: ==== diff --git a/src/reference/asciidoc/handler-advice.adoc b/src/reference/asciidoc/handler-advice.adoc index fa24add673..1ff5abd2a8 100644 --- a/src/reference/asciidoc/handler-advice.adoc +++ b/src/reference/asciidoc/handler-advice.adoc @@ -62,7 +62,8 @@ The retry advice (`o.s.i.handler.advice.RequestHandlerRetryAdvice`) leverages th The core component of `spring-retry` is the `RetryTemplate`, which allows configuration of sophisticated retry scenarios, including `RetryPolicy` and `BackoffPolicy` strategies (with a number of implementations) as well as a `RecoveryCallback` strategy to determine the action to take when retries are exhausted. Stateless Retry:: -Stateless retry is the case where the retry activity is handled entirely within the advice. The thread pauses (if configured to do so) and retries the action. +Stateless retry is the case where the retry activity is handled entirely within the advice. +The thread pauses (if configured to do so) and retries the action. Stateful Retry:: Stateful retry is the case where the retry state is managed within the advice but where an exception is thrown and the caller resubmits the request. @@ -71,7 +72,8 @@ Stateful retry needs some mechanism to detect a retried submission. For more information on `spring-retry`, see https://docs.spring.io/spring-integration/api/[the project's Javadoc] and the reference documentation for http://docs.spring.io/spring-batch/reference/html/retry.html[Spring Batch], where `spring-retry` originated. -WARNING: The default back off behavior is to not back off. Retries are attempted immediately. +WARNING: The default back off behavior is to not back off. +Retries are attempted immediately. Using a back off policy that causes threads to pause between attempts may cause performance issues, including excessive memory use and thread starvation. In high-volume environments, back off policies should be used with caution. @@ -321,7 +323,8 @@ If you configure it to, say, retry only on `MyException` and your application th Since Spring Retry 1.0.3, the `BinaryExceptionClassifier` has a property called `traverseCauses` (the default is `false`). When `true`, it traverses exception causes until it finds a match or runs out of causes to traverse. + -To use this classifier for retry, use a `SimpleRetryPolicy` created with the constructor that takes the max attempts, the `Map` of `Exception` objects, and the `traverseCauses` boolean. Then you can inject this policy into the `RetryTemplate`. +To use this classifier for retry, use a `SimpleRetryPolicy` created with the constructor that takes the max attempts, the `Map` of `Exception` objects, and the `traverseCauses` boolean. +Then you can inject this policy into the `RetryTemplate`. [[circuit-breaker-advice]] ===== Circuit Breaker Advice diff --git a/src/reference/asciidoc/http.adoc b/src/reference/asciidoc/http.adoc index 23a58c9633..ad53de6eba 100644 --- a/src/reference/asciidoc/http.adoc +++ b/src/reference/asciidoc/http.adoc @@ -73,7 +73,8 @@ The following example bean defines an HTTP inbound endpoint: The `HttpRequestHandlingMessagingGateway` accepts a list of `HttpMessageConverter` instances or else relies on a default list. The converters allow customization of the mapping from `HttpServletRequest` to `Message`. -The default converters encapsulate simple strategies, which (for example) create a `String` message for a `POST` request where the content type starts with `text`. See the https://docs.spring.io/spring-integration/api/index.html[Javadoc] for full details. +The default converters encapsulate simple strategies, which (for example) create a `String` message for a `POST` request where the content type starts with `text`. +See the https://docs.spring.io/spring-integration/api/index.html[Javadoc] for full details. An additional flag (`mergeWithDefaultConverters`) can be set along with the list of custom `HttpMessageConverter` to add the default converters after the custom converters. By default, this flag is set to `false`, meaning that the custom converters replace the default list. @@ -307,7 +308,8 @@ The following example shows how to configure it on an inbound gateway: ---- ==== -Based on the preceding configuration, the namespace parser creates an instance of the `IntegrationRequestMappingHandlerMapping` (if none exists) and an `HttpRequestHandlingController` bean and associates with it an instance of http://static.springsource.org/spring-integration/api/org/springframework/integration/http/inbound/RequestMapping.html[`RequestMapping`]. This `RequestMapping` instance is, in turn, converted to the Spring MVC http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/RequestMappingInfo.html[`RequestMappingInfo`]. +Based on the preceding configuration, the namespace parser creates an instance of the `IntegrationRequestMappingHandlerMapping` (if none exists) and an `HttpRequestHandlingController` bean and associates with it an instance of http://static.springsource.org/spring-integration/api/org/springframework/integration/http/inbound/RequestMapping.html[`RequestMapping`]. +This `RequestMapping` instance is, in turn, converted to the Spring MVC http://static.springsource.org/spring/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/RequestMappingInfo.html[`RequestMappingInfo`]. The `` element provides the following attributes: @@ -405,7 +407,8 @@ Starting with version 4.2, the default response status code when no reply is rec is `500 Internal Server Error`. There are two ways to modify this behavior: -* Add a `reply-timeout-status-code-expression`. This has the same semantics as the `status-code-expression` on the inbound adapter. +* Add a `reply-timeout-status-code-expression`. +This has the same semantics as the `status-code-expression` on the inbound adapter. * Add an `error-channel` and return an appropriate message with an HTTP status code header, as the following example shows: + ==== @@ -524,7 +527,8 @@ Alternatively, you may wish to consider using JSON instead, which is enabled by ===== Beginning with Spring Integration 2.2, you can also determine the HTTP method dynamically by using SpEL and the `http-method-expression` attribute. -Note that this attribute is mutually exclusive with `http-method`. You can also use the `expected-response-type-expression` attribute instead of `expected-response-type` and provide any valid SpEL expression that determines the type of the response. +Note that this attribute is mutually exclusive with `http-method`. +You can also use the `expected-response-type-expression` attribute instead of `expected-response-type` and provide any valid SpEL expression that determines the type of the response. The following configuration example uses `expected-response-type-expression`: ==== diff --git a/src/reference/asciidoc/ip.adoc b/src/reference/asciidoc/ip.adoc index aace57ccf8..a02a5145aa 100644 --- a/src/reference/asciidoc/ip.adoc +++ b/src/reference/asciidoc/ip.adoc @@ -448,7 +448,8 @@ You can use this serializer in conjunction with a `MessageConvertingTcpMessageMa NOTE: The Jackson `ObjectMapper` cannot demarcate messages in the stream. Therefore, the `MapJsonSerializer` needs to delegate to another serializer or deserializer to handle message demarcation. -By default, a `ByteArrayLfSerializer` is used, resulting in messages with a format of `` on the wire, but you can configure it to use others instead. (The next example shows how to do so.) +By default, a `ByteArrayLfSerializer` is used, resulting in messages with a format of `` on the wire, but you can configure it to use others instead. +(The next example shows how to do so.) The final standard serializer is `org.springframework.core.serializer.DefaultSerializer`, which you can use to convert serializable objects with Java serialization. `org.springframework.core.serializer.DefaultDeserializer` is provided for inbound deserialization of streams that contain serializable objects. @@ -636,7 +637,8 @@ Beginning with version 3.0, changes to `TcpConnection` instances are reported by * `connectionId`: The connection identifier, which you can use in a message header to send data to the connection. * `connectionFactoryName`: The bean name of the connection factory to which the connection belongs. * `throwable`: The `Throwable` (for `TcpConnectionExceptionEvent` events only). -* `source`: The `TcpConnection`. You can use this, for example, to determine the remote IP Address with `getHostAddress()` (cast required). +* `source`: The `TcpConnection`. +You can use this, for example, to determine the remote IP Address with `getHostAddress()` (cast required). In addition, since version 4.0, the standard deserializers discussed in <> now emit `TcpDeserializationExceptionEvent` instances when they encounter problems while decoding the data stream. These events contain the exception, the buffer that was in the process of being built, and an offset into the buffer (if available) at the point where the exception occurred. @@ -733,7 +735,8 @@ In some cases, you may want to establish the connection in reverse, such that th This topology is supported by setting `client-mode="true"` on the inbound adapter. In this case, the connection factory must be of type `client` and must have `single-use` set to `false`. -Two additional attributes support this mechanism. `retry-interval` specifies (in milliseconds) how often the framework attempts to reconnect after a connection failure. +Two additional attributes support this mechanism. +The `retry-interval` specifies (in milliseconds) how often the framework attempts to reconnect after a connection failure. `scheduler` supplies a `TaskScheduler` to schedule the connection attempts and to test that the connection is still active. If you don't provide a scheduler, the framework's default <> bean is used. @@ -993,7 +996,8 @@ You should keep in mind some important considerations when you use a fixed threa The following does not apply if you do not use a fixed thread pool. -With NIO connections, there are three distinct task types. The I/O selector processing is performed on one dedicated thread (detecting events, accepting new connections, and dispatching the I/O read operations to other threads by using the task executor). +With NIO connections, there are three distinct task types. +The I/O selector processing is performed on one dedicated thread (detecting events, accepting new connections, and dispatching the I/O read operations to other threads by using the task executor). When an I/O reader thread (to which the read operation is dispatched) reads data, it hands off to another thread to assemble the incoming message. Large messages can take several reads to complete. These "`assembler`" threads can block while waiting for data. @@ -2107,16 +2111,15 @@ public static class Config { <2> Searches for `@MessagingGateway` interfaces. -<3> The entry point to the client-side of the flow. The calling application can use `@Autowired` for this `Gateway` bean -and invoke its method. +<3> The entry point to the client-side of the flow. +The calling application can use `@Autowired` for this `Gateway` bean and invoke its method. -<4> Outbound endpoints consist of a `MessageHandler` and a consumer that wraps it. In this scenario, the -`@ServiceActivator` configures the endpoint, according to the channel type. +<4> Outbound endpoints consist of a `MessageHandler` and a consumer that wraps it. +In this scenario, the `@ServiceActivator` configures the endpoint, according to the channel type. <5> Inbound endpoints (in the TCP/UDP module) are all message-driven and so only need to be declared as simple `@Bean` instances. -<6> This class provides a number of POJO methods for use in this sample flow (a `@Transformer` and `@ServiceActivator` -on the server side and a `@Transformer` on the client side). +<6> This class provides a number of POJO methods for use in this sample flow (a `@Transformer` and `@ServiceActivator` on the server side and a `@Transformer` on the client side). <7> The client-side connection factory. diff --git a/src/reference/asciidoc/jmx.adoc b/src/reference/asciidoc/jmx.adoc index eeb8eb60bf..ab84622718 100644 --- a/src/reference/asciidoc/jmx.adoc +++ b/src/reference/asciidoc/jmx.adoc @@ -151,7 +151,8 @@ The following example shows how to configure an attribute-polling channel adapte ==== Tree-polling Channel Adapter The tree-polling channel adapter queries the JMX MBean tree and sends a message with a payload that is the graph of objects that matches the query. -By default, the MBeans are mapped to primitives and simple objects, such as `Map`, `List`, and arrays. Doing so permits simple transformation to (for example) JSON. +By default, the MBeans are mapped to primitives and simple objects, such as `Map`, `List`, and arrays. +Doing so permits simple transformation to (for example) JSON. An MBeanServer reference is also required. However, by default, it automatically checks for a bean named `mbeanServer`, same as the notification-listening channel adapter <>. The following example shows how to configure an tree-polling channel adapter with XML: @@ -318,7 +319,8 @@ The `bean` attribute in the object names for sources and handlers takes one of t | For well known Spring Integration default components | handler/source -| None of the above. Fall back to the `toString()` method of the object being monitored (handler or source) +| None of the above. +Fall back to the `toString()` method of the object being monitored (handler or source) |=== diff --git a/src/reference/asciidoc/jpa.adoc b/src/reference/asciidoc/jpa.adoc index d7008f794f..bd758ef490 100644 --- a/src/reference/asciidoc/jpa.adoc +++ b/src/reference/asciidoc/jpa.adoc @@ -570,7 +570,9 @@ One of the things we can achieve by using native queries is to perform database Below is a small xml fragment that demonstrates the use of native query to insert values in a table. IMPORTANT: Named parameters may not be supported by your JPA provider in conjunction with native SQL queries. -While they work fine with Hibernate, OpenJPA and EclipseLink do not support them. See https://issues.apache.org/jira/browse/OPENJPA-111. Section 3.8.12 of the JPA 2.0 spec states: "`Only positional parameter binding and positional access to result items may be portably used for native queries.`" +While they work fine with Hibernate, OpenJPA and EclipseLink do not support them. +See https://issues.apache.org/jira/browse/OPENJPA-111. +Section 3.8.12 of the JPA 2.0 spec states: "`Only positional parameter binding and positional access to result items may be portably used for native queries.`" The following example configures an outbound-channel-adapter with a native query: @@ -593,7 +595,8 @@ Note that the other attributes (such as `channel` and `entity-manager`) and the ==== Using Named Queries Using named queries is similar to using <> or a <>, except that we specify a named query instead of a query. -First, we cover how to define a JPA named query. Then we cover how to declare an outbound channel adapter to work with a named query. +First, we cover how to define a JPA named query. +Then we cover how to declare an outbound channel adapter to work with a named query. If we have an entity called `Student`, we can use annotations on the `Student` class to define two named queries: `selectStudent` and `updateStudent`. The following example shows how to do so: @@ -932,7 +935,8 @@ The value is specified in milliseconds. Optional. ==== -The remaining attributes are described earlier in this chapter. See <> and <>. +The remaining attributes are described earlier in this chapter. +See <> and <>. ==== Configuring with Java Configuration diff --git a/src/reference/asciidoc/message-publishing.adoc b/src/reference/asciidoc/message-publishing.adoc index 47fab0c4cf..366be6b280 100644 --- a/src/reference/asciidoc/message-publishing.adoc +++ b/src/reference/asciidoc/message-publishing.adoc @@ -315,7 +315,8 @@ The following example shows how to an asynchronous `publishing-interceptor`: ---- ==== -Another way of handling this type of scenario is with a wire-tap. See <>. +Another way of handling this type of scenario is with a wire-tap. +See <>. [[scheduled-producer]] ==== Producing and Publishing Messages Based on a Scheduled Trigger diff --git a/src/reference/asciidoc/message-store.adoc b/src/reference/asciidoc/message-store.adoc index b9d0989ae0..4f553c11ef 100644 --- a/src/reference/asciidoc/message-store.adoc +++ b/src/reference/asciidoc/message-store.adoc @@ -62,7 +62,8 @@ Currently, they are not serializable, but, even if they were, the deserialized c Beginning with Spring Integration version 3.0, you can resolve this issue with a header enricher configured to replace these headers with a name after registering the channel with the `HeaderChannelRegistry`. -Also, consider what happens when you configure a message-flow as follows: gateway -> queue-channel (backed by a persistent Message Store) -> service-activator. That gateway creates a temporary reply channel, which is lost by the time the service-activator's poller reads from the queue. +Also, consider what happens when you configure a message-flow as follows: gateway -> queue-channel (backed by a persistent Message Store) -> service-activator. +That gateway creates a temporary reply channel, which is lost by the time the service-activator's poller reads from the queue. Again, you can use the header enricher to replace the headers with a `String` representation. For more information, see <>. @@ -105,7 +106,8 @@ This defaults to a `SimpleMessageGroupFactory`, which produces `SimpleMessageGro (`LinkedHashSet`) internal collection. Other possible options are `SYNCHRONISED_SET` and `BLOCKING_QUEUE`, where the last one can be used to reinstate the previous `SimpleMessageGroup` behavior. -Also the `PERSISTENT` option is available. See the next section for more information. +Also the `PERSISTENT` option is available. +See the next section for more information. Starting with version 5.0.1, the `LIST` option is also available for when the order and uniqueness of messages in the group does not matter. [[lazy-load-message-group]] diff --git a/src/reference/asciidoc/message.adoc b/src/reference/asciidoc/message.adoc index 8c3f99332a..88a980efd1 100644 --- a/src/reference/asciidoc/message.adoc +++ b/src/reference/asciidoc/message.adoc @@ -104,7 +104,8 @@ If the value is a `String`, it must represent a bean name or have been generated |=== Many inbound and outbound adapter implementations also provide or expect certain headers, and you can configure additional user-defined headers. -Constants for these headers can be found in those modules where such headers exist -- for example. `AmqpHeaders`, `JmsHeaders`, and so on. +Constants for these headers can be found in those modules where such headers exist -- for example. +`AmqpHeaders`, `JmsHeaders`, and so on. [[message-header-accessor]] ===== `MessageHeaderAccessor` API diff --git a/src/reference/asciidoc/meta-data-store.adoc b/src/reference/asciidoc/meta-data-store.adoc index 8389f66468..5ff969229a 100644 --- a/src/reference/asciidoc/meta-data-store.adoc +++ b/src/reference/asciidoc/meta-data-store.adoc @@ -22,8 +22,8 @@ If you need to persist metadata between application context restarts, the framew The `PropertiesPersistingMetadataStore` is backed by a properties file and a http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/util/PropertiesPersister.html[`PropertiesPersister`]. -By default, it persists only the state when the application context is closed normally. It implements `Flushable` so that you -can persist the state at will, by invoking `flush()`. +By default, it persists only the state when the application context is closed normally. +It implements `Flushable` so that you can persist the state at will, by invoking `flush()`. The following example shows how to configure a 'PropertiesPersistingMetadataStore' with XML: [source,xml] diff --git a/src/reference/asciidoc/metrics.adoc b/src/reference/asciidoc/metrics.adoc index 06dbb25688..263fe5a33e 100644 --- a/src/reference/asciidoc/metrics.adoc +++ b/src/reference/asciidoc/metrics.adoc @@ -1,7 +1,8 @@ [[metrics-management]] === Metrics and Management -This section describes how to capture metrics for Spring Integration. In recent versions, we have relied more on Micrometer (see http://micrometer.io), and we plan to use Micrometer even more in future releases. +This section describes how to capture metrics for Spring Integration. +In recent versions, we have relied more on Micrometer (see http://micrometer.io), and we plan to use Micrometer even more in future releases. [[configuring-metrics-capture]] ==== Configuring Metrics Capture @@ -213,7 +214,8 @@ The error ratio is: 1 - success ratio. [[mgmt-handler-features]] ==== MessageHandler Metric Features -These legacy metrics will be removed in a future release. See <>. +These legacy metrics will be removed in a future release. +See <>. The following table shows the statistics maintained for message handlers. Some metrics are simple counters (message count and error count), and one is an estimate of averages of send duration. diff --git a/src/reference/asciidoc/mongodb.adoc b/src/reference/asciidoc/mongodb.adoc index df767c4490..1f6dcf1dc8 100644 --- a/src/reference/asciidoc/mongodb.adoc +++ b/src/reference/asciidoc/mongodb.adoc @@ -127,7 +127,8 @@ For example, there is no ability to configure custom converters for complex doma There is also no way to provide a custom `MongoTemplate` (or `MappingMongoConverter`). To achieve these capabilities, an alternative MongoDB `MessageStore` implementation has been introduced (we describe it next). -Spring Integration 3.0 introduced the `ConfigurableMongoDbMessageStore`. It implements both the `MessageStore` and `MessageGroupStore` interfaces. +Spring Integration 3.0 introduced the `ConfigurableMongoDbMessageStore`. +It implements both the `MessageStore` and `MessageGroupStore` interfaces. This class can receive, as a constructor argument, a `MongoTemplate`, with which you can, for example, configure a custom `WriteConcern`. Another constructor requires a `MappingMongoConverter` and a `MongoDbFactory`, which lets you provide some custom conversions for `Message` instances and their properties. Note that, by default, the `ConfigurableMongoDbMessageStore` uses standard Java serialization to write and read `Message` instances to and from MongoDB (see `MongoDbMessageBytesConverter`) and relies on default values for other properties from `MongoTemplate`. @@ -226,7 +227,8 @@ As the preceding configuration shows, you configure a MongoDb inbound channel ad * `query`: A JSON query (see http://www.mongodb.org/display/DOCS/Querying[MongoDB Querying]) * `query-expression`: A SpEL expression that is evaluated to a JSON query string (as the `query` attribute above) or to an instance of `o.s.data.mongodb.core.query.Query`. Mutually exclusive with the `query` attribute. -* `entity-class`: The type of the payload object. If not supplied, a `com.mongodb.DBObject` is returned. +* `entity-class`: The type of the payload object. +If not supplied, a `com.mongodb.DBObject` is returned. * `collection-name` or `collection-name-expression`: Identifies the name of the MongoDB collection to use. * `mongodb-factory`: Reference to an instance of `o.s.data.mongodb.MongoDbFactory` * `mongo-template`: Reference to an instance of `o.s.data.mongodb.core.MongoTemplate` @@ -289,10 +291,11 @@ You can declare your poller to be transactional by using the `transactional` ele This element can reference a real transaction manager (for example, if some other part of your flow invokes JDBC). If you do not have a "`real`" transaction, you can use an instance of `o.s.i.transaction.PseudoTransactionManager`, which is an implementation of Spring's `PlatformTransactionManager` and enables the use of the transaction synchronization features of the Mongo adapter when there is no actual transaction. -IMPORTANT: Doing so does not make MongoDB itself transactional. It lets the synchronization of actions be taken before or after success (commit) or after failure (rollback). +IMPORTANT: Doing so does not make MongoDB itself transactional. +It lets the synchronization of actions be taken before or after success (commit) or after failure (rollback). Once your poller is transactional, you can set an instance of the `o.s.i.transaction.TransactionSynchronizationFactory` on the `transactional` element. -`TransactionSynchronizationFactory` creates an instance of the `TransactionSynchronization`. +A `TransactionSynchronizationFactory` creates an instance of the `TransactionSynchronization`. For your convenience, we have exposed a default SpEL-based `TransactionSynchronizationFactory` that lets you configure SpEL expressions, with their execution being coordinated (synchronized) with a transaction. Expressions for before-commit, after-commit, and after-rollback events are supported, together with a channel for each event where the evaluation result (if any) is sent. For each child element, you can specify `expression` and `channel` attributes. diff --git a/src/reference/asciidoc/mqtt.adoc b/src/reference/asciidoc/mqtt.adoc index 9d1a817a9a..9bf74289f1 100644 --- a/src/reference/asciidoc/mqtt.adoc +++ b/src/reference/asciidoc/mqtt.adoc @@ -95,7 +95,8 @@ It applies only if the channel might block (such as a bounded `QueueChannel` tha Downstream exceptions are sent to this channel, if supplied, in an `ErrorMessage`. The payload is a `MessagingException` that contains the failed message and cause. <9> The recovery interval. -It controls the interval at which the adapter attempts to reconnect after a failure. It defaults to `10000ms` (ten seconds). +It controls the interval at which the adapter attempts to reconnect after a failure. +It defaults to `10000ms` (ten seconds). ==== NOTE: Starting with version 4.1, you can omit the URL. @@ -261,18 +262,21 @@ The default `DefaultPahoMessageConverter` recognizes the following headers: * `mqtt_retained`: `true` if the message is to be retained * `mqtt_qos`: The quality of service <4> The client factory. -<5> The default quality of service. It is used if no `mqtt_qos` header is found or the `qos-expression` returns `null`. +<5> The default quality of service. +It is used if no `mqtt_qos` header is found or the `qos-expression` returns `null`. It is not used if you supply a custom `converter`. <6> An expression to evaluate to determine the qos. The default is `headers[mqtt_qos]`. -<7> The default value of the retained flag. It is used if no `mqtt_retained` header is found. +<7> The default value of the retained flag. +It is used if no `mqtt_retained` header is found. It is not used if a custom `converter` is supplied. <8> An expression to evaluate to determine the retained boolean. The default is `headers[mqtt_retained]`. <9> The default topic to which the message is sent (used if no `mqtt_topic` header is found). <10> An expression to evaluate to determine the destination topic. The default is `headers['topic']`. -<11> When `true`, the caller does not block. Rather, it waits for delivery confirmation when a message is sent. +<11> When `true`, the caller does not block. +Rather, it waits for delivery confirmation when a message is sent. The default is `false` (the send blocks until delivery is confirmed). <12> When `async` and `async-events` are both `true`, an `MqttMessageSentEvent` is emitted. It contains the message, the topic, the `messageId` generated by the client library, the `clientId`, and the `clientInstance` (incremented each time the client is connected). @@ -283,7 +287,8 @@ Note that it is possible for the `MqttMessageDeliveredEvent` to be received befo The default is `false`. ==== -NOTE: Starting with version 4.1, the URL can be omitted. Instead, the server URIs can be provided in the `serverURIs` property of the `DefaultMqttPahoClientFactory`. +NOTE: Starting with version 4.1, the URL can be omitted. +Instead, the server URIs can be provided in the `serverURIs` property of the `DefaultMqttPahoClientFactory`. This enables, for example, connection to a highly available (HA) cluster. ==== Configuring with Java Configuration diff --git a/src/reference/asciidoc/overview.adoc b/src/reference/asciidoc/overview.adoc index f8d036344e..89e2f165db 100644 --- a/src/reference/asciidoc/overview.adoc +++ b/src/reference/asciidoc/overview.adoc @@ -550,9 +550,9 @@ Each of these online schemas has a warning similar to the following: [IMPORTANT] ==== -This schema is for the 1.0 version of Spring Integration Core. We cannot update it to the current schema -because that will break any applications using 1.0.3 or lower. For subsequent versions, the unversioned -schema is resolved from the classpath and obtained from the jar. +This schema is for the 1.0 version of Spring Integration Core. +We cannot update it to the current schema because that will break any applications using 1.0.3 or lower. +For subsequent versions, the unversioned schema is resolved from the classpath and obtained from the jar. Please refer to github: https://github.com/spring-projects/spring-integration/tree/master/spring-integration-core/src/main/resources/org/springframework/integration/config diff --git a/src/reference/asciidoc/polling-consumer.adoc b/src/reference/asciidoc/polling-consumer.adoc index c8c8841342..c9dffdd13f 100644 --- a/src/reference/asciidoc/polling-consumer.adoc +++ b/src/reference/asciidoc/polling-consumer.adoc @@ -153,7 +153,8 @@ Such classes implement the following methods: * `beforeReceive(MessageSource source)` This method is called before the `MessageSource.receive()` method. -It lets you examine and reconfigure the source. Returning `false` cancels this poll (similar to the `PollSkipAdvice` mentioned earlier). +It lets you examine and reconfigure the source. +Returning `false` cancels this poll (similar to the `PollSkipAdvice` mentioned earlier). * `Message afterReceive(Message result, MessageSource source)` This method is called after the `receive()` method. diff --git a/src/reference/asciidoc/redis.adoc b/src/reference/asciidoc/redis.adoc index abcef2a574..68ecf61f30 100644 --- a/src/reference/asciidoc/redis.adoc +++ b/src/reference/asciidoc/redis.adoc @@ -220,7 +220,8 @@ These attributes are mutually exclusive. [[redis-queue-inbound-channel-adapter]] ==== Redis Queue Inbound Channel Adapter -Spring Integration 3.0 introduced a queue inbound channel adapter to "`pop`" messages from a Redis list. By default, it uses "`right pop`", but you can configure it to use "`left pop`" instead. +Spring Integration 3.0 introduced a queue inbound channel adapter to "`pop`" messages from a Redis list. +By default, it uses "`right pop`", but you can configure it to use "`left pop`" instead. The adapter is message-driven. It uses an internal listener thread and does not use a poller. @@ -273,7 +274,8 @@ Its default is `false`. It is used for the underlying listening task. It defaults to a `SimpleAsyncTaskExecutor`. <13> Specifies whether this endpoint should use "`right pop`" (when `true`) or "`left pop`" (when `false`) to read messages from the Redis list. -If `true`, the Redis List acts as a `FIFO` queue when used with a default Redis queue outbound channel adapter. Set it to `false` to use with software that writes to the list with "`right push`" or to achieve a stack-like message order. +If `true`, the Redis List acts as a `FIFO` queue when used with a default Redis queue outbound channel adapter. +Set it to `false` to use with software that writes to the list with "`right push`" or to achieve a stack-like message order. Its default is `true`. Since version 4.3. ==== @@ -541,7 +543,8 @@ You can declare your poller to be transactional by using a `transactional` eleme This element can reference a real transaction manager (for example, if some other part of your flow invokes JDBC). If you do not have a "`real`" transaction, you can use an `o.s.i.transaction.PseudoTransactionManager`, which is an implementation of Spring's `PlatformTransactionManager` and enables the use of the transaction synchronization features of the Redis adapter when there is no actual transaction. -IMPORTANT: This does not make the Redis activities themselves transactional. It lets the synchronization of actions be taken before or after success (commit) or after failure (rollback). +IMPORTANT: This does not make the Redis activities themselves transactional. +It lets the synchronization of actions be taken before or after success (commit) or after failure (rollback). Once your poller is transactional, you can set an instance of the `o.s.i.transaction.TransactionSynchronizationFactory` on the `transactional` element. `TransactionSynchronizationFactory` creates an instance of the `TransactionSynchronization`. diff --git a/src/reference/asciidoc/resequencer.adoc b/src/reference/asciidoc/resequencer.adoc index d8495b63f4..e36761492d 100644 --- a/src/reference/asciidoc/resequencer.adoc +++ b/src/reference/asciidoc/resequencer.adoc @@ -1,15 +1,18 @@ [[resequencer]] === Resequencer -The resequencer is related to the aggregator but serves a different purpose. While the aggregator combines messages, the resequencer passes messages through without changing them. +The resequencer is related to the aggregator but serves a different purpose. +While the aggregator combines messages, the resequencer passes messages through without changing them. [[resequencer-functionality]] ==== Functionality -The resequencer works in a similar way to the aggregator, in the sense that it uses the `CORRELATION_ID` to store messages in groups. he difference is that the Resequencer does not process the messages in any way. +The resequencer works in a similar way to the aggregator, in the sense that it uses the `CORRELATION_ID` to store messages in groups. +The difference is that the Resequencer does not process the messages in any way. Instead, it releases them in the order of their `SEQUENCE_NUMBER` header values. -With respect to that, you can opt to release all messages at once (after the whole sequence, according to the `SEQUENCE_SIZE`, and other possibilities) or as soon as a valid sequence is available. (We cover what we mean by "a valid sequence" later in this chapter.) +With respect to that, you can opt to release all messages at once (after the whole sequence, according to the `SEQUENCE_SIZE`, and other possibilities) or as soon as a valid sequence is available. +(We cover what we mean by "a valid sequence" later in this chapter.) IMPORTANT: The resequencer is intended to resequence relatively short sequences of messages with small gaps. If you have a large number of disjoint sequences with many gaps, you may experience performance issues. @@ -61,11 +64,14 @@ Optional. <4> The channel to which the resequencer sends the messages that timed out (if `send-partial-result-on-timeout` is set to `false`). Optional. <5> Whether to send out ordered sequences as soon as they are available or only after the whole message group arrives. -Optional. (The default is `false`.) +Optional. +(The default is `false`.) <6> A reference to a `MessageGroupStore` that can be used to store groups of messages under their correlation key until they are complete. -Optional. (The default is a volatile in-memory store.) +Optional. +(The default is a volatile in-memory store.) <7> Whether, upon the expiration of the group, the ordered group should be sent out (even if some of the messages are missing). -Optional. (The default is false.) +Optional. +(The default is false.) See <>. <8> The timeout interval to wait when sending a reply `Message` to the `output-channel` or `discard-channel`. Defaults to `-1`, which blocks indefinitely. @@ -77,7 +83,8 @@ Optional. <9> A reference to a bean that implements the message correlation (grouping) algorithm. The bean can be an implementation of the `CorrelationStrategy` interface or a POJO. In the latter case, the `correlation-strategy-method` attribute must also be defined. -Optional. (By default, the aggregator uses the `IntegrationMessageHeaderAccessor.CORRELATION_ID` header.) +Optional. +(By default, the aggregator uses the `IntegrationMessageHeaderAccessor.CORRELATION_ID` header.) <10> A method that is defined on the bean referenced by `correlation-strategy` and that implements the correlation decision algorithm. Optional, with restrictions (requires `correlation-strategy` to be present). <11> A SpEL expression representing the correlation strategy. diff --git a/src/reference/asciidoc/router.adoc b/src/reference/asciidoc/router.adoc index 810039c7f1..40206bc1fd 100644 --- a/src/reference/asciidoc/router.adoc +++ b/src/reference/asciidoc/router.adoc @@ -777,7 +777,8 @@ The following example shows a sample configuration for `ErrorMessageExceptionTyp [[router-namespace]] ==== Configuring a Generic Router -Spring Integration provides a generic router. You can use it for general-purpose routing (as opposed to the other routers provided by Spring Integration, each of which has some form of specialization). +Spring Integration provides a generic router. +You can use it for general-purpose routing (as opposed to the other routers provided by Spring Integration, each of which has some form of specialization). ===== Configuring a Content-based Router with XML @@ -1221,7 +1222,8 @@ For an arbitrary domain object, these properties are not available. For this reason, be careful when you use routing slips in conjunction with POJO methods if the result is used to determine the next path. -IMPORTANT: If a routing slip is involved in a distributed environment, we recommend not using inline expressions for the Routing Slip `path`. This recommendation applies to distributed environments such as cross-JVM applications, using a `request-reply` through a message broker (such as<> or <>), or using a persistent `MessageStore` (<>) in the integration flow. +IMPORTANT: If a routing slip is involved in a distributed environment, we recommend not using inline expressions for the Routing Slip `path`. +This recommendation applies to distributed environments such as cross-JVM applications, using a `request-reply` through a message broker (such as<> or <>), or using a persistent `MessageStore` (<>) in the integration flow. The framework uses `RoutingSlipHeaderValueMessageProcessor` to convert them to `ExpressionEvaluatingRoutingSlipRouteStrategy` objects, and they are used in the `routingSlip` message header. Since this class is not `Serializable` (it cannot be, because it depends on the `BeanFactory`), the entire `Message` becomes non-serializable and, in any distributed operation, we end up with a `NotSerializableException`. To overcome this limitation, register an `ExpressionEvaluatingRoutingSlipRouteStrategy` bean with the desired SpEL and use its bean name in the routing slip `path` configuration. diff --git a/src/reference/asciidoc/samples.adoc b/src/reference/asciidoc/samples.adoc index 8c780e2e92..c0b2c9f698 100644 --- a/src/reference/asciidoc/samples.adoc +++ b/src/reference/asciidoc/samples.adoc @@ -49,7 +49,8 @@ $ git pull === Submitting Samples or Sample Requests -You can submit both new samples and requests for samples. We greatly appreciate any effort toward improving the samples, including the sharing of good ideas. +You can submit both new samples and requests for samples. +We greatly appreciate any effort toward improving the samples, including the sharing of good ideas. [[samples-how-can-i-contribute]] ==== How Can I Contribute My Own Samples? @@ -124,7 +125,8 @@ This category targets developers and architects who have a good understanding of In other words, the emphasis of the samples in this category is business use cases and how they can be solved with a message-driven architecture and Spring Integration in particular. For example, if you want to see how a loan broker or travel agent process could be implemented and automated with Spring Integration, this is the right place to find these types of samples. -IMPORTANT: Spring Integration is a community-driven framework. Therefore community participation is IMPORTANT. +IMPORTANT: Spring Integration is a community-driven framework. +Therefore community participation is IMPORTANT. That includes samples. If you cannot find what you are looking for, let us know! diff --git a/src/reference/asciidoc/service-activator.adoc b/src/reference/asciidoc/service-activator.adoc index b0bcd255c1..43ed560671 100644 --- a/src/reference/asciidoc/service-activator.adoc +++ b/src/reference/asciidoc/service-activator.adoc @@ -160,7 +160,8 @@ If the service returns a `ListenableFuture` when this the `async` attribute i This is particularly advantageous for long-running services that use a `PollableChannel`, because the poller thread is released to perform other services within the framework. If the service completes the future with an `Exception`, normal error processing occurs. -An `ErrorMessage` is sent to the `errorChannel` message header, if present. Otherwise, an `ErrorMessage` is sent to the default `errorChannel` (if available). +An `ErrorMessage` is sent to the `errorChannel` message header, if present. +Otherwise, an `ErrorMessage` is sent to the default `errorChannel` (if available). [[service-activator-return-type]] diff --git a/src/reference/asciidoc/sftp.adoc b/src/reference/asciidoc/sftp.adoc index e7fdf6b0fd..ef77665adf 100644 --- a/src/reference/asciidoc/sftp.adoc +++ b/src/reference/asciidoc/sftp.adoc @@ -1176,7 +1176,8 @@ Using the `rm` Command The `rm` command has no options. -If the remove operation was successful, the resulting message payload is `Boolean.TRUE`. Otherwise, the message payload is `Boolean.FALSE`. +If the remove operation was successful, the resulting message payload is `Boolean.TRUE`. +Otherwise, the message payload is `Boolean.FALSE`. The `file_remoteDirectory` header holds the remote directory, and the `file_remoteFile` header holds the file name. ==== Using the `mv` Command @@ -1228,11 +1229,11 @@ The payload of the message sent to the `toSplitter` channel is a list of `String If you omitted `command-options="-1"`, the payload would be a list of `FileInfo` objects. You can provide options as a space-delimited list (for example, `command-options="-1 -dirs -links"`). -Starting with version 4.2, the `GET`, `MGET`, `PUT`, and `MPUT` commands support a `FileExistsMode` property (`mode` -when using the namespace support). This affects the behavior when the local file exists (`GET` and `MGET`) or the remote -file exists (`PUT` and `MPUT`). The supported modes are `REPLACE`, `APPEND`, `FAIL`, and `IGNORE`. -For backwards compatibility, the default mode for `PUT` and `MPUT` operations is `REPLACE`. For `GET` and `MGET` -operations, the default is `FAIL`. +Starting with version 4.2, the `GET`, `MGET`, `PUT`, and `MPUT` commands support a `FileExistsMode` property (`mode` when using the namespace support). +This affects the behavior when the local file exists (`GET` and `MGET`) or the remote file exists (`PUT` and `MPUT`). +The supported modes are `REPLACE`, `APPEND`, `FAIL`, and `IGNORE`. +For backwards compatibility, the default mode for `PUT` and `MPUT` operations is `REPLACE`. +For `GET` and `MGET` operations, the default is `FAIL`. ==== Configuring with Java Configuration diff --git a/src/reference/asciidoc/testing.adoc b/src/reference/asciidoc/testing.adoc index c0806a187a..5a8fdde1a2 100644 --- a/src/reference/asciidoc/testing.adoc +++ b/src/reference/asciidoc/testing.adoc @@ -21,7 +21,8 @@ See the documentation for those projects for further information. Thanks to the canonical implementation of the EIP in Spring Integration Framework and its first-class citizens (such as `MessageChannel`, `Endpoint` and `MessageHandler`), abstractions, and loose coupling principles, you can implement integration solutions of any complexity. With the Spring Integration API for the flow definitions, you can improve, modify or even replace some part of the flow without impacting (mostly) other components in the integration solution. Testing such an integration solution is still a challenge, both from an end-to-end approach and from an in-isolation approach. -Several existing tools can help to test or mock some integration protocols, and they work well with Spring Integration channel adapters. Examples of such tools include the following: +Several existing tools can help to test or mock some integration protocols, and they work well with Spring Integration channel adapters. +Examples of such tools include the following: * Spring `MockMVC` and its `MockRestServiceServer` can be used for testing HTTP. * Some RDBMS vendors provide embedded data bases for JDBC or JPA support. @@ -251,7 +252,8 @@ public class MyIntegrationTests { ==== The `@SpringIntegrationTest` annotation populates a `MockIntegrationContext` bean, which you can autowire to the test class to access its methods. -With the `noAutoStartup` option, the Spring Integration Test Framework prevents endpoints that are normally `autoStartup=true` from starting. The endpoints are matched to the provided patterns, which support the following simple pattern styles: `xxx*`, `*xxx`, `*xxx*`, and `xxx*yyy`. +With the `noAutoStartup` option, the Spring Integration Test Framework prevents endpoints that are normally `autoStartup=true` from starting. +The endpoints are matched to the provided patterns, which support the following simple pattern styles: `xxx*`, `*xxx`, `*xxx*`, and `xxx*yyy`. This is useful when we would like to not have real connections to the target systems from inbound channel adapters (for example an AMQP Inbound Gateway, JDBC Polling Channel Adapter, WebSocket Message Producer in client mode, and so on). diff --git a/src/reference/asciidoc/transactions.adoc b/src/reference/asciidoc/transactions.adoc index d8c4f555f5..54e45082b1 100644 --- a/src/reference/asciidoc/transactions.adoc +++ b/src/reference/asciidoc/transactions.adoc @@ -1,7 +1,8 @@ [[transactions]] == Transaction Support -This chapter covers Spring Integration's support for transactions. It covers the following topics: +This chapter covers Spring Integration's support for transactions. +It covers the following topics: * <> * <> diff --git a/src/reference/asciidoc/transformer.adoc b/src/reference/asciidoc/transformer.adoc index b00aec0717..2e91f05315 100644 --- a/src/reference/asciidoc/transformer.adoc +++ b/src/reference/asciidoc/transformer.adoc @@ -62,7 +62,8 @@ Its `requires-reply` value is `false` by default, but that can be set to `true` ==== Transformers and Spring Expression Language (SpEL) -Like routers, aggregators, and other components, as of Spring Integration 2.0, transformers can also benefit from http://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html[SpEL support] whenever transformation logic is relatively simple. The following example shows how to use a SpEL expression: +Like routers, aggregators, and other components, as of Spring Integration 2.0, transformers can also benefit from http://docs.spring.io/spring/docs/current/spring-framework-reference/html/expressions.html[SpEL support] whenever transformation logic is relatively simple. +The following example shows how to use a SpEL expression: ==== [source,xml] @@ -352,8 +353,10 @@ Note, `BoonJsonObjectMapper` was added in version 4.1. ==== If you have requirements to use both Jackson and Boon in the same application, keep in mind that, before version 3.0, the JSON transformers used only Jackson 1.x. From 4.1 on, the framework selects Jackson 2 by default, preferring it to the Boon implementation if both are on the classpath. -Jackson 1.x is no longer supported by the framework internally. However, you can still use it within your code by including the necessary library. +Jackson 1.x is no longer supported by the framework internally. +However, you can still use it within your code by including the necessary library. To avoid unexpected issues with JSON mapping features when you use annotations, you may need to apply annotations from both Jackson and Boon on domain classes, as the following example shows: + [source,java] ---- @org.codehaus.jackson.annotate.JsonIgnoreProperties(ignoreUnknown=true) diff --git a/src/reference/asciidoc/web-sockets.adoc b/src/reference/asciidoc/web-sockets.adoc index 6bcd4abb17..f1a0606141 100644 --- a/src/reference/asciidoc/web-sockets.adoc +++ b/src/reference/asciidoc/web-sockets.adoc @@ -129,7 +129,7 @@ The `WebSocketOutboundChannelAdapter`: On the client side, the `WebSocketSession` `id` message header is not required, because `ClientWebSocketContainer` deals only with a single connection and its `WebSocketSession` respectively. -To use the STOMP subprotocol, you should configure this adapter with a `StompSubProtocolHandler`. +To use the STOMP sub-protocol, you should configure this adapter with a `StompSubProtocolHandler`. Then you can send any STOMP message type to this adapter, using `StompHeaderAccessor.create(StompCommand...)` and a `MessageBuilder`, or just using a `HeaderEnricher` (see <>). The rest of this chapter covers largely additional configuration options. diff --git a/src/reference/asciidoc/whats-new.adoc b/src/reference/asciidoc/whats-new.adoc index 9b48aaf70c..a8fd06d0a5 100644 --- a/src/reference/asciidoc/whats-new.adoc +++ b/src/reference/asciidoc/whats-new.adoc @@ -100,7 +100,8 @@ See <> for more information. [[x5.1-integration-flows-generated-bean-names]] ==== Integration Flows: Generated Bean Names -Starting with version 5.0.5, generated bean names for the components in an `IntegrationFlow` include the flow bean name, followed by a dot, as a prefix. For example, if a flow bean were named `flowBean`, a generated bean might be named `flowBean.generatedBean`. +Starting with version 5.0.5, generated bean names for the components in an `IntegrationFlow` include the flow bean name, followed by a dot, as a prefix. +For example, if a flow bean were named `flowBean`, a generated bean might be named `flowBean.generatedBean`. See <> for more information. @@ -215,9 +216,9 @@ See <> and <> for more information. === JMX Changes Object name key values are now quoted if they contain any characters other than those allowed in a Java identifier (or period `.`). -e.g. `org.springframework.integration:type=MessageChannel,` `name="input:foo.myGroup.errors"`. +For example `org.springframework.integration:type=MessageChannel,` `name="input:foo.myGroup.errors"`. This has the side effect that previously "allowed" names, with such characters, will now be quoted. -e.g. `org.springframework.integration:type=MessageChannel,` `name="input#foo.myGroup.errors"`. +For example `org.springframework.integration:type=MessageChannel,` `name="input#foo.myGroup.errors"`. [[x51.-micrometer]] === Micrometer Support Changes diff --git a/src/reference/asciidoc/ws.adoc b/src/reference/asciidoc/ws.adoc index 8ddda70d7a..6e404a4fb6 100644 --- a/src/reference/asciidoc/ws.adoc +++ b/src/reference/asciidoc/ws.adoc @@ -236,10 +236,13 @@ NOTE: Rather than using the wildcard (`*`), we recommend using the following com Doing so avoids mapping `request` headers to the reply. Starting with version 4.3, you can negate patterns in the header mappings by preceding the pattern with `!`. -Negated patterns get priority, so a list such as `STANDARD_REQUEST_HEADERS,thing1,thing*,!thing2,!thing3,qux,!thing1` does not map `thing1`, `thing2`, or `thing3`. It does map the standard headers, `thing4`, and `qux`. -(Note that `thing1` is included in both non-negated and negated forms. Because negated values take precedence, `thing1` is not mapped.) +Negated patterns get priority, so a list such as `STANDARD_REQUEST_HEADERS,thing1,thing*,!thing2,!thing3,qux,!thing1` does not map `thing1`, `thing2`, or `thing3`. +It does map the standard headers, `thing4`, and `qux`. +(Note that `thing1` is included in both non-negated and negated forms. +Because negated values take precedence, `thing1` is not mapped.) -IMPORTANT: If you have a user-defined header that begins with `!` that you do wish to map, you can escape it with `\`, as follows: `STANDARD_REQUEST_HEADERS,\!myBangHeader`. `!myBangHeader` is then mapped. +IMPORTANT: If you have a user-defined header that begins with `!` that you do wish to map, you can escape it with `\`, as follows: `STANDARD_REQUEST_HEADERS,\!myBangHeader`. +A `!myBangHeader` is then mapped. Inbound SOAP headers (request headers for the inbound gateway and reply headers for the outbound gateway) are mapped as `SoapHeaderElement` objects. You can explore the contents by accessing the `Source`: diff --git a/src/reference/asciidoc/xml.adoc b/src/reference/asciidoc/xml.adoc index 5af5945549..b03bc9ec40 100644 --- a/src/reference/asciidoc/xml.adoc +++ b/src/reference/asciidoc/xml.adoc @@ -762,7 +762,8 @@ The following example defines a property and uses it with the `output-properties Starting with `version 4.2`, the `XPathMessageSplitter` exposes an `iterator` option as a `boolean` flag (defaults to `true`). This allows the "`streaming`" of split nodes in the downstream flow. With the `iterator` mode set to `true`, each node is transformed while iterating. -When `false`, all entries are first transformed, before the split nodes start being sent to the output channel. (You can think of the difference as "`transform, send, transform, send`" versus "`transform, transform, send, send`".) +When `false`, all entries are first transformed, before the split nodes start being sent to the output channel. +(You can think of the difference as "`transform, send, transform, send`" versus "`transform, transform, send, send`".) See <> for more information. [[xml-xpath-routing]]