[Java][Vertx] Add option to generate methods that return Futures

[RickyRister]

Closes #21068

Added supportVertxFuture option to the java generator.

• When enabled, the api clients will, for each operation, have an additional overload of the method that returns a vertx Future instead of taking a Handler.
  • The new methods are implemented as default methods on the interface. The method creates a Promise, calls the old method with that promise as the callback, then returns the promise.future.
  • Implemented it this way in order to keep the changes minimal. This does mean the impl classes don't have the new methods that return Futures.
• When enabled, the vertx version in the generated build files will be 4.0.0 instead of 3.x.x

PR checklist

• [✓] Read the contribution guidelines.
• [✓] Pull Request title clearly describes the work in the pull request and Pull Request description provides details about how to validate the work. Missing information here may result in delayed response from the community.
• [✓] Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in Git BASH)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• [✓] File the PR against the correct branch: master (upcoming 7.x.0 minor release - breaking changes with fallbacks), 8.0.x (breaking changes without fallbacks)
• [✓] If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

@bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @martin-mfg (2023/08)

[RickyRister]

Example of output

package org.openapitools.client.api;

import org.openapitools.client.ApiClient;
import org.openapitools.client.model.Order;
import io.vertx.core.AsyncResult;
import io.vertx.core.Handler;
import io.vertx.core.Future;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonObject;

import java.util.*;

public interface StoreApi {

    void deleteOrder(@javax.annotation.Nonnull String orderId, Handler<AsyncResult<Void>> handler);

    default Future<Void> deleteOrder(@javax.annotation.Nonnull String orderId){
        Promise<Void> promise = Promise.promise();
        deleteOrder(orderId, promise);
        return promise.future();
    }

    void deleteOrder(@javax.annotation.Nonnull String orderId, ApiClient.AuthInfo authInfo, Handler<AsyncResult<Void>> handler);

    default Future<Void> deleteOrder(@javax.annotation.Nonnull String orderId, ApiClient.AuthInfo authInfo){
        Promise<Void> promise = Promise.promise();
        deleteOrder(orderId, authInfo, promise);
        return promise.future();
    }

    void getInventory(Handler<AsyncResult<Map<String, Integer>>> handler);

    default Future<Map<String, Integer>> getInventory(){
        Promise<Map<String, Integer>> promise = Promise.promise();
        getInventory(promise);
        return promise.future();
    }

    void getInventory(ApiClient.AuthInfo authInfo, Handler<AsyncResult<Map<String, Integer>>> handler);

    default Future<Map<String, Integer>> getInventory(ApiClient.AuthInfo authInfo){
        Promise<Map<String, Integer>> promise = Promise.promise();
        getInventory(authInfo, promise);
        return promise.future();
    }

    void getOrderById(@javax.annotation.Nonnull Long orderId, Handler<AsyncResult<Order>> handler);

    default Future<Order> getOrderById(@javax.annotation.Nonnull Long orderId){
        Promise<Order> promise = Promise.promise();
        getOrderById(orderId, promise);
        return promise.future();
    }

    void getOrderById(@javax.annotation.Nonnull Long orderId, ApiClient.AuthInfo authInfo, Handler<AsyncResult<Order>> handler);

    default Future<Order> getOrderById(@javax.annotation.Nonnull Long orderId, ApiClient.AuthInfo authInfo){
        Promise<Order> promise = Promise.promise();
        getOrderById(orderId, authInfo, promise);
        return promise.future();
    }

    void placeOrder(@javax.annotation.Nonnull Order order, Handler<AsyncResult<Order>> handler);

    default Future<Order> placeOrder(@javax.annotation.Nonnull Order order){
        Promise<Order> promise = Promise.promise();
        placeOrder(order, promise);
        return promise.future();
    }

    void placeOrder(@javax.annotation.Nonnull Order order, ApiClient.AuthInfo authInfo, Handler<AsyncResult<Order>> handler);

    default Future<Order> placeOrder(@javax.annotation.Nonnull Order order, ApiClient.AuthInfo authInfo){
        Promise<Order> promise = Promise.promise();
        placeOrder(order, authInfo, promise);
        return promise.future();
    }

}

[wing328]

thanks for the PR

can you please add a new config file under ./bin/config with the option enabled, generate the samples, commit the new files and update github workflow to test the output?

#21007 is a good reference PR, which has been recently merged doing the above.

[RickyRister]

While updating the github workflow, I noticed that samples/client/petstore/java/vertx-no-nullable isn't listed under the samples. Is that intentional?

[wing328]

I noticed that samples/client/petstore/java/vertx-no-nullable isn't listed under the samples. Is that intentional?

don't think. likely it's missed

please kindly add it as part of this pr when you've time

[wing328]

https://github.com/OpenAPITools/openapi-generator/actions/runs/14443852484/job/40636043682?pr=21083

please run the command twice to update the samples

[RickyRister]

I noticed that samples/client/petstore/java/vertx-no-nullable isn't listed under the samples. Is that intentional?

don't think. likely it's missed

please kindly add it as part of this pr when you've time

Wouldn't it make more sense to add it in a separate PR? Fixing the missing vertx-no-nullable samples is unrelated to adding the supportVertxFuture option, and adding the missing samples for vertx-no-nullable will cause a lot more files to be generated for this PR.

EDIT: never mind, I incorrectly thought that files were generated by the workflow.

[wing328]

ci failure not related to this change