Include Future Directives Examples for Java.

[felipefzdz]

This PR addresses the following directives for #20466

• future-with-directives/onComplete.rst
• future-with-directives/onSuccess.rst
• future-with-directives/completeOrRecoverWith.rst

onComplete directive passes an Scala Try to the inner route. The lack of pattern matching in Java makes pretty complex the handling of that Try. I had to use func from scala-java8-compat, that's why I've included the package import commented out. In order to create a Partial Function I've used PFBuilder from akka.japi.pf package. That class is marked as EXPERIMENTAL, so I'm not sure if this is the intended way of consuming the result of onSuccess in Java.

That example gets really deep nested. As it needs to fit in the box generated by Sphinx I had to break the lines with not the best readability.

As my previous PR, the code here has been indented with tabs. It will be reformatted whenever the Java formatter will be ready.

[akka-ci]

Can one of the repo owners verify this patch?

[ktoso]

OK TO TEST

[ktoso]

that's pretty much the reason we I'm a fan of 2 spaces formatting (and we'll soon enforce that) :-)

[felipefzdz]

I agree with you. I've updated it to 2 spaces formatting and now is much more readable :)

[ktoso]

Will review more in the morning, thanks for the PRs!

[akka-ci]

Test PASSed.

[Hawstein]

AFAIR, the time here should be '2016-2016' which stands for file-created-year to file-modified-year :)

[He-Pin]

@Hawstein That should be nice too,just not that consistent,anyway ,we have git to track.

[Hawstein]

Yep, just a little suggestion, not a big deal.

[felipefzdz]

Thanks for spotting it @Hawstein. I've updated it!

[akka-ci]

Test PASSed.

[johanandren]

Could we static import PathMatchers.* and make the path matching a single nice line?

[johanandren]

And add a comment about importing that just like the func comment.

[johanandren]

LGTM with a few nitpicks

[felipefzdz]

Thanks @johanandren. I've amended the commit with your suggestions.

[akka-ci]

Test PASSed.

[ktoso]

Thanks, excellent PR again @felipefzdz! To address your questions:

onComplete directive passes an Scala Try to the inner route. The lack of pattern matching in Java makes pretty complex the handling of that Try. I had to use func from scala-java8-compat, that's why I've included the package import commented out. In order to create a Partial Function I've used PFBuilder from akka.japi.pf package. That class is marked as EXPERIMENTAL, so I'm not sure if this is the intended way of consuming the result of onSuccess in Java.

Perhaps an interesting thing would be to add overloads in Java that handle the success/failure as 2 callbacks hm...

Yes, using the PFBuilder is OK here 👍

That example gets really deep nested. As it needs to fit in the box generated by Sphinx I had to break the lines with not the best readability.

Right, but looks pretty decent now, thanks!