[concurrency-interest] More Javadoc problems

Doug Lea dl at cs.oswego.edu
Sat Dec 20 07:19:02 EST 2014

On 12/19/2014 09:00 AM, cowwoc wrote:
> The Javadoc for CompletableFuture.whenComplete() reads:
> "If the supplied action itself encounters an exception, then the returned
> stage exceptionally completes with this exception unless this stage also
> completed exceptionally."

First, thanks very much to Peter Levart for suggesting how to get
the effects you wanted.

I agree that this is terse, but I don't think it is ambiguous given
the previous sentence of the javadoc, which tells you what the
"unless" is referring to:

"Returns a new CompletionStage with the same result or exception as this stage, 
that executes the given action when this stage completes."

The policy here is the same as in most other Java constructions.
The underlying notion is that a handler for one exception should
if at all possible locally arrange processing of any unrelated
exceptions it encounters. Otherwise there is no good way to
communicate them, so the usual policy is to preserve only the
outer "causal" exception. (See for example JLS "finally: specs
But when try-with-resources was introduced (which often hits
this problem), the Throwable.addSuppressed method was added to
provide a means of reporting them. As Peter pointed out, we
can't/shouldn't automate this, but it is usually a good idea.
On the other hand, as Peter noted, the "handle" method, that
allows arbitrary translations of results and/or exceptions, is
often a better fit in these cases.
(CompletionStage.whenComplete" is analogous to "finally",
CompletionStage.handle" is analogous to to "catch", and
CompletableFuture.exceptionally is a CompletableFuture-specific
simplification of "handle" that triggers only in the exception case,
otherwise preserving result.)

It might be helpful to develop a document discussing techniques
and suggested practices for dealing with exceptions in
CompletableFuture/CompletionStage designs.


More information about the Concurrency-interest mailing list