diff --git a/asciidoc/chapters/assembly_mg_changes-in-client-components.adoc b/asciidoc/chapters/assembly_mg_changes-in-client-components.adoc index 3958d35..8b59a0c 100644 --- a/asciidoc/chapters/assembly_mg_changes-in-client-components.adoc +++ b/asciidoc/chapters/assembly_mg_changes-in-client-components.adoc @@ -20,5 +20,7 @@ include::../modules/con_mg_changes-in-vertx-mongodb-client.adoc[leveloffset=+1] include::../chapters/assembly_mg_changes-in-vertx-redis-client.adoc[leveloffset=+1] +include::../community_features/rabbitmq-client.adoc[leveloffset=+1] + ifdef::parent-context-of-changes-in-client-components[:context: {parent-context-of-changes-in-client-components}] ifndef::parent-context-of-changes-in-client-components[:!context:] diff --git a/asciidoc/chapters/assembly_mg_changes-in-clustering.adoc b/asciidoc/chapters/assembly_mg_changes-in-clustering.adoc new file mode 100644 index 0000000..24ee27b --- /dev/null +++ b/asciidoc/chapters/assembly_mg_changes-in-clustering.adoc @@ -0,0 +1,14 @@ +ifdef::context[:parent-context-of-changes-in-clustering: {context}] + +[id="changes-in-clustering_{context}"] += Changes in clustering +:context: changes-in-clustering + +This section explains the changes in clustering. + +include::../modules/con_mg_changes-in-infinispan-cluster-manager.adoc[leveloffset=+1] + +include::../community_features/ignite.adoc[leveloffset=+1] + +ifdef::parent-context-of-changes-in-clustering[:context: {parent-context-of-changes-in-clustering}] +ifndef::parent-context-of-changes-in-clustering[:!context:] diff --git a/asciidoc/chapters/assembly_mg_changes-in-common-components.adoc b/asciidoc/chapters/assembly_mg_changes-in-common-components.adoc index bfe9b19..7cffd76 100644 --- a/asciidoc/chapters/assembly_mg_changes-in-common-components.adoc +++ b/asciidoc/chapters/assembly_mg_changes-in-common-components.adoc @@ -30,6 +30,8 @@ include::../modules/con_mg_changes-in-json.adoc[leveloffset=+1] include::../modules/con_mg_changes-in-vertx-web.adoc[leveloffset=+1] +include::con_mg_changes-in-vertx-web-graphql.adoc[leveloffset=+1] + include::../modules/con_mg_changes-in-micrometer-metrics.adoc[leveloffset=+1] include::../modules/con_mg_changes-in-vertx-openapi.adoc[leveloffset=+1] diff --git a/asciidoc/chapters/assembly_mg_what-is-new-and-different-in-vertx-4.adoc b/asciidoc/chapters/assembly_mg_what-is-new-and-different-in-vertx-4.adoc index 1da82fb..60d6c8a 100644 --- a/asciidoc/chapters/assembly_mg_what-is-new-and-different-in-vertx-4.adoc +++ b/asciidoc/chapters/assembly_mg_what-is-new-and-different-in-vertx-4.adoc @@ -11,6 +11,8 @@ include::../modules/con_mg_use-future-methods-for-asynchronous-operations.adoc[l include::../modules/con_mg_no_dependency_on_the_jackson_databind_library.adoc[leveloffset=+1] +include::../modules/con_mg_support_for_opentracing.adoc[leveloffset=+1] + include::../modules/con_mg_handling_deprecations_and_removals.adoc[leveloffset=+1] ifdef::parent-context-of-what-is-new-and-different-in-vertx-4[:context: {parent-context-of-what-is-new-and-different-in-vertx-4}] diff --git a/asciidoc/index.adoc b/asciidoc/index.adoc index aae14e5..7f78c6c 100644 --- a/asciidoc/index.adoc +++ b/asciidoc/index.adoc @@ -4,8 +4,6 @@ This guide describes the updates in {VertX} {v4} release. Use the information to include::modules/con_mg-about-vertx.adoc[leveloffset=+1] -include::../modules/proc_configuring-your-application-to-use-vertx.adoc[leveloffset=+1] - include::chapters/assembly_mg_what-is-new-and-different-in-vertx-4.adoc[leveloffset=+1] include::chapters/assembly_mg_changes-in-common-components.adoc[leveloffset=+1] diff --git a/asciidoc/modules/con_mg_changes-in-vertx-grpc.adoc b/asciidoc/modules/con_mg_changes-in-vertx-grpc.adoc index 9362aed..cc19089 100644 --- a/asciidoc/modules/con_mg_changes-in-vertx-grpc.adoc +++ b/asciidoc/modules/con_mg_changes-in-vertx-grpc.adoc @@ -5,42 +5,123 @@ The following section describes the changes in {VertX} gRPC. == New gRPC compiler plugin -In earlier releases of {VertX}, to compile a gRPC `.proto` descriptor, you had to work with fork of the official gRPC compiler. This fork is maintained by the Eclipse project. Working with the fork was complex. +In {VertX} {v4}, the module `protoc-gen-grpc-java` is longer available. This module was a fork of the official gRPC compiler. In earlier releases of {VertX}, 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. +[source,xml] ---- - - org.xolstice.maven.plugins - protobuf-maven-plugin - - com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier} - grpc-java - io.vertx:protoc-gen-grpc-java:1.25.0:exe:${os.detected.classifier} - - + + + org.xolstice.maven.plugins + protobuf-maven-plugin + + com.google.protobuf:protoc:3.2.0:exe:${os.detected.classifier} + grpc-java + + io.vertx:protoc-gen-grpc-java:${vertx.grpc.version}:exe:${os.detected.classifier} + + ... + ---- In {VertX} {v4}, 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. +[source,xml] ---- - - org.xolstice.maven.plugins - protobuf-maven-plugin - 0.6.1 - - com.google.protobuf:protoc:${protoc.version}:exe:${os.detected.classifier} - grpc-java - io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier} - - - vertx-grpc-protoc-plugin - io.vertx - vertx-grpc-protoc-plugin - ${vertx.version} - io.vertx.grpc.protoc.plugin.VertxGrpcGenerator - - - - + + + org.xolstice.maven.plugins + protobuf-maven-plugin + + com.google.protobuf:protoc:3.2.0:exe:${os.detected.classifier} + grpc-java + + io.grpc:protoc-gen-grpc-java:${vertx.grpc.version}:exe:${os.detected.classifier} + + + + vertx-grpc-protoc-plugin + io.vertx + vertx-grpc-protoc-plugin + ${vertx.version} + io.vertx.grpc.protoc.plugin.VertxGrpcGenerator + + + + ... + +---- + +== Migrating the generated code + +In {VertX} {v4}, 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 {VertX}, the older gRPC plugin would write the generated code in the same source file. + +For example, if you have the following descriptor: + +[source,proto] +---- +service Greeter { + rpc SayHello (HelloRequest) returns (HelloReply) {} +} +---- + +In {VertX} {v3x}, the code would be generated in the `GreeterGrpc` class. + +[source,java] +---- +// 3.x +GreeterGrpc.GreeterVertxImplBase service = + new GreeterGrpc.GreeterVertxImplBase() { + ... + } +---- + +In {VertX} {v4}, the code is generated in the `VertxGreeterGrpc` class. + +[source,java] +---- +// 4.x +VertxGreeterGrpc.GreeterVertxImplBase service = + new VertxGreeterGrpc.GreeterVertxImplBase() { + ... + } +---- + +== gRPC APIs support futures + +In {VertX} {v4}, the gRPC APIs support futures. The gRPC plugin generates promisified APIs. These APIs use the standard {VertX} input and output arguments, which makes it easier to create standard {VertX} applications. + +The following example shows you use of promises in {VertX} {v3x}. + +[source,java] +---- +// 3.x +GreeterGrpc.GreeterVertxImplBase service = + new GreeterGrpc.GreeterVertxImplBase() { + @Override + public void sayHello(HelloRequest request, Promise future) { + future.complete( + HelloReply.newBuilder().setMessage(request.getName()).build()); + } + } +---- + +The following example shows use of futures in {VertX} {v4}. + +[source,java] +---- +// 4.x +VertxGreeterGrpc.GreeterVertxImplBase service = + new VertxGreeterGrpc.GreeterVertxImplBase() { + @Override + public Future sayHello(HelloRequest request) { + return Future.succeededFuture( + HelloReply.newBuilder() + .setMessage(request.getName()) + .build()); + } + } ---- diff --git a/asciidoc/modules/con_mg_changes-in-vertx-jdbc-client.adoc b/asciidoc/modules/con_mg_changes-in-vertx-jdbc-client.adoc index ad0d375..0ca69d5 100644 --- a/asciidoc/modules/con_mg_changes-in-vertx-jdbc-client.adoc +++ b/asciidoc/modules/con_mg_changes-in-vertx-jdbc-client.adoc @@ -1,8 +1,240 @@ [id="changes-in-vertx-jdbc-client_{context}"] = Changes in {VertX} JDBC client +From {VertX} {v4}, the JDBC client supports SQL client. The SQL common module has also been merged in JDBC client, that is, `io.vertx:vertx-sql-common` merged in `io.vertx:vertx-jdbc-client` module. You will have to remove the `io.vertx:vertx-sql-common` dependency file because `io.vertx:vertx-jdbc-client` will include it. With the merging of SQL common client, all the database APIs have been consolidated into the JDBC client. + +In {VertX} {v4}, the SQL client has been updated to include the following clients: + +* Reactive PostgreSQL client. In earlier releases, it included a reactive PostgreSQL client. + +* Reactive MySQL client +* Reactive DB2 client +* Existing JDBC client that includes the JDBC client API and the SQL client API. + +The reactive implementations use the database network protocols. This makes them resource-efficient. + +JDBC calls to database are blocking calls. The JDBC client uses worker threads to make these calls non-blocking. + The following section describes the changes in {VertX} JDBC client. -== Merged Vert.x SQL common module in JDBC client module +== Creating a pool + +In {VertX} {v4}, 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 {VertX} {v3x}. + +[source,java] +---- +// 3.x +SQLClient client = JDBCClient.create(vertx, jsonConfig); +---- + +The following example shows how to create a pool in {VertX} {v4}. + +[source,java] +---- +// 4.x +JDBCPool pool = JDBCPool.pool(vertx, jsonConfig); +---- + +NOTE: Though the {VertX} {v3x} APIs are supported in {VertX} {v4}, it is recommended that you use the new JDC client APIs in your applications. + +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 {VertX} {v3x}. + +[source,java] +---- +// 3.x +client.getConnection(res -> { + if (res.succeeded()) { + SQLConnection connection = res.result(); + // very important! do not forget to return the connection + connection.close(); + } else { + // Failed to get connection - deal with it + } +}); +---- + +The following example shows how to manage connections for queries in {VertX} {v4}. + +[source,java] +---- +// 4.x +pool + .getConnection() + .onFailure(e -> { + // failed to get a connection + }) + .onSuccess(conn -> { + // very important! don't forget to return the connection + conn.close(); + }); +---- + +== Support for Typsesafe Config + +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. + +[source,java] +---- +// 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) + ); +---- + +NOTE: To use Typesafe Config, you must include the `agroal` connection pool in your project. The pool does not expose many configuration options and makes the configuration easy to use. + +== Running SQL queries + +This section shows you how to run queries in the JDBC client. + +=== Running one shot queries + +The following example shows how to run queries without managing the connection in {VertX} {v3x}. + +[source,java] +---- +// 3.x +client.query("SELECT * FROM user WHERE emp_id > ?", new JsonArray().add(1000), res -> { + if (res.succeeded()) { + ResultSet rs = res2.result(); + // Do something with results + } +}); +---- + +The following example shows how to run queries without managing the connection in {VertX} {v4}. + +[source,java] +---- +// 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")); + } + }); +---- + +=== Running queries on managed connections + +The following example shows how to run queries on managed connections in {VertX} {v4}. + +[source,java] +---- +pool + .getConnection() + .onFailure(e -> { + // failed to get a connection + }) + .onSuccess(conn -> { + conn + .query("SELECT * FROM user") + .execute() + .onFailure(e -> { + // handle the failure + // very important! don't forget to return the connection + conn.close(); + }) + .onSuccess(rows -> { + for (Row row : rows) { + System.out.println(row.getString("FIRST_NAME")); + } + // very important! don't forget to return the connection + conn.close(); + }); + }); +---- + +== Support for stored procedures + +Stored procedures are supported in the JDBC client. + +The following example shows how to pass `IN` arguments in {VertX} {v3x}. + +[source,java] +---- +// 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 {VertX} {v4}. + +[source,java] +---- +// 4.0 +client + .preparedQuery("{call new_customer(?, ?)}") + .execute(Tuple.of("Paulo", "Lopes")) + .onSuccess(rows -> { + ... + }); +---- + +In {VertX} {v3x}, the support for combining the `IN` and `OUT` arguments was very limited due to the available types. In {VertX} {v4}, 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 {VertX} {v3x}. + +[source,java] +---- +// 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 {VertX} {v4}. + +[source,java] +---- +// 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. + +* For an argument is of type `OUT`, you can specify its return type. In the example, the `OUT` argument is specified as type `VARCHAR` which is a JDBC constant. -The `io.vertx:vertx-sql-common` module has been merged in `io.vertx:vertx-jdbc-client` module. You will have to remove the `io.vertx:vertx-sql-common` dependency file because `io.vertx:vertx-jdbc-client` will include it. +* The types are not bound by JSON limitations. You can now use database specific types instead of text constants for the type name. diff --git a/asciidoc/modules/con_mg_changes-in-vertx-openapi.adoc b/asciidoc/modules/con_mg_changes-in-vertx-openapi.adoc index ac9e624..4c19853 100644 --- a/asciidoc/modules/con_mg_changes-in-vertx-openapi.adoc +++ b/asciidoc/modules/con_mg_changes-in-vertx-openapi.adoc @@ -69,7 +69,7 @@ int aParam = parameters.queryParameter("aParam").getInteger(); == Handling security In {VertX} {v4}, the -methods `RouterFactory.addSecurityHandler()` and `OpenAPI3RouterFactory.addSecuritySchemaScopeValidator()` are no longer available.XXX +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 also automatically recognizes `OAuth2Handler` and sets up the security schema. diff --git a/asciidoc/modules/con_mg_migrating-applications-to-new-redis-client.adoc b/asciidoc/modules/con_mg_migrating-applications-to-new-redis-client.adoc index 22536fc..47d547f 100644 --- a/asciidoc/modules/con_mg_migrating-applications-to-new-redis-client.adoc +++ b/asciidoc/modules/con_mg_migrating-applications-to-new-redis-client.adoc @@ -59,8 +59,8 @@ client.set("key", "value", s -> { }); ---- -The following example shows you how to handle requests after creating the client in {VertX} {v4}. The example uses a list -to set XXX instead of hard coding options. See link:https://redis.io/commands/set[Redis SET command] for more information on arguments available for the command. +The following example shows how to handle requests after creating the client in {VertX} {v4}. The example uses a list +for setting the key-value pairs instead of hard coding options. See link:https://redis.io/commands/set[Redis SET command] for more information on arguments available for the command. ---- // Using 4.x diff --git a/asciidoc/modules/con_mg_miscellaneous-changes-in-vertx.adoc b/asciidoc/modules/con_mg_miscellaneous-changes-in-vertx.adoc index 6a4cac1..36a5083 100644 --- a/asciidoc/modules/con_mg_miscellaneous-changes-in-vertx.adoc +++ b/asciidoc/modules/con_mg_miscellaneous-changes-in-vertx.adoc @@ -55,6 +55,6 @@ Use the following new methods to create clients that do not have shared data sou include::con_mg_changes-in-vertx-junit5.adoc[leveloffset=+1] -include::con_mg_changes-in-infinispan-cluster-manager.adoc[leveloffset=+1] +include::../community_features/kotlin.adoc[leveloffset=+1] -include::con_mg_changes-in-vertx-web-graphql.adoc[leveloffset=+1] +include::../community_features/wiremongo.adoc[leveloffset=+1] diff --git a/asciidoc/modules/con_mg_support_for_opentracing.adoc b/asciidoc/modules/con_mg_support_for_opentracing.adoc new file mode 100644 index 0000000..4878cb3 --- /dev/null +++ b/asciidoc/modules/con_mg_support_for_opentracing.adoc @@ -0,0 +1,2 @@ +[id="support_for_opentracing_{context}"] += Support for Opentracing