feature/future

[Vincent Biret (baywet)]

• codegen update: future API surface
• replaces callback api surface by future API surface
• bumps minumum API level version number to 26

fixes #533
replaces the callback API surface by futures for async operations

TODO:

• update readme for new API level requirements

Here is an example of the experience it enables:
Before

final ICallback<Subscription> callback = new ICallback<Subscription> {
   @Override
   public void succes(final Subscription result) {
        System.Out.println("created " + s.id);
   }
   @Override
   public  void failure(final ClientException ex) {
   //log errror
  }
};

client.subscriptions()
    .buildRequest()
    .post(mySub, callback);

After

client.subscriptions()
    .buildRequest()
    .futurePost(mySub)
    .thenApply(s ->System.Out.println("created " + s.id))
    .get();

[Nikitha Chettiar (nikithauc)]

For my learning, why rename the HTTP request methods such as send() or post() to futureSend() or futurePost().
Is the 'future' prefix an indicator of the return type or a good practice?
Would using the HTTP request methods without the prefix be more conventional?

[Vincent Biret (baywet)]

Nikitha Chettiar (@nikithauc) thanks for reviewing the PR.
The reason why I had to set a different name is because now that those methods don't have a parameter for the callback, they conflict with the synchronous methods. I did some research to try to identify whether there was a convention like in dotnet with the "Async" suffix, but it doesn't seem to be the case. So I went with the prefix. Changing the prefix/suffix should only be a matter of a big string replace in the templates and in the "manually updated files".
Please let me know if you hear about some kind of convention for Java.

[Vincent Biret (baywet)]

as a follow up, I decided to ask the question to the java community directly, let's see what comes back https://stackoverflow.com/questions/65737878/java-naming-conventions-for-methods-returning-futures

[Michael Mainer (MIchaelMainer)]

Since we're returning a CompletableFuture, I don't think we need "future" in the method name. I do like having Async in the method name like commenter in the SO post said. But then I'm biased. We should consider keeping the sync functions and mark them as obsolete, while gaining the futures based methods. Then customers can plan on moving to the future implementation.

[Vincent Biret (baywet)]

Yeah, I'll wait a couple of more days before merging to see if anything else pops as an answer to my question on SO.
As for the sync API, I already argued with Darrel (@darrelmiller) to simply remove it as we're shipping a new major release (which would make the lib much smaller, and solve the naming issue) but he said no.

[Michael Mainer (MIchaelMainer)]

For reviewer convenience:
sdvdiff 30586eafb3ee1d77b5811285521f18a5b0e45f1c 6a5765eeecdd992e3e7dd4f8a0a252edb9440cbf

[Michael Mainer (MIchaelMainer)]

Sampled through the other generated changes. Looks good.