[concurrency-interest] More Javadoc problems

cowwoc cowwoc at bbs.darktech.org
Sat Dec 20 10:28:46 EST 2014


On 20/12/2014 7:19 AM, Doug Lea [via JSR166 Concurrency] wrote:
> 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."

Doug, the "unless" and the paragraph you referred to are very distant 
from one another. It's hard to draw the conclusion you mentioned unless 
"unless" is one sentence away from what it is referring to. I suggest 
changing:

     "If the supplied action itself encounters an exception, then the 
returned stage exceptionally completes with this exception unless this 
stage also completed exceptionally."

to:

     "If the supplied action itself encounters an exception, then the 
returned stage exceptionally completes with this exception unless this 
stage also completed exceptionally (in which case, the returned stage 
exceptionally completes with the original exception)."

> 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
> http://docs.oracle.com/javase/specs/jls/se7/html/jls-14.html#jls-14.20.2)
> 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.
>
> -Doug

I would actually love it for whenComplete() to behave like finally() 
because if it did it would throw exception2.addSuppressed(exception1) 
instead of exception1. Would it not? I think this would be a lot less 
confusing and would prevent the kind of information loss we are 
currently seeing.

In any case, It would help if the Javadoc provided this information or 
linked to a document that did. It would be great to read that 
"whenComplete" is analogous to "finally", "handle" is analogous to 
"catch" and so on. And also to read that one can use CompletionException 
to wrap checked exceptions without having to do any manual unwrapping 
later on.

PS: When is the online Javadoc updated? If you look at 
http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html#whenComplete-java.util.function.BiConsumer- 
you will notice that it doesn't contain any of this information. I'm 
guessing that it corresponds to Java 8 update 0.

Thanks,
Gili




--
View this message in context: http://jsr166-concurrency.10961.n7.nabble.com/More-Javadoc-problems-tp11669p11686.html
Sent from the JSR166 Concurrency mailing list archive at Nabble.com.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://cs.oswego.edu/pipermail/concurrency-interest/attachments/20141220/bcf0134d/attachment.html>


More information about the Concurrency-interest mailing list