Discuss how onComplete or onSuccess/onFailure can be used

[julianladisch]

Motivation:

Simplify the code by replacing onComplete + if-ar.succeeded-else with
either onComplete(res, e) or with other processing.

Avoiding onComplete + if-ar.succeeded-else results in more concise and understandable
code because it avoids the additional nesting of the if-else clause.

Extend the exampleFuture* code to discuss all possibilities how onComplete and
onSuccess/onFailure might be used.

Conformance:

• You should have signed the Eclipse Contributor Agreement as explained in https://github.com/eclipse/vert.x/blob/master/CONTRIBUTING.md
• Please also make sure you adhere to the code style guidelines: https://github.com/vert-x3/wiki/wiki/Vert.x-code-style-guidelines

[tsegismont]

Thanks @julianladisch for bringing this up.

I have reservations about this one. Invoking onSuccess and onFailure at the same place implies creating two future listeners where a single one would do the trick.

If the goal is to avoid writing the if block, then there is an onComplete overload that takes two arguments, a success and a failure handler.

We should promote the usage of this method, imo.

That doesn't mean onSucess and onFailure don't have any use case (sometimes they're convenient, like when a method returning a future needs to perform a side action when the future is completed).

[julianladisch]

@tsegismont @vietj : Thank you for pointing out that invoking onSuccess and onFailure at the same place is slightly slower and takes slightly more memory. I've adjusted the changes accordingly.
Please re-review.