Document behavior on reactive tx cancellation

Closes gh-25091

Author: rstoyanchev

spring-tx/src/main/java/org/springframework/transaction/reactive/TransactionalOperator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -38,9 +38,10 @@
  * application services utilizing this class, making calls to the low-level
  * services via an inner-class callback object.
  *
- * <p>Transactional Publishers should avoid Subscription cancellation.
- * Cancelling initiates asynchronous transaction cleanup that does not allow for
- * synchronization on completion.
+ * <p><strong>Note:</strong> Transactional Publishers should avoid Subscription
+ * cancellation. See the
+ * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/data-access.html#tx-prog-operator-cancel">Cancel Signals</a>
+ * section of the Spring Framework reference for more details.
  *
  * @author Mark Paluch
  * @author Juergen Hoeller

src/docs/asciidoc/data-access.adoc

@@ -1457,6 +1457,11 @@ programming arrangements as the following listing shows:
 	}
 ----
 
+Note that there are special considerations for the returned `Publisher` with regards to
+Reactive Streams cancellation signals. See the <<tx-prog-operator-cancel>> section under
+"Using the TransactionOperator" for more details.
+
+
 .Method visibility and `@Transactional`
 ****
 When you use proxies, you should apply the `@Transactional` annotation only to methods
@@ -2446,6 +2451,21 @@ method on the supplied `ReactiveTransaction` object, as follows:
 	})
 ----
 
+[[tx-prog-operator-cancel]]
+===== Cancel Signals
+
+In Reactive Streams, a `Subscriber` can cancel its `Subscription` and terminate its
+`Publisher`. Operators in Project Reactor, as well as in other libraries, such as `next()`,
+`take(long)`, `timeout(Duration)`, and others can issue cancellations. There is no way to
+know the reason for the cancellation, whether it is due to an error or a simply lack of
+interest to consume further, and in version 5.2 the `TransactionalOperator` defaults to
+committing the transaction on cancel. In version 5.3 this behavior will change and
+transactions will be roll back on cancel to create a reliable and deterministic outcome.
+As a result it is important to consider the operators used downstream from a transaction
+`Publisher`. In particular in the case of a `Flux` or other multi-value `Publisher`,
+the full output must be consumed to allow the transaction to complete.
+
+
 [[tx-prog-operator-settings]]
 ===== Specifying Transaction Settings