Polishing some concerns and warnings

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<Message<?>>) {...}
 }
 ----
+====
 
 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<String>) {...}
 }
 ----
+====
 
 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 "`<<aggregator>>`" 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 "`<<message-store>>`" 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 "`<<aggregator-xml>>`".
 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 "`<<aggregator-config>>`").
+There is a difference between `groupTimeout` behavior and `MessageGroupStoreReaper` (see "`<<aggregator-xml>>`").
 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 "`<<aggregator-api>>`" and "`<<annotations_on_beans>>`" for more information.
 

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.

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]
 ----
 <int:publish-subscribe-channel id="pubsubChannel" apply-sequence="true"/>

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 `<request-handler-advice-chain/>` 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 <<mhac-intro, the introduction to this section>>, advice objects in a request handler advice chain are applied to just the current endpoint, not the downstream flow (if any).
+As discussed in <<message-handler-advice-chain, the introduction to this section>>, 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()`.
 

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 <<described earlier,jpa-outbound-channel-adapter-entity-class>>).
+(To perform inserts, we send JPA entities to the channel adapter, as <<jpa-outbound-channel-adapter-entity-class,described earlier>>).
 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.

src/reference/asciidoc/preface.adoc

@@ -1,6 +1,5 @@
 [[preface]]
 = Preface
-[preface]
 
 This chapter includes:
 

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>>
 * <<transaction-boundaries>>
 * <<transaction-synchronization>>
 * <<pseudo-transactions>>
 
-[[transaction-support]]
+[[understanding-transaction]]
 === Understanding Transactions in Message flows
 
 Spring Integration exposes several hooks to address the transactional needs of your message flows.

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>>
+* <<x5.1-AmqpDedicatedChannelAdvice>>
 
-<<AmqpDedicatedChannelAdvice>>
+<<x5.1-AmqpDedicatedChannelAdvice>>
 ==== `AmqpDedicatedChannelAdvice`
 
 See <<amqp-strict-ordering>>.
@@ -21,20 +21,22 @@ See <<amqp-strict-ordering>>.
 [[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>>
-* <<dispatcher-exceptions>>
-* <<global-channel-interceptors>>
-* <<objecttojsontransformer>>
-* <<integration-flows-generated-bean-names>>
+* <<x5.1-java-dsl>>
+* <<x5.1-dispatcher-exceptions>>
+* <<x5.1-global-channel-interceptors>>
+* <<x5.1-object-to-json-transformer>>
+* <<x5.1-integration-flows-generated-bean-names>>
+* <<x5.1-aggregator>>
+* <<x5.1-publisher>>
 
-[[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 "`<<json-transformers>>`" 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 "`<<java-dsl-flows>>`" 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 "`<<aggregator>>`" 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 `<int:enable-publisher>` child element on `<int:annotation-config>`.
 
 See "`<<publisher-annotation>>`" 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 "`<<amqp-message-headers>>`" for more informatio
 The `contentType` header is now correctly mapped as an entry in the general headers map.
 See "`<<amqp-content-type>>`" 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 "`<<jdbc>>`" 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.

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 <<mentioned earlier,xpath-namespace-support>>:
+The following example shows several different ways to use XPath expressions, including the options for setting the XML namespaces <<xpath-namespace-support,mentioned earlier>>:
 
 ====
 [source,xml]