Chapter 3. What’s changed in Eclipse Vert.x 4

This section explains the fundamental differences between Eclipse Vert.x 4 and 3.x releases.

3.1. Use future methods for asynchronous operations

Eclipse Vert.x 4 uses futures for asynchronous operations. Every callback method has a corresponding future method. Futures can be used to compose asynchronous operations. You can use a combination of callback and future methods to migrate callback-based applications to Eclipse Vert.x 4. However, you can also continue using callbacks for asynchronous operations.

The following example shows how a callback was used for asynchronous operations in Eclipse Vert.x 3.x releases.

WebClient client = WebClient.create(vertx);
HttpRequest request = client.get("/resource");

request.send(ar -> {
  if (ar.succeeded()) {
    HttpResponse response = ar.result();
  } else {
    Throwable error = ar.cause();
  }
});

The following example shows how to use callback and future methods together for asynchronous operations in Eclipse Vert.x 4.

WebClient client = WebClient.create(vertx);
HttpRequest request = client.get("/resource");

Future<HttpResponse> response = request.send();

response.onComplete(ar -> {
  if (ar.succeeded()) {
    HttpResponse response = ar.result();
  } else {
    Throwable failure = ar.cause();
  }
});

Error handling is better with futures. In callbacks, you have to handle failures at every stage of the composition, whereas in futures you can handle the failure once in the end. In basic applications, you may not notice distinct difference between using callbacks and futures.

The following example shows how callbacks can be used to compose two asynchronous operations. You can see that the error is handled at every composition.

client.get("/resource1").send(ar1 -> {
  if (ar1.succeeded()) {
    HttpResponse response = ar.result();
    JsonObject json = response.body();
    client.put("/resource2").sendJsonObject(ar2 -> {
      if (ar2.succeeded()) {
        // Handle final result
      } else {
        Throwable failure2 = ar.cause();
      }
    });
  } else {
    Throwable failure1 = ar.cause();
  }
});

The following example shows how callbacks and futures can be used to compose two asynchronous operations in Eclipse Vert.x 4. The error is handled only once in the end.

Future<HttpResponse> fut1 = client.get("/resource1").send();

Future<HttpResponse> fut2 = fut1.compose(response -> client.put("/resource2").sendJsonObject(response.body()));

fut2.onComplete(ar -> {
  if (ar.succeeded()) {
    // Handle final result
  } else {
    Throwable failure = ar.cause();
  }
});

3.2. No dependency on the Jackson Databind library

The JSON features in Eclipse Vert.x depend on Jackson library. Jackson Databind library enables object mapping of JSON.

In Eclipse Vert.x 4, Jackson Databind is an optional Maven dependency. If you want to use this dependency, you must explicitly add it in the classpath.

  • If you are object mapping JSON, then you must explicitly add the dependency in your project descriptor in the com.fasterxml.jackson.core:jackson-databind jar.

    <dependencies>
    ...
    <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    </dependency>
    ...
    </dependencies>

    In future, if you decide not to use object mapping of JSON, you can remove this dependency.

  • If you are not object mapping JSON, the Jackson Databind library is not required. You can run your applications without this jar.

3.3. Handling deprecations and removals

Some features and functions have been deprecated or removed in Eclipse Vert.x 4. Before you migrate your applications to Eclipse Vert.x 4, check for deprecations and removals.

  • Some APIs were deprecated in an Eclipse Vert.x 3.x release and new equivalent APIs were provided in that release.
  • The deprecated APIs have been removed in Eclipse Vert.x 4.

If your application uses a deprecated API, you should update your application to use the new API. This helps in migrating applications to the latest version of the product.

The Java compiler generates warnings when deprecated APIs are used. You can use the compiler to check for deprecated methods while migrating applications to Eclipse Vert.x 4.

The following example shows an EventBus method that was deprecated in an Eclipse Vert.x 3.x releases.

// Send was deprecated in Vert.x 3.x release
vertx.eventBus().send("some-address", "hello world", ar -> {
  // Handle response here
});

The method send(String,String,Handler<AsyncResult<Message>>) has been replaced in Eclipse Vert.x 4 with the method request(String,String,Handler<AsyncResult<Message>>).

The following example shows how to update your application to use the new method.

// New method can be used in Vert.x 3.x and Vert.x 4.x releases
vertx.eventBus().request("some-address", "hello world", ar -> {
  // Handle response here
});