3.8.0 Deprecations and breaking changes

API

Vert.x 3.8 improves the asynchronous programming model by introducing the io.vertx.core.Promise interface that defines the contract for creating and completing asynchronous results. As consequence a few API have been deprecated and sometimes breaking.

Vert.x Core

Event bus acknowledged send

The EventBus#send(..., Handler<AsyncResult<Message<T>>>) and Message#reply(..., Handler<AsyncResult<Message<T>>>) methods are now deprecated. Such methods raise overloading issues in Vert.x 4 because the version returning a Future<Message<T>> would collide with the fire and forget version.

The request-response messaging pattern should now use the new request and replyAndRequest methods:

// Deprecated
eventBus.send("the-address", body, ar -> ...);

// Now you should do this
eventBus.request("the-address", body, ar -> ...);

Likewise with replies

// Deprecated
eventBus.consumer("the-address", message -> {
  message.reply(body, ar -> ...);
});

// Now you should do this
eventBus.consumer("the-address", message -> {
  message.replyAndRequest(body, ar -> ...);
});

MessageProducer send methods

The MessageProducer interface declares two send methods, such methods should be deprecated. MessageProducer#write(T) should be used instead of MessageProducer#send(T), EventBus#request(String,Object,Handler) should be used instead of MessageProducer#send(T,Handler).

MessageProducer<String> producer = eventBus.sender("the-address");

// Deprecated
producer.send("the-address");

// Now you should use
producer.write("the-address");

Likewise:

MessageProducer<String> producer = eventBus.sender("the-address");

// Deprecated
producer.send("the-address", ar -> ...);

// Now you should use
eventBus.request("the-address", ar -> ...);

Future creation and completion

It replaces the creation and completion of io.vertx.core.Future:

// Deprecated
Future<String> fut = Future.future();
vertx.setTimer(1000, id -> fut.complete("hello");
return fut;

// Now you should do this
Promise<String> promise = Promise.promise();
vertx.setTimer(1000, id -> promise.complete("hello");
return promise.future();

Creating and completing futures is deprecated in Vert.x 3.8 in favor of promises.

Verticle lifecycle

Consequently the Verticle contract has been updated to provide lifecycle method using promises. The current methods using futures remains and is deprecated. Users should instead switch to the promise version:

// Before 3.8
class MyVerticle extends AbstractVerticle {
  // Deprecated
  public void start(Future<Void> fut) {
    ...
  }
}

// After 3.8
class MyVerticle extends AbstractVerticle {
  // Now use this instead
  public void start(Promise<Void> fut) {
    ...
  }
}

Blocking tasks

Vert.x provides the executeBlocking method in a few places to execute blocking tasks where the user provides an handler that receives a future that shall be completed by the blocking task. These method signatures have been changed to use a promise instead.

// Before
vertx.executeBlocking(future -> ..., result -> ...);

// After it the same, but you can rename the name future to promise instead
vertx.executeBlocking(promise -> ..., result -> ...);

Any Future type declaration should be changed to Promise instead:

// Before
vertx.executeBlocking((Future<String> future) -> ..., result -> ...);

// After
vertx.executeBlocking((Promise<String> promise) -> ..., result -> ...);

This is a breaking change.

Future composition

Future provides one form of composition that consumes a future as input:

// Deprecated and not replaced
future.compose(res -> ..., anotherFuture);

// Instead do it with a mapping function
future.compose(res -> {
  ...
  return anotherFuture;
});

Vert.x Web

• Now the Route match failures are signaled with the appropriate status code, not always 404. Refeer to vertx-web documentation section "Route match failures"

Vert.x circuit breaker

The following methods replace Handler<Future<T>> by Handler<Promise<T>> in their signature:

• CircuitBreaker#execute
• CircuitBreaker#executeCommand
• CircuitBreaker#executeWithFallback
• CircuitBreaker#executeCommandWithFallback
• CircuitBreaker#executeAndReport
• CircuitBreaker#executeAndReportWithFallback

// Before
breaker.execute(future -> {
  ...
});

// After it the same, but you can rename the name future to promise instead
breaker.execute(promise -> {
  ...
});

Any Future type declaration should be changed to Promise instead:

// Before
breaker.execute((Future<String> future) -> {
  ...
});

// After
breaker.execute((Promise<String> promise) -> {
  ...
});

This is a breaking change.

Vert.x health checks

The following methods replace Handler<Future<T>> by Handler<Promise<T>> in their signature:

• HealthCheckHandler#register
• HealthChecks#register

HealthChecks hc = HealthChecks.create(vertx);

// Before
hc.register("my-procedure", future -> future.complete(Status.OK()));

// After is the same but renaming future to promise is more appropriate
hc.register("my-procedure", promise -> promise.complete(Status.OK()));

Any Future type declaration should be changed to Promise instead:

HealthChecks hc = HealthChecks.create(vertx);

// Before
hc.register("my-procedure", (Future<Status> future) -> future.complete(Status.OK()));

// After
hc.register("my-procedure", (Promise<Status> promise) -> promise.complete(Status.OK()));

This is a breaking change.

Vert.x Mongo Client

• RxJava and RxJava 2 API changes, some methods now return Maybe instead of Single

  • rxUpdateCollection
  • rxUpdateCollectionWithOptions
  • rxReplaceDocuments
  • rxReplaceDocumentsWithOptions
  • rxBulkWrite
  • rxBulkWriteWithOptions
  • rxRemoveDocument
  • rxRemoveDocumentWithOptions
  • rxRemoveDocuments
  • rxRemoveDocumentsWithOptions
  • rxRunCommand