Skip to content

Commit

Permalink
Document behavior on reactive tx cancellation
Browse files Browse the repository at this point in the history
Closes gh-25091
  • Loading branch information
rstoyanchev committed Jun 8, 2020
1 parent 0ccf5e1 commit 9e1121f
Show file tree
Hide file tree
Showing 2 changed files with 25 additions and 4 deletions.
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
Expand Down
20 changes: 20 additions & 0 deletions src/docs/asciidoc/data-access.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down

0 comments on commit 9e1121f

Please sign in to comment.