The WriteStream<T>.write() and WriteStream<T>.end() methods are no longer fluent.

This is a breaking change. Update your applications if you have used the fluent aspect for write streams.

The MessageProducer interface does not extend the WriteStream interface.

In the previous releases of Eclipse Vert.x, the MessageProducer interface extended the WriteStream interface. The MessageProducer interface provided limited support for message back-pressure. Credit leaks would result in a reduction of credits in the message producer. If these leaks used all the credits, messages would not be sent.

However, MessageConsumer will continue to extend ReadStream. When MessageConsumer is paused and the pending message queue is full, the messages are dropped. This continues the integration with Rx generators to build message consuming pipelines.

The send methods in the MessageProducer interface have been removed.

Use the methods MessageProducer<T>.write(T) instead of MessageProducer<T>.send(T) and EventBus.request(String,Object,Handler) instead of MessageProducer.send(T,Handler).

The EventBus.send(…​, Handler<AsyncResult<Message<T>>>) and Message.reply(…​, Handler<AsyncResult<Message<T>>>) methods have been removed. These methods would have caused overloading issues in Eclipse Vert.x 4. The version of the method returning Future<Message<T>> would collide with the fire and forget version.

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

The following example shows the request and reply to a message in Eclipse Vert.x 3.x releases.

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

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

The following example shows the request and reply to a message in Eclipse Vert.x 4.

eventBus.request("the-address", body, ar -> ...);

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

From Eclipse Vert.x 4 onward, multiple handlers are supported for a future. The Future<T>.setHandler() method used to set a single handler and has been removed. Use Future<T>.onComplete(), Future<T>.onSuccess(), and Future<T>.onFailure() methods instead to call handlers on completion, success, and failure results of an action.

The following example shows how to call a handler in Eclipse Vert.x 3.x releases.

Future<String> fut = getSomeFuture();
fut.setHandler(ar -> ...);

The following example shows how to call the new Future<T>.onComplete() method in Eclipse Vert.x 4.

Future<String> fut = getSomeFuture();
fut.onComplete(ar -> ...);

In earlier releases of Eclipse Vert.x, you would use the Future.completer() method to access Handler<AsyncResult<T>>, which was associated with the Future.

In Eclipse Vert.x 4, the Future<T>.completer() method has been removed. Future<T> directly extends Handler<AsyncResult<T>>. You can access all the handler methods using the Future object. The Future object is also a handler.

The HttpClientRequest.connectionHandler() method has been removed. Use HttpClient.connectionHandler() method instead to call connection handlers for client requests in your application.

The following example shows how the HttpClientRequest.connectionHandler() method was used in Eclipse Vert.x 3.x releases.

client.request().connectionHandler(conn -> {
  // Connection related code
}).end();

The following example shows you how to use the new HttpClient.connectionHandler() method in Eclipse Vert.x 4.

client.connectionHandler(conn -> {
  // Connection related code
});

In earlier releases of Eclipse Vert.x, VerticleFactory.createVerticle() method synchronously instantiated a verticle. From Eclipse Vert.x 4 onward, the method asynchronously instantiates the verticle and returns the callback Callable<Verticle> instead of the single verticle instance. This improvement enables the application to call this method once and invoke the returned callable multiple times for creating multiple instances.

The following code shows how verticles were instantiated in Eclipse Vert.x 3.x releases.

Verticle createVerticle(String verticleName, ClassLoader classLoader) throws Exception;

The following code shows how verticles are instantiated in Eclipse Vert.x 4.

void createVerticle(String verticleName, ClassLoader classLoader, Promise<Callable<Verticle>> promise);

The VerticleFactory class has been simplified. The class does not require initial resolution of an identifier because the factory can instead use nested deployment to deploy the verticle.

If your existing applications use factories, in Eclipse Vert.x 4 you can update the code to use a callable when a promise completes or fails. The callable can be called several times.

The following example shows existing factories in an Eclipse Vert.x 3.x application.

return new MyVerticle();

The following example shows how to update existing factories to use promise in Eclipse Vert.x 4.

promise.complete(() -> new MyVerticle());

Use the Vertx.executeBlocking() method, if you want the factory to block code. When the factory receives the blocking code, it should resolve the promise and get the verticle instances from the promise.

Multi-threaded worker verticle deployment option has been removed. This feature could only be used with Eclipse Vert.x event-bus. Other Eclipse Vert.x components such as HTTP did not support the feature.

Use the unordered Vertx.executeBlocking() method to achieve the same functionality as multi-threaded worker deployment.

The Vertx.getOrCreateContext() method creates a single context for each non Eclipse Vert.x thread. The non Eclipse Vert.x threads are associated with a context the first time a context is created. In earlier releases, a new context was created each time the method was called from a non Eclipse Vert.x thread.

new Thread(() -> {
  assertSame(vertx.getOrCreateContext(), vertx.getOrCreateContext());
}).start();

This change does not affect your applications, unless your application implicitly relies on a new context to be created with each invocation.

In the following example the n blocks run concurrently as each blocking code is called on a different context.

for (int i = 0;i < n;i++) {
  vertx.executeBlocking(block, handler);
}

To get the same results in Eclipse Vert.x 4, you must update the code:

for (int i = 0;i < n;i++) {
  vertx.executeBlocking(block, false, handler);
}

The following section describes the miscellaneous updates in Eclipse Vert.x HTTP methods.

// 3.x
options.setMaxPoolSize(30); // Maximum connection is set to 30 for each endpoint

// 4.0
options.setMaxWebSockets(30); // Maximum connection is set to 30 for each endpoint

switch (method) {
  case GET:
    ...
    break;
  case OTHER:
    String s = request.getRawMethod();
    if (s.equals("PROPFIND") {
      ...
    } else ...
}

switch (method.name()) {
  case "GET":
    ...
    break;
  case "PROPFIND";
    ...
    break;
}

HttpMethod PROPFIND = HttpMethod.valueOf("PROPFIND");

if (method == HttpMethod.GET) {
  ...
} else if (method.equals(PROPFIND)) {
  ...
} else {
  ...
}

client.request(HttpMethod.OTHER, ...).setRawName("PROPFIND");

client.request(HttpMethod.valueOf("PROPFIND"), ...);

This section describes the changes in HTTP client.

The following types of Eclipse Vert.x clients are available:

HttpClientRequest request = client.get(80, "example.com", "/", response -> {
  int statusCode = response.statusCode();
  response.exceptionHandler(err -> {
    // Handle connection error, for example, connection closed
  });
  response.bodyHandler(body -> {
    // Handle body entirely
  });
});
request.exceptionHandler(err -> {
  // Handle connection error OR response error
});
request.end();

client.get(80, "example.com", "/some-uri")
  .send(ar -> {
    if (ar.suceeded()) {
      HttpResponse<Buffer> response = ar.result();
      // Handle response
    }  else {
      // Handle error
    }
  });

HttpClientRequest request = client.get(80, "example.com", "/", response -> {
  int statusCode = response.statusCode();
  response.exceptionHandler(err -> {
    // Handle connection error, for example, connection closed
  });
  response.bodyHandler(body -> {
    // Handle body entirely
  });
});
request.exceptionHandler(err -> {
  // Handle connection error OR response error
});
request.end();

client.request(HttpMethod.GET, 80, "example.com", "/", ar -> {
  if (ar.succeeded()) {
    HttpClientRequest = ar.result();
    request.send(ar2 -> {
      if (ar2.succeeded()) {
        HttpClientResponse = ar2.result();
        int statusCode = response.statusCode();
        response.body(ar3 -> {
          if (ar3.succeeded()) {
            Buffer body = ar3.result();
            // Handle body entirely
          } else {
            // Handle server error, for example, connection closed
          }
        });
      } else {
        // Handle server error, for example, connection closed
      }
    });
  } else {
    // Connection error, for example, invalid server or invalid SSL certificate
  }
});

Future<Buffer> fut = client.request(HttpMethod.GET, 80, "example.com", "/")
  .compose(request -> request.send().compose(response -> {
    int statusCode = response.statusCode();
    if (statusCode == 200) {
      return response.body();
    } else {
      return Future.failedFuture("Unexpectd status code");
    }
  })
});
fut.onComplete(ar -> {
  if (ar.succeeded()) {
    Buffer body = ar.result();
    // Handle body entirely
  } else {
    // Handle error
  }
});

request.end();

request.end(Buffer.buffer("hello world));

writeStream.pipeTo(request, ar -> {
  if (ar.succeeded()) {
    // Sent the stream
  }
});

// Send a request and process the response
request.onComplete(ar -> {
  if (ar.succeeded()) {
    HttpClientResponse response = ar.result();
    // Handle the response
  }
})
request.end();

// The new send method combines all the operations
request.send(ar -> {
  if (ar.succeeded()) {
    HttpClientResponse response = ar.result();
    // Handle the response
  }
}));

HttpClient client = vertx.createHttpClient(options);

    client.request(HttpMethod.GET, 8443, "localhost", "/")
      .onSuccess(request -> {
        request.onSuccess(resp -> {

        //Code to handle HTTP response
        });
      });

HttpClient client = vertx.createHttpClient(options);

    client.request(HttpMethod.GET, 8443, "localhost", "/")
      .onSuccess(request -> {
        request.response().onSuccess(resp -> {

        //Code to handle HTTP response
        });
      });

client.request(HttpMethod.GET, 8080, "example.com", "/resource", ar -> {
  if (ar.succeeded()) {
    HttpClientRequest request = ar.result();
    request.putHeader("content-type", "application/json")
    request.send(new JsonObject().put("hello", "world"))
      .onSuccess(response -> {
      //
      }).onFailure(err -> {
      //
       });
     }
})

client.request().connectionHandler(conn -> {
  // Connection related code
}).end();

client.connectionHandler(conn -> {
// Connection related code
});

client.request(HttpMethod.CONNECT, uri, ar -> {
  if (ar.succeeded()) {
    HttpClientResponse response = ar.result();
    if (response.statusCode() == 200) {
      NetSocket so = response.netSocket();
   }
  }
}).end();

client.request(HttpMethod.CONNECT, uri, ar -> {
}).netSocket(ar -> {
  if (ar.succeeded()) {
   // Got a response with a 200 status code
   NetSocket so = ar.result();
   // Go for tunneling
  }
}).end();

Future<HttpClientResponse> f1 = client.send(HttpMethod.GET, 8080, "localhost", "/uri", HttpHeaders.set("foo", "bar"));

MultiMap headers = MultiMap.caseInsensitiveMultiMap();

MultiMap headers = HttpHeaders.headers();

MultiMap headers = HttpHeaders.set("content-type", "application.data");

CaseInsensitiveHeaders headers = new CaseInsensitiveHeaders();

MultiMap multiMap = MultiMap#caseInsensitiveMultiMap();

MultiMap headers = HttpHeaders.headers();

client.request(HttpMethod.GET, 8080, "example.com", "/resource", ar -> {
  if (ar.succeeded()) {
    HttpClientRequest request = ar.result();
    request.putHeader("content-type", "application/json")
    request.send(new JsonObject().put("hello", "world"))
      .onSuccess(response -> {
      //
      }).onFailure(err -> {
      //
       });
     }
})

The NetServerOptions.isClientAuthRequired() method has been removed. Use the getClientAuth() == ClientAuth.REQUIRED enumerated type to check if client authentication is required.

The following example shows how to use a switch statement to check if authentication of the client is required.

switch (options.getClientAuth()) {
case REQUIRED:
// ... behavior same as in releases prior to {VertX} {v4}
break;
default:
// fallback statement...
}

The following example shows how to use the check if authentication of the client is required in Eclipse Vert.x 4.

if (options.getClientAuth() == ClientAuth.REQUIRED) {
// behavior in releases prior to {VertX} {v4}

The NetSocket.upgradeToSsl() method has been updated to use Handler<AsyncResult> instead of Handler. The handler is used to check if the channel has been successfully upgraded to SSL or TLS.

The logging classes Logger and LoggerFactory along with their methods have been deprecated. These logging classes and methods will be removed in a future release.

The Log4j 1 logger is no longer available. However, if you want to use Log4j 1 logger, it is available with SLF4J.

The WriteStreamSubscriber.onComplete() callback has been removed. This callback was invoked if WriteStream had pending streams of data to be written.

In Eclipse Vert.x 4, use the callbacks WriteStreamSubscriber.onWriteStreamEnd() and WriteStreamSubscriber.onWriteStreamError() instead. These callbacks are called after WriteStream.end() is complete.

WriteStreamSubscriber<Buffer> subscriber = writeStream.toSubscriber();

The following example shows how to create the adapter from a WriteStream in Eclipse Vert.x 3.x releases.

subscriber.onComplete(() -> {
    // Called after writeStream.end() is invoked, even if operation has not completed
});

The following examples show how to create the adapter from a WriteStream using the new callback methods in Eclipse Vert.x 4 release:

subscriber.onWriteStreamEnd(() -> {
    // Called after writeStream.end() is invoked and completes successfully
});

subscriber.onWriteStreamError(() -> {
    // Called after writeStream.end() is invoked and fails
});

The method ConfigRetriever.getConfigAsFuture() has been removed. Use the method retriever.getConfig() instead.

The following example shows how configuration was retrieved in Eclipse Vert.x 3.x releases.

Future<JsonObject> fut = ConfigRetriever. getConfigAsFuture(retriever);

The following example shows how to retrieve configuration in Eclipse Vert.x 4.

fut = retriever.getConfig();

All the methods in the JSON class that implement Jackson types have been removed. Use the following methods instead:

For example, use the following code:

In earlier releases, the Jackson core and Jackson databind dependencies were required at runtime.

From Eclipse Vert.x 4 onward, only the Jackson core dependency is required.

You will require the Jackson databind dependency only if you are object mapping JSON. In this case, you must explicitly add the dependency in your project descriptor in the com.fasterxml.jackson.core:jackson-databind jar.

The following methods are supported for the mentioned types.

The following methods are supported only with Jackson bind:

The Eclipse Vert.x JSON types implement RFC-7493. In earlier releases of Eclipse Vert.x, the implementation incorrectly used Base64 encoder instead of Base64URL. This has been fixed in Eclipse Vert.x 4, and Base64URL encoder is used in the JSON types.

If you want to continue using the Base64 encoder in Eclipse Vert.x 4, you can use the configuration flag legacy. The following example shows how to set the configuration flag in Eclipse Vert.x 4.

java -Dvertx.json.base64=legacy ...

A new utility method Json.toBase64() converts the Base64URL string to Base64. This utility can be for:

Use the following example code to convert a Base64URL to Base64 encoder.

String base64url = someJsonObject.getString("base64encodedElement")
String base64 = Json.toBase64(base64url);

The TrustOptions.toJSON method has been removed.

In earlier releases of Eclipse Vert.x, you had to specify both the UserSessionHandler and SessionHandler handlers when working in a session.

To simplify the process, in Eclipse Vert.x 4, the UserSessionHandler class has been removed and its functionality has been added in the SessionHandler class. In Eclipse Vert.x 4, to work with sessions you must specify only one handler.

The following cookie interfaces have been removed:

Use the io.vertx.core.http.Cookie interface instead.

The create methods in FaviconHandler and ErrorHandler have been updated. You must pass a Vertx instance object in the create methods. These methods access file system. Passing the Vertx object ensures consistent access to files using the 'Vertx' file system.

The following example shows how create methods were used in Eclipse Vert.x 3.x releases.

FaviconHandler.create();
ErrorHandler.create();

The following example shows how create methods should be used in Eclipse Vert.x 4.

FaviconHandler.create(vertx);
ErrorHandler.create(vertx);

Use the method TemplateEngine.unwrap() to access the template engine. You can then apply customizations and configurations to the template.

The following methods that are used to get and set the engine configurations have been deprecated. Use the TemplateEngine.unwrap() method instead.

The io.vertx.ext.web.Locale interface has been removed. Use the io.vertx.ext.web.LanguageHeader interface instead.

The RoutingContext.acceptableLocales() method has been removed. Use the RoutingContext.acceptableLanguages() method instead.

In earlier releases of Eclipse Vert.x, the Router.mountSubRouter() method incorrectly returned a Router. This has been fixed, and the method now returns a Route.

The JWTAuthHandler.create(JWTAuth authProvider, String skip) method has been removed. Use the JWTAuthHandler.create(JWTAuth authProvider) method instead.

The following example shows how JWT authentication handler was created in Eclipse Vert.x 3.x releases.

router
   // protect everything but "/excluded/path"
   .route().handler(JWTAuthHandler(jwtAuth, "/excluded/path")

The following example shows how JWT authentication handler was created in Eclipse Vert.x 4.

router
   .route("/excluded/path").handler(/* public access to "/excluded/path" */)
   // protect everything
   .route().handler(JWTAuthHandler(jwtAuth)

In Eclipse Vert.x 4, OSGi environment is no longer supported. The StaticHandler.create(String, ClassLoader) method has been removed because the method was used in the OSGi environment.

If you have used this method in your applications, then in Eclipse Vert.x 4 you can either add the resources to the application classpath or serve resources from the file system.

The sockjs.BridgeOptions class has been removed. Use the new sockjs.SockJSBridgeOptions class instead. The sockjs.SockJSBridgeOptions class contains all the options that are required to configure the event bus bridge.

There is no change in the behavior of the new class, except that the name of the data object class has changed.

In previous releases, when you used sockjs.BridgeOptions class to add new bridges, there were a lot of duplicate configurations. The new class contains all the possible common configurations, and removes duplicate configurations.

SockJSSocket no longer registers a clustered event bus consumer by default. If you want to write to the socket using the event bus, you must enable the writeHandler in SockJSHandlerOptions. When you enable the writeHandler, the event bus consumer is set to local by default.

Router router = Router.router(vertx);
SockJSHandlerOptions options = new SockJSHandlerOptions()
  .setRegisterWriteHandler(true); // enable the event bus consumer registration
SockJSHandler sockJSHandler = SockJSHandler.create(vertx, options);
router.mountSubRouter("/myapp", sockJSHandler.socketHandler(sockJSSocket -> {
  // Retrieve the writeHandlerID and store it (For example, in a local map)
  String writeHandlerID = sockJSSocket.writeHandlerID();
}));

You can configure the event bus consumer to a cluster.

SockJSHandlerOptions options = new SockJSHandlerOptions()
  .setRegisterWriteHandler(true) // enable the event bus consumer registration
  .setLocalWriteHandler(false) // register a clustered event bus consumer

The SessionHandler.setAuthProvider(AuthProvider) method has been deprecated. Use the SessionHandler.addAuthProvider() method instead. The new method allows an application to work with multiple authentication providers and link the session objects to these authentication providers.

From Eclipse Vert.x 4, OAuth2Auth.create(Vertx vertx) method requires vertx as a constructor argument. The vertx argument uses a secure non-blocking random number generator to generate nonce which ensures better security for applications.

The following methods have been updated and are now supported on polyglot environments: * UploadScalar is now a factory, use the method UploadScalar.create() instead.

In prior releases, the Eclipse Vert.x Web GraphQL handler could process its own POST requests. It did not need Eclipse Vert.x Web BodyHandler to process the requests. However, this implementation was susceptible to DDoS attacks.

From Eclipse Vert.x 4 onward, to process POST requests BodyHandler is required. You must install BodyHandler before installing Eclipse Vert.x Web GraphQL handler.

In prior releases, the following metrics were recorded as distribution summaries for sockets. From Eclipse Vert.x 4 onward, these metrics are logged as counter, which report the amount of data exchanged.

For these counters, equivalent distribution summaries have been introduced for HTTP. These summaries are used to collect information about the request and response sizes.

The following metrics have been renamed.

The vertx-web-openapi module uses RouterBuilder to build the Eclipse Vert.x Web router. This router builder is similar to the router builer OpenAPI3RouterFactory in vertx-web-api-contract module.

To start working with the vertx-web-openapi module, instantiate the RouterBuilder.

RouterBuilder.create(vertx, "petstore.yaml").onComplete(ar -> {
  if (ar.succeeded()) {
    // Spec loaded with success
    RouterBuilder routerBuilder = ar.result();
  } else {
    // Something went wrong during router builder initialization
    Throwable exception = ar.cause();
  }
});

You can also instantiate the RouterBuilder using futures.

RouterBuilder.create(vertx, "petstore.yaml")
  .onSuccess(routerBuilder -> {
    // Spec loaded with success
  })
  .onFailure(exception -> {
    // Something went wrong during router builder initialization
  });

In most cases, you can search and replace usages of old OpenAPI3RouterFactory methods with the new RouterBuilder methods. The following table lists a few examples of old and new methods.

Use the following syntax to access the parsed request parameters:

RequestParameters parameters = routingContext.get(io.vertx.ext.web.validation.ValidationHandler.REQUEST_CONTEXT_KEY);
int aParam = parameters.queryParameter("aParam").getInteger();

In Eclipse Vert.x 4, the methods RouterFactory.addSecurityHandler() and OpenAPI3RouterFactory.addSecuritySchemaScopeValidator() are no longer available.

Use the RouterBuilder.securityHandler() method instead. This method accepts io.vertx.ext.web.handler.AuthenticationHandler as an handler. The method automatically recognizes OAuth2Handler and sets up the security schema.

The new security handlers also implement the operations defined in the OpenAPI specification.

In vertx-web-openapi module, the following failure handlers are not available. You must set up failure handlers using the Router.errorHandler(int, Handler) method.

In Eclipse Vert.x 4, the OpenAPI contract is not mapped to plain old Java object (POJO). So, the additional swagger-parser dependency is no longer required. You can use the getters and resolvers to retrieve specific components of the contract.

The following example shows how to retrieve a specific component using a single operation.

JsonObject model = routerBuilder.operation("getPets").getOperationModel();

The following example shows how to retrieve the full contract.

JsonObject contract = routerBuilder.getOpenAPI().getOpenAPI();

The following example shows you how to resolve parts of the contract.

JsonObject petModel = routerBuilder.getOpenAPI().getCached(JsonPointer.from("/components/schemas/Pet"));

In the vertx-web-api-contract module, you could validate HTTP requests using HTTPRequestValidationHandler. You did not have to use OpenAPI for validations.

In Eclipse Vert.x 4, to validate HTTP requests use vertx-web-validation module. You can import this module and validate requests without using OpenAPI. Use ValidationHandler to validate requests.

The vertx-web-api-service module has been updated and can be used with the vertx-web-validation module. If you are working with vertx-web-openapi module, there is no change in the web service functionality.

However, if you do not use OpenAPI, then to use the web service module with vertx-web-validation module you must use the RouteToEBServiceHandler class.

router.get("/api/transactions")
  .handler(
    ValidationHandlerBuilder.create(schemaParser)
      .queryParameter(optionalParam("from", stringSchema()))
      .queryParameter(optionalParam("to", stringSchema()))
      .build()
  ).handler(
    RouteToEBServiceHandler.build(eventBus, "transactions.myapplication", "getTransactionsList")
  );

The vertx-web-api-service module does not support vertx-web-api-contract. So, when you upgrade to Eclipse Vert.x 4, you must migrate your Eclipse Vert.x OpenAPI applications to vertx-web-openapi module.

The following methods have been removed from the CircuitBreaker class because they cannot be used with futures.

The following create methods in service discovery that have Handler<AmqpMessage> as an argument have been removed. These methods cannot be used with futures.

The ServiceDiscovery.registerServiceImporter() and ServiceDiscovery.registerServiceExporter() methods are no longer fluent. The methods return Future<Void>.

The vertx-service-discovery-bridge-kubernetes adds the KubernetesServiceImporter discovery bridge. The bridge imports services from Kubernetes or Openshift into the Eclipse Vert.x service discovery.

From Eclipse Vert.x 4, this bridge is no longer registered automatically. Even if you have added the bridge in the classpath of your Maven project, it will not be automatically registered.

You must manually register the bridge after creating the ServiceDiscovery instance.

The following example shows you how to manually register the bridge.

JsonObject defaultConf = new JsonObject();
serviceDiscovery.registerServiceImporter(new KubernetesServiceImporter(), defaultConf);

The SecretOptions class is no longer available. Use the new PubSecKeyOptions class instead to work with a cryptographic key.

The following example shows how methods of SecretOptions class were used in Eclipse Vert.x 3.x releases.

new SecretOptions()
    .setType("HS256")
    .setSecret("password")

The following example shows how methods of PubSecKeyOptions class should be used in Eclipse Vert.x 4.

new PubSecKeyOptions()
    .setAlgorithm("HS256")
    .setSecretKey("password")

In Eclipse Vert.x 3.x, the configuration object in public secret key management assumed that:

The following example shows how to configure key pair in Eclipse Vert.x 3.x.

new PubSecKeyOptions()
  .setPublicKey(
    // remove the PEM boundaries
    pubPemString
      .replaceAll("-----BEGIN PUBLIC KEY----")
      .replaceAll("-----END PUBLIC KEY----"))
  .setSecretKey(
    // remove the PEM boundaries
    secPemString
      .replaceAll("-----BEGIN PUBLIC KEY----")
      .replaceAll("-----END PUBLIC KEY----"));

In Eclipse Vert.x 4, you must specify both the public and private key.

The following example shows how to configure key pair in Eclipse Vert.x 4.

PubSecKeyOptions pubKey =
  new PubSecKeyOptions()
    // the buffer is the exact contents of the PEM file and had boundaries included in it
    .setBuffer(pubPemString);

PubSecKeyOptions secKey =
  new PubSecKeyOptions()
    // the buffer is the exact contents of the PEM file and had boundaries included in it
    .setBuffer(secPemString);

You can now handle X509 certificates using PubSecKeyOptions.

PubSecKeyOptions x509Certificate =
  new PubSecKeyOptions()
    // the buffer is the exact contents of the PEM file and had boundaries included in it
    .setBuffer(x509PemString);

In Eclipse Vert.x 3.x, KeyStoreOptions assumes that the keystore format is jceks, and the stored password is the same as the password of the key. As jceks is a proprietary format, it is recommended to use a standard format, such as JDK, instead.

When you use KeyStoreOptions in Eclipse Vert.x 4, you can specify a store type. For example, store types such as PKCS11, PKCS12, and so on can be set. The default store type is jceks.

In Eclipse Vert.x 3.x, all keystore entries would share the same password, that is, the keystore password. In Eclipse Vert.x 4, each keystore entry can have a dedicated password. If you do not want to set password for each keystore entry, you can configure the keystore password as the default password for all entries.

The following example shows how to load a jceks keystore in Eclipse Vert.x 3.x.

new KeyStoreOptions()
  .setPath("path/to/keystore.jks")
  .setPassword("keystore-password");

In Eclipse Vert.x 4, the default format is assumed to be the default format configured by JDK. The format is PKCS12 in Java 9 and above.

The following example shows how to load a jceks keystore in Eclipse Vert.x 4.

new KeyStoreOptions()
  .setPath("path/to/keystore.jks")
  // Modern JDKs use `jceks` keystore. But this type is not the default
  // If the type is not set to `jceks` then probably `pkcs12` will be used
  .setType("jceks")
  .setPassword("keystore-password")
  // optionally if your keys have different passwords
  // and if a key specific id is not provided it defaults to
  // the keystore password
  .putPasswordProtection("key-id", "key-specific-password");

The following methods have been removed:

The following methods have been deprecated:

The following classes have been deprecated:

In Eclipse Vert.x 4, the module protoc-gen-grpc-java is no longer available. This module was a fork of the official gRPC compiler. In earlier releases of Eclipse Vert.x, you had to work with this fork. This fork is maintained by the Eclipse project. Working with the fork was complex.

In previous releases, to work with gRPC, the following details were added to pom.xml file.

  <!-- Vert.x 3.x -->
<plugin>
  <groupId>org.xolstice.maven.plugins</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <configuration>
    <protocArtifact>com.google.protobuf:protoc:3.2.0:exe:${os.detected.classifier}</protocArtifact>
    <pluginId>grpc-java</pluginId>
    <!-- NOTE: the gav coordinates point to the 3.x only compiler fork -->
    <pluginArtifact>io.vertx:protoc-gen-grpc-java:${vertx.grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
  </configuration>
  ...
</plugin>

In Eclipse Vert.x 4, a new gRPC compiler plugin is available. This plugin uses the official gRPC compiler instead of the fork. To work with the new gRPC plugin, add the following details to pom.xml file.

    <!-- Vert.x 4.0 -->
<plugin>
  <groupId>org.xolstice.maven.plugins</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <configuration>
    <protocArtifact>com.google.protobuf:protoc:3.2.0:exe:${os.detected.classifier}</protocArtifact>
    <pluginId>grpc-java</pluginId>
    <!-- NOTE: the gav coordinates point to the official compiler -->
    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${vertx.grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
    <protocPlugins>
      <!-- NEW: a plugin is added to generate the Vert.x specific code -->
      <protocPlugin>
        <id>vertx-grpc-protoc-plugin</id>
        <groupId>io.vertx</groupId>
        <artifactId>vertx-grpc-protoc-plugin</artifactId>
        <version>${vertx.version}</version>
        <mainClass>io.vertx.grpc.protoc.plugin.VertxGrpcGenerator</mainClass>
      </protocPlugin>
    </protocPlugins>
  </configuration>
  ...
</plugin>

In Eclipse Vert.x 4, the new compiler is used. When the new gRPC plugin is used, the generated code is not written in the same source file. This is because the compiler does not allow custom code generation on its base class. The plugins must generate a new class with a different name to save the code.

In earlier releases of Eclipse Vert.x, the older gRPC plugin would write the generated code in the same source file.

For example, if you have the following descriptor:

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

In Eclipse Vert.x 3.x, the code would be generated in the GreeterGrpc class.

// 3.x
GreeterGrpc.GreeterVertxImplBase service =
  new GreeterGrpc.GreeterVertxImplBase() {
      ...
  }

In Eclipse Vert.x 4, the code is generated in the VertxGreeterGrpc class.

// 4.x
VertxGreeterGrpc.GreeterVertxImplBase service =
  new VertxGreeterGrpc.GreeterVertxImplBase() {
      ...
  }

In Eclipse Vert.x 4, the gRPC APIs support futures. The gRPC plugin generates promisified APIs. These APIs use the standard Eclipse Vert.x input and output arguments, which makes it easier to create standard Eclipse Vert.x applications.

The following example shows the use of promise in Eclipse Vert.x 3.x.

// 3.x
GreeterGrpc.GreeterVertxImplBase service =
  new GreeterGrpc.GreeterVertxImplBase() {
        @Override
        public void sayHello(HelloRequest request, Promise<HelloReply> future) {
          future.complete(
              HelloReply.newBuilder().setMessage(request.getName()).build());
        }
  }

The following example shows the use of futures in Eclipse Vert.x 4.

// 4.x
VertxGreeterGrpc.GreeterVertxImplBase service =
  new VertxGreeterGrpc.GreeterVertxImplBase() {
      @Override
      public Future<HelloReply> sayHello(HelloRequest request) {
        return Future.succeededFuture(
          HelloReply.newBuilder()
            .setMessage(request.getName())
            .build());
      }
  }

Some fluent methods in MqttClient class return Future instead of being fluent. For example, methods such as, MqttClient.connect(), MqttClient.disconnect(), MqttClient.publish() return future in Eclipse Vert.x 4.

The following example shows the use of publish() method in Eclipse Vert.x 3.x releases.

client
   .publish("hello", Buffer.buffer("hello"), MqttQoS.EXACTLY_ONCE, false, false)
   .publish("hello", Buffer.buffer("hello"), MqttQoS.AT_LEAST_ONCE, false, false);

The following example shows the use of publish() method in Eclipse Vert.x 4 release.

client.publish("hello", Buffer.buffer("hello"), MqttQoS.EXACTLY_ONCE, false, false);
client.publish("hello", Buffer.buffer("hello"), MqttQoS.AT_LEAST_ONCE, false, false);

The MqttWill data object wraps a string message as an Eclipse Vert.x buffer instead of a byte array.

The following MQTT methods have been removed:

The ServiceProxyProcessor class has been removed.

To use the service proxy code generator, you must import vertx-codegen with processor classifier in your classpath:

<dependencies>
  <dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-codegen</artifactId>
    <classifier>processor</classifier>
  </dependency>
  <dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-service-proxy</artifactId>
  </dependency>
</dependencies>

Service proxy reuses io.vertx.codegen.CodeGenProcessor from vertx-codegen to start the code generation of service proxy and handler.

The AdminUtils class is no longer available. Use the new KafkaAdminClient class instead to perform administrative operations on a Kafka cluster.

The flush methods in KafkaProducer class use Handler<AsyncResult<Void>> instead of Handler<Void>.

In Eclipse Vert.x 4, you can create a pool using the JDBC client APIs. In earlier releases, you could create only clients. You could not create pools.

The following example shows how to create a client in Eclipse Vert.x 3.x.

// 3.x
SQLClient client = JDBCClient.create(vertx, jsonConfig);

The following example shows how to create a pool in Eclipse Vert.x 4.

// 4.x
JDBCPool pool = JDBCPool.pool(vertx, jsonConfig);

A pool enables you to perform simple queries. You do not need to manage connections for simple queries. However, for complex queries or multiple queries, you must manage your connections.

The following example shows how to manage connections for queries in Eclipse Vert.x 3.x.

// 3.x
client.getConnection(res -> {
  if (res.succeeded()) {
    SQLConnection connection = res.result();
    // Important, do not forget to return the connection
    connection.close();
  } else {
    // Failed to get connection
  }
});

The following example shows how to manage connections for queries in Eclipse Vert.x 4.

// 4.x
pool
  .getConnection()
  .onFailure(e -> {
    // Failed to get a connection
  })
  .onSuccess(conn -> {
    // Important, do not forget to return the connection
    conn.close();
  });

You can use jsonConfig for configurations. However, using the jsonConfig may sometimes result in errors. To avoid these errors, the JDBC client introduces Typesafe Config.

The following example shows the basic structure of a Typesafe Config.

// 4.x ONLY!!!
JDBCPool pool = JDBCPool.pool(
      vertx,
      // configure the connection
      new JDBCConnectOptions()
        // H2 connection string
        .setJdbcUrl("jdbc:h2:~/test")
        // username
        .setUser("sa")
        // password
        .setPassword(""),
      // configure the pool
      new PoolOptions()
        .setMaxSize(16)
    );

This section shows you how to run queries in the JDBC client.

// 3.x
client.query("SELECT * FROM user WHERE emp_id > ?", new JsonArray().add(1000), res -> {
  if (res.succeeded()) {
    ResultSet rs = res2.result();
    // You can use these results in your application
  }
});

// 4.x
pool
  .preparedQuery("SELECT * FROM user WHERE emp_id > ?")
  // the emp id to look up
  .execute(Tuple.of(1000))
  .onSuccess(rows -> {
    for (Row row : rows) {
      System.out.println(row.getString("FIRST_NAME"));
    }
  });

pool
  .getConnection()
  .onFailure(e -> {
    // Failed to get a connection
  })
  .onSuccess(conn -> {
    conn
      .query("SELECT * FROM user")
      .execute()
      .onFailure(e -> {
        // Handle the failure
        // Important, do not forget to return the connection
        conn.close();
      })
      .onSuccess(rows -> {
        for (Row row : rows) {
          System.out.println(row.getString("FIRST_NAME"));
        }
        // Important, do not forget to return the connection
        conn.close();
      });
  });

Stored procedures are supported in the JDBC client.

The following example shows how to pass IN arguments in Eclipse Vert.x 3.x.

// 3.x
connection.callWithParams(
  "{ call new_customer(?, ?) }",
  new JsonArray().add("John").add("Doe"),
  null,
  res -> {
    if (res.succeeded()) {
      // Success!
    } else {
      // Failed!
    }
  });

The following example shows how to pass IN arguments in Eclipse Vert.x 4.

// 4.0
client
  .preparedQuery("{call new_customer(?, ?)}")
  .execute(Tuple.of("Paulo", "Lopes"))
  .onSuccess(rows -> {
    ...
  });

In Eclipse Vert.x 3.x, the support for combining the IN and OUT arguments was very limited due to the available types. In Eclipse Vert.x 4, the pool is type safe and can handle the combination of IN and OUT arguments. You can also use INOUT parameters in your applications.

The following example shows handling of arguments in Eclipse Vert.x 3.x.

// 3.x
connection.callWithParams(
  "{ call customer_lastname(?, ?) }",
  new JsonArray().add("John"),
  new JsonArray().addNull().add("VARCHAR"),
  res -> {
    if (res.succeeded()) {
      ResultSet result = res.result();
    } else {
      // Failed!
    }
});

The following example shows handling of arguments in Eclipse Vert.x 4.

// 4.x
client
  .preparedQuery("{call customer_lastname(?, ?)}")
  .execute(Tuple.of("John", SqlOutParam.OUT(JDBCType.VARCHAR)))
  .onSuccess(rows -> {
    ...
  });

In the JDBC client, the data types have been updated.

From Eclipse Vert.x 4 onwards, MailAttachment is available as an interface. It enables you to use the mail attachment functionality in a stream. In earlier releases of Eclipse Vert.x, MailAttachment was available as a class and attachment for mails was represented as a data object.

MailConfig interface extends the NetClientOptions interface. Due to this extension, mail configuration also supports the proxy setting of the NetClient.

The AMQP client methods that had Handler<AmqpMessage> as an argument have been removed. In earlier releases, you could set this handler on ReadStream<AmqpMessage>. However, if you migrate your applications to use futures, such methods cannot be used.

The following methods have been removed from MongoClient class.

Before Eclipse Vert.x 4, every Eclipse Vert.x release included a new release of the JavaScript client.

However, from Eclipse Vert.x 4 onward, a new version of JavaScript client will be available in npm only if there changes in the client. You do not need to update your client application for every Eclipse Vert.x release, unless there is a version change.

You can migrate your existing applications to new Redis client directly or use the helper class RedisAPI to migrate your applications in two steps.

Before migrating the applications you must create the client.

// Create the redis client (3.x)
RedisClient client = RedisClient
  .create(vertx, new RedisOptions().setHost(host));

// Create the redis client (4.x)
Redis client = Redis
  .createClient(
    vertx,
    "redis://server.address:port");

redis[s]://[[user]:password@]server[:port]/[database]

// Using 3.x
// omitting the error handling for brevity
client.set("key", "value", s -> {
  if (s.succeeded()) {
    System.out.println("key stored");
    client.get("key", g -> {
      if (s.succeeded()) {
        System.out.println("Retrieved value: " + s.result());
      }
    });
  }
});

// Using 4.x
// omitting the error handling for brevity

// 1. Wrap the client into a RedisAPI
api = RedisAPI.api(client);

// 2. Use the typed API
api.set(
    Arrays.asList("key", "value"), s -> {
    if (s.succeeded()) {
      System.out.println("key stored");
      client.get("key", g -> {
        if (s.succeeded()) {
          System.out.println("Retrieved value: " + s.result());
        }
      });
    }
});

// Using 3.x
// omitting the error handling for brevity
client.set("key", "value", s -> {
  if (s.succeeded()) {
    System.out.println("key stored");
    client.get("key", g -> {
      if (s.succeeded()) {
        System.out.println("Retrieved value: " + s.result());
      }
    });
  }
});

// Using 4.x
// omitting the error handling for brevity

import static io.vertx.redis.client.Request.cmd;
import static io.vertx.redis.client.Command.*;

client.send(cmd(SET).arg("key").arg("value"), s -> {
    if (s.succeeded()) {
      System.out.println("key stored");
      client.send(cmd(GET).arg("key"), g -> {
        if (s.succeeded()) {
          System.out.println("Retrieved value: " + s.result());
        }
      });
    }
});

// Using 4.x
// omitting the error handling for brevity

import static io.vertx.redis.client.Request.cmd;
import static io.vertx.redis.client.Command.*;

client.send(cmd(MGET).arg("key1").arg("key2").arg("key3"), mget -> {
  mget.result()
    .forEach(value -> {
      // Use the single value

This section describes changes in Redis client.

// Before (3.x)
Redis.createClient(
      rule.vertx(),
      new RedisOptions()
        .setType(RedisClientType.SENTINEL)
        .addConnectionString("redis://localhost:5000")
        .setMasterName("sentinel7000")
        .setRole(RedisRole.SLAVE));

// After (4.0)
Redis.createClient(
      rule.vertx(),
      new RedisOptions()
        .setType(RedisClientType.SENTINEL)
        .addConnectionString("redis://localhost:5000")
        .setMasterName("sentinel7000")
        .setRole(RedisRole.REPLICA));

// Before (3.9)
options.setUseSlaves(RedisSlaves);

// After (4.0)
options.setUseReplicas(RedisReplicas);

The Infinispan cluster manager is based on Infinispan 11.

In Eclipse Vert.x 4, the clustering SPI has been redesigned. The subscription data model has changed. As a result of this, Eclipse Vert.x 3.x nodes and Eclipse Vert.x 4 nodes cannot be added together in the same Infinispan cluster.

The Eclipse Vert.x applications are not impacted by this change as the EventBus and SharedData APIs remain the same.

If you had a custom Infinispan configuration file in your Eclipse Vert.x 3.x application:

 <cache-container default-cache="distributed-cache">
    <distributed-cache name="distributed-cache"/>
    <replicated-cache name="__vertx.subs"/>
    <replicated-cache name="__vertx.haInfo"/>
    <replicated-cache name="__vertx.nodeInfo"/>
    <distributed-cache-configuration name="__vertx.distributed.cache.configuration"/>
  </cache-container>

If you run an Eclipse Vert.x cluster on Openshift, the infinispan-cloud JAR is no longer needed. The JAR has been removed from the dependencies section of the build file. The configuration files that were bundled in this JAR are now included in the infinispan-core JAR.

If you have a cluster where different teams have deployed verticles for their applications, you can consider splitting the Eclipse Vert.x 3.x cluster into smaller ones. Note that after splitting the cluster, the separated components will not be able to communicate using the clustering features. You can split the cluster using the following components:

After you split the cluster, each team can move to Eclipse Vert.x 4 when they are ready or if required.

If you cannot split your cluster, then use Vert.x EventBus Link to migrate your codebase incrementally.

Vert.x EventBus Link is a tool that connects an Eclipse Vert.x 3.x clustered EventBus to an Eclipse Vert.x 4 clustered EventBus.

The tool creates an EventBusLink object that implements the EventBus interface. An instance of EventBusLink is created on at least one node of each cluster. The instance is created by providing a set of addresses and its behavior depends on the message paradigm:

The Eclipse Vert.x EventBus Link creates a WebSocket server to receive messages and uses a WebSocket client to send them.

See the sections get started and using for more details.

The vertx-core module has been updated to use a service provider interface for parameter injection. This change resulted in following updates in JUnit5:

The VertxTestContext.succeeding() and VertxTestContext.failing() methods have been deprecated. Use VertxTestContext.succeedingThenComplete() and VertxTestContext.failingThenComplete() methods instead.