From 9a7ae3dfad8ce7ba5085f41ec38f6ef9c0ee4e22 Mon Sep 17 00:00:00 2001 From: Artem Bilan Date: Tue, 3 Jul 2018 14:46:49 -0400 Subject: [PATCH] Polishing some concerns and warnings --- src/reference/asciidoc/aggregator.adoc | 20 +++++++------ src/reference/asciidoc/amqp.adoc | 1 + src/reference/asciidoc/channel.adoc | 4 +-- src/reference/asciidoc/handler-advice.adoc | 4 +-- src/reference/asciidoc/jpa.adoc | 2 +- src/reference/asciidoc/preface.adoc | 1 - src/reference/asciidoc/transactions.adoc | 4 +-- src/reference/asciidoc/whats-new.adoc | 33 +++++++++++++--------- src/reference/asciidoc/xml.adoc | 2 +- 9 files changed, 40 insertions(+), 31 deletions(-) diff --git a/src/reference/asciidoc/aggregator.adoc b/src/reference/asciidoc/aggregator.adoc index 37a27ca7bb..34db5e67f9 100644 --- a/src/reference/asciidoc/aggregator.adoc +++ b/src/reference/asciidoc/aggregator.adoc @@ -148,6 +148,7 @@ This method is invoked after the arrival of each new message, to decide whether The following example shows how to use the `@ReleaseStrategy` annotation for a `List` of type `Message`: +==== [source,java] ---- public class MyReleaseStrategy { @@ -156,9 +157,11 @@ public class MyReleaseStrategy { public boolean canMessagesBeReleased(List>) {...} } ---- +==== The following example shows how to use the `@ReleaseStrategy` annotation for a `List` of type `String`: +==== [source,java] ---- public class MyReleaseStrategy { @@ -167,6 +170,7 @@ public class MyReleaseStrategy { public boolean canMessagesBeReleased(List) {...} } ---- +==== Based on the signatures in the preceding two examples, the POJO-based release strategy is passed a `Collection` of not-yet-released messages (if you need access to the whole `Message`) or a `Collection` of payload objects (if the type parameter is anything other than `Message`). This satisfies the majority of use cases. @@ -234,7 +238,7 @@ The following example shows how to configure an aggregator with the previous imp ---- ==== -===== CorrelationStrategy +===== `CorrelationStrategy` The `CorrelationStrategy` interface is defined as follows: @@ -266,7 +270,6 @@ Changes to groups are thread safe. A `LockRegistry` is used to obtain a lock for the resolved correlation ID. A `DefaultLockRegistry` is used by default (in-memory). For synchronizing updates across servers, where a shared `MessageGroupStore` is being used, you must configure a shared lock registry. -See "`<>`" for more information. [[aggregator-java-dsl]] ==== Configuring an Aggregator in Java DSL @@ -346,7 +349,7 @@ Optional. <6> A reference to a `MessageGroupStore` used to store groups of messages under their correlation key until they are complete. Optional. By default, it is a volatile in-memory store. -// TODO How would one change it? +See "`<>`" for more information. <7> The order of this aggregator when more than one handle is subscribed to the same `DirectChannel` (use for load-balancing purposes). Optional. <8> Indicates that expired messages should be aggregated and sent to the 'output-channel' or 'replyChannel' once their containing `MessageGroup` is expired (see https://docs.spring.io/spring-integration/api/org/springframework/integration/store/MessageGroupStore.html#expireMessageGroups-long[`MessageGroupStore.expireMessageGroups(long)`]). @@ -356,8 +359,7 @@ You can accomplish that through a Control Bus operation or, if you have a refere Otherwise, by itself, this attribute does nothing. It serves only as an indicator of whether to discard or send to the output or reply channel any messages that are still in the `MessageGroup` that is about to be expired. Optional (the default is `false`). -NOTE: This attribute might more properly be called `send-partial-result-on-timeout`, because the group may not actually expire if -`expire-groups-upon-timeout` is set to `false`. +NOTE: This attribute might more properly be called `send-partial-result-on-timeout`, because the group may not actually expire if `expire-groups-upon-timeout` is set to `false`. <9> The timeout interval to wait when sending a reply `Message` to the `output-channel` or `discard-channel`. Defaults to `-1`, which results in blocking indefinitely. It is applied only if the output channel has some 'sending' limitations, such as a `QueueChannel` with a fixed 'capacity'. @@ -608,7 +610,7 @@ In the preceding example, the root object of the SpEL evaluation context is the ====== Aggregator and Group Timeout Starting with version 4.0, two new mutually exclusive attributes have been introduced: `group-timeout` and `group-timeout-expression` (see the earlier description). -// TODO This needs a link, but I don't see a target for it. +See "`<>`". In some cases, you may need to emit the aggregator result (or discard the group) after a timeout if the `ReleaseStrategy` does not release when the current message arrives. For this purpose, the `groupTimeout` option lets scheduling the `MessageGroup` be forced to complete, as the following example shows: @@ -632,7 +634,7 @@ If the release strategy still does not release the group, it is expired. If `send-partial-result-on-expiry` is `true`, existing messages in the (partial) `MessageGroup` are released as a normal aggregator reply message to the `output-channel`. Otherwise, it is discarded. -There is a difference between `groupTimeout` behavior and `MessageGroupStoreReaper` (see "`<>`"). +There is a difference between `groupTimeout` behavior and `MessageGroupStoreReaper` (see "`<>`"). The reaper initiates forced completion for all `MessageGroup` s in the `MessageGroupStore` periodically. The `groupTimeout` does it for each `MessageGroup` individually if a new message does not arrive during the `groupTimeout`. Also, the reaper can be used to remove empty groups (empty groups are retained in order to discard late messages if `expire-groups-upon-completion` is false). @@ -642,7 +644,7 @@ Also, the reaper can be used to remove empty groups (empty groups are retained i The following example shows an aggregator configured with annotations: -=== +==== [source,java] ---- public class Waiter { @@ -680,6 +682,7 @@ The aggregator can be either referenced explicitly from XML or, if the `@Message Annotation configuration (`@Aggregator` and others) for the Aggregator component covers only simple use cases, where most default options are sufficient. If you need more control over those options when using annotation configuration, consider using a `@Bean` definition for the `AggregatingMessageHandler` and mark its `@Bean` method with `@ServiceActivator`, as the following example shows: +==== [source,java] ---- @ServiceActivator(inputChannel = "aggregatorChannel") @@ -694,6 +697,7 @@ public MessageHandler aggregator(MessageGroupStore jdbcMessageGroupStore) { return aggregator; } ---- +==== See "`<>`" and "`<>`" for more information. diff --git a/src/reference/asciidoc/amqp.adoc b/src/reference/asciidoc/amqp.adoc index 6b04a10394..703230db56 100644 --- a/src/reference/asciidoc/amqp.adoc +++ b/src/reference/asciidoc/amqp.adoc @@ -1341,6 +1341,7 @@ The `org.springframework.amqp.support.AmqpHeaders` class identifies the default * `amqp_consumerTag` * `amqp_consumerQueue` +[[header-copy-caution]] CAUTION: As mentioned earlier in this section, using a header mapping pattern of`*` is a common way to copy all headers. However, this can have some unexpected side effects, because certain RabbitMQ proprietary properties/headers are also copied. diff --git a/src/reference/asciidoc/channel.adoc b/src/reference/asciidoc/channel.adoc index b3b674e69f..af8acc9c8e 100644 --- a/src/reference/asciidoc/channel.adoc +++ b/src/reference/asciidoc/channel.adoc @@ -639,7 +639,6 @@ If you provide a resequencer or aggregator downstream from a `PublishSubscribeCh Doing so indicates that the channel should set the `sequence-size` and `sequence-number` message headers as well as the correlation ID prior to passing along the messages. For example, if there are five subscribers, the `sequence-size` would be set to `5`, and the messages would have `sequence-number` header values ranging from `1` to `5`. -<<<<<<< HEAD Alongside with the `Executor`, an `ErrorHandler` can be configured as well. By default the `PublishSubscribeChannel` uses a `MessagePublishingErrorHandler` implementation to send error to the `MessageChannel` from the `errorChannel` header or a global `errorChannel` instance. If an `Executor` is not configured, the `ErrorHandler` is ignored and exceptions are thrown directly to the caller's Thread. @@ -647,11 +646,10 @@ If an `Executor` is not configured, the `ErrorHandler` is ignored and exceptions If you are providing a _Resequencer_ or _Aggregator_ downstream from a `PublishSubscribeChannel`, then you can set the 'apply-sequence' property on the channel to `true`. That will indicate that the channel should set the sequence-size and sequence-number Message headers as well as the correlation id prior to passing the Messages along. For example, if there are 5 subscribers, the sequence-size would be set to 5, and the Messages would have sequence-number header values ranging from 1 to 5. -======= + The following example shows how to set the `apply-sequence` header to `true`: ==== ->>>>>>> Full editing pass for the Spring Integration Reference Guide [source,xml] ---- diff --git a/src/reference/asciidoc/handler-advice.adoc b/src/reference/asciidoc/handler-advice.adoc index 971a6322a0..09f2f9678f 100644 --- a/src/reference/asciidoc/handler-advice.adoc +++ b/src/reference/asciidoc/handler-advice.adoc @@ -13,7 +13,7 @@ inbound-adapter->poller->http-gateway1->http-gateway2->jdbc-outbound-adapter ==== If you configure some retry-logic into an advice chain on the poller and the call to `http-gateway2` failed because of a network glitch, the retry causes both `http-gateway1` and `http-gateway2` to be called a second time. -Similarly, after a transient failure in the jdbc-outbound-adapter, both HTTP gateways aree called a second time before again calling the `jdbc-outbound-adapter`. +Similarly, after a transient failure in the jdbc-outbound-adapter, both HTTP gateways are called a second time before again calling the `jdbc-outbound-adapter`. Spring Integration 2.2 adds the ability to add behavior to individual endpoints. This is achieved by the addition of the `` element to many endpoints. @@ -534,7 +534,7 @@ While the abstract class mentioned above is a convenience, you can add any `Advi [[handle-message-advice]] ==== Handling Message Advice -As discussed in <>, advice objects in a request handler advice chain are applied to just the current endpoint, not the downstream flow (if any). +As discussed in <>, advice objects in a request handler advice chain are applied to just the current endpoint, not the downstream flow (if any). For `MessageHandler` objects that produce a reply (such as those that extend `AbstractReplyProducingMessageHandler`), the advice is applied to an internal method: `handleRequestMessage()` (called from `MessageHandler.handleMessage()`). For other message handlers, the advice is applied to `MessageHandler.handleMessage()`. diff --git a/src/reference/asciidoc/jpa.adoc b/src/reference/asciidoc/jpa.adoc index 7bfb8d3af7..9b6f97ec20 100644 --- a/src/reference/asciidoc/jpa.adoc +++ b/src/reference/asciidoc/jpa.adoc @@ -543,7 +543,7 @@ Using native queries is similar to using JPA QL, except that the queries are nat By using native queries, we lose database vendor independence, which we get using JPA QL. One of the things we can achieve by using native queries is to perform database inserts, which is not possible with JPA QL. -(To perform inserts, we send JPA entities to the channel adapter, as <>). +(To perform inserts, we send JPA entities to the channel adapter, as <>). 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. diff --git a/src/reference/asciidoc/preface.adoc b/src/reference/asciidoc/preface.adoc index ec02fba975..3e268c8e84 100644 --- a/src/reference/asciidoc/preface.adoc +++ b/src/reference/asciidoc/preface.adoc @@ -1,6 +1,5 @@ [[preface]] = Preface -[preface] This chapter includes: diff --git a/src/reference/asciidoc/transactions.adoc b/src/reference/asciidoc/transactions.adoc index 8a4f92bfa9..bdfd978511 100644 --- a/src/reference/asciidoc/transactions.adoc +++ b/src/reference/asciidoc/transactions.adoc @@ -3,12 +3,12 @@ This chapter covers Spring Integration's support for transactions. It covers the following topics: -* <> +* <> * <> * <> * <> -[[transaction-support]] +[[understanding-transaction]] === Understanding Transactions in Message flows Spring Integration exposes several hooks to address the transactional needs of your message flows. diff --git a/src/reference/asciidoc/whats-new.adoc b/src/reference/asciidoc/whats-new.adoc index 4fade24461..0aa617c688 100644 --- a/src/reference/asciidoc/whats-new.adoc +++ b/src/reference/asciidoc/whats-new.adoc @@ -11,9 +11,9 @@ If you are interested in more details, see the Issue Tracker tickets that were r The following components are new in 5.1: -* <> +* <> -<> +<> ==== `AmqpDedicatedChannelAdvice` See <>. @@ -21,20 +21,22 @@ See <>. [[x5.1-general]] === General Changes -The following changes have been made in version 5.1: +The following general changes have been made in version 5.1: -* <> -* <> -* <> -* <> -* <> +* <> +* <> +* <> +* <> +* <> +* <> +* <> -[[java-dsl]] +[[x5.1-java-dsl]] ==== Java DSL The `IntegrationFlowContext` is now an interface and `IntegrationFlowRegistration` is an inner interface of `IntegrationFlowContext`. -[[dispatcher-exceptions]] +[[x5.1-dispatcher-exceptions]] ==== Dispatcher Exceptions Exceptions caught and re-thrown by `AbstractDispatcher` are now more consistent: @@ -49,26 +51,27 @@ Previously: * Other `RuntimeException` instances were re-thrown unchanged. * Checked exceptions were wrapped in a `MessageDeliveryException` with the `failedMessage` property set. -[[global-channel-interceptors]] +[[x5.1-global-channel-interceptors]] ==== Global Channel Interceptors Global channel interceptors now apply to dynamically registered channels, such as through the `IntegrationFlowContext` when using the Java DSL or beans that are initialized using `beanFactory.initializeBean()`. Previously, when beans were created after the application context was refreshed, interceptors were not applied. -[[objecttojsontransformer]] +[[x5.1-object-to-json-transformer]] ==== `ObjectToJsonTransformer` A new `ResultType.BYTES` mode is introduced for the `ObjectToJsonTransformer`. See "`<>`" for more information. -[[integration-flows-generated-bean-names]] +[[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`. See "`<>`" for more information. +[[x5.1-aggregator]] ==== Aggregator Changes If the `groupTimeout` is evaluated to a negative value, an aggregator now expires the group immediately. @@ -76,12 +79,14 @@ Only `null` is considered as a signal to do nothing for the current message. See "`<>`" for more information. +[[x5.1-publisher]] ==== @Publisher annotation changes Starting with version 5.1, you must explicitly turn on the `@Publisher` AOP functionality by using `@EnablePublisher` or by using the `` child element on ``. See "`<>`" for more information. +[[x5.1-amqp]] === AMQP Changes We have made `ID` and `Timestamp` header mapping changes in the `DefaultAmqpHeaderMapper`. @@ -90,12 +95,14 @@ See the note near the bottom of "`<>`" for more informatio The `contentType` header is now correctly mapped as an entry in the general headers map. See "`<>`" for more information. +[[x5.1-jdbc]] === JDBC Changes A confusing `max-rows-per-poll` property on the JDBC Inbound Channel Adapter and JDBC Outbound Gateway has been deprecated in favor of the newly introduced `max-rows` property. See "`<>`" for more information. +[[x5.1-ftp-sftp]] === FTP and SFTP Changes A `RotatingServerAdvice` is now available to poll multiple servers and directories with the inbound channel adapters. diff --git a/src/reference/asciidoc/xml.adoc b/src/reference/asciidoc/xml.adoc index 4be058dfd4..1fd5803242 100644 --- a/src/reference/asciidoc/xml.adoc +++ b/src/reference/asciidoc/xml.adoc @@ -107,7 +107,7 @@ You can define namespaces by using one of the following choices: All three options are mutually exclusive. Only one option can be set. -The following example shows several different ways to use XPath expressions, including the options for setting the XML namespaces <>: +The following example shows several different ways to use XPath expressions, including the options for setting the XML namespaces <>: ==== [source,xml]