Rephrasing changes

asciidoc/index.adoc

@@ -1,6 +1,8 @@
 ECLIPSE VERT.X 4 MIGRATION GUIDE
 
-This guide describes the updates in Eclipse Vert.x {v4} release. Use the information to upgrade your {VertX} {v3x} applications to {VertX} {v4}.
+This guide describes the updates in Eclipse Vert.x {v4} release. Use the information to upgrade your {VertX} {v3x} applications to {VertX} {v4}. It provides information about the new, deprecated and unsupported features in this release.
+
+Depending on the modules used in your application, you can read the relevant section to know more about the changes in {VertX} {v4}. 
 
 include::modules/con_mg-about-vertx.adoc[leveloffset=+1]
 

asciidoc/modules/con_mg_changes-in-eventbus-javascript-client.adoc

@@ -42,6 +42,6 @@ Use the following code in your build scripts to access the module.
 
 == Versioning of JavaScript client
 
-In earlier releases, for every {VertX} release included a new release of the JavaScript client.
+Before {VertX} {v4}, every {VertX} release included a new release of the JavaScript client.
 
 However, from {VertX} {v4} 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 {VertX} release, unless there is a version change.

asciidoc/modules/con_mg_changes-in-future.adoc

@@ -1,7 +1,7 @@
 [id="changes-in-handlers_{context}"]
-= Changes in Future
+= Changes in future
 
-This section explains the changes in Future.
+This section explains the changes in future.
 
 == Support for multiple handlers for futures
 
@@ -43,9 +43,3 @@ client.connectionHandler(conn -> {
   // Connection related code
 });
 ----
-
-== Checking the version of HTTP running on the server
-
-In earlier releases of {VertX}, the version of HTTP running on a server was checked only if the application explicitly called the `HttpServerRequest.version()` method. If the HTTP version was HTTP/1.x, the method would return the 501 HTTP status, and close the connection.
-
-From {VertX} {v4} onward, before a request is sent to the server, the HTTP version on the server is automatically checked by calling the `HttpServerRequest.version()` method. The method returns the HTTP version instead of throwing an exception when an invalid HTTP version is found.

asciidoc/modules/con_mg_changes-in-infinispan-cluster-manager.adoc

@@ -26,4 +26,4 @@ If you had a custom Infinispan configuration file in your {VertX} {v3x} applicat
   </cache-container>
 ----
 
-If you run a {VertX} 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 run an {VertX} 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.

asciidoc/modules/con_mg_changes-in-key-management.adoc

@@ -19,6 +19,7 @@ The `SecretOptions` class is no longer available. Use the new `PubSecKeyOptions`
 
 The following example shows how methods of `SecretOptions` class were used in {VertX} {v3x} releases.
 
+[source,java,options="nowrap",subs="attributes+"]
 ----
 new SecretOptions()
     .setType("HS256")
@@ -27,6 +28,7 @@ new SecretOptions()
 
 The following example shows how methods of `PubSecKeyOptions` class should be used in {VertX} {v4}.
 
+[source,java,options="nowrap",subs="attributes+"]
 ----
 new PubSecKeyOptions()
     .setAlgorithm("HS256")
@@ -46,16 +48,12 @@ The following example shows how to configure key pair in {VertX} {v3x}.
 ----
 new PubSecKeyOptions()
   .setPublicKey(
-    // remove the boundaries
-    // (don't do this as it doesn't handle end of lines
-    // it's for illustration purposes)
+    // remove the PEM boundaries
     pubPemString
       .replaceAll("-----BEGIN PUBLIC KEY----")
       .replaceAll("-----END PUBLIC KEY----"))
   .setSecretKey(
-    // remove the boundaries
-    // (don't do this as it doesn't handle end of lines
-    // it's for illustration purposes)
+    // remove the PEM boundaries
     secPemString
       .replaceAll("-----BEGIN PUBLIC KEY----")
       .replaceAll("-----END PUBLIC KEY----"));
@@ -69,12 +67,12 @@ The following example shows how to configure key pair in {VertX} {v4}.
 ----
 PubSecKeyOptions pubKey =
   new PubSecKeyOptions()
-    // the buffer is the exact contents of the PEM file (boundaries included)
+    // 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 (boundaries included)
+    // the buffer is the exact contents of the PEM file and had boundaries included in it
     .setBuffer(secPemString);
 ----
 
@@ -84,7 +82,7 @@ You can now handle X509 certificates using `PubSecKeyOptions`.
 ----
 PubSecKeyOptions x509Certificate =
   new PubSecKeyOptions()
-    // the buffer is the exact contents of the PEM file (boundaries included)
+    // the buffer is the exact contents of the PEM file and had boundaries included in it
     .setBuffer(x509PemString);
 ----
 
@@ -113,12 +111,12 @@ The following example shows how to load a `jceks` keystore in {VertX} {v4}.
 ----
 new KeyStoreOptions()
   .setPath("path/to/keystore.jks")
-  // this is required as for modern JDKs this isn't the default
-  // type and probaly `pkcs12` will be picked instead
+  // 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
-  // if a key specific id is not provided it defaults to
+  // and if a key specific id is not provided it defaults to
   // the keystore password
   .putPasswordProtection("key-id", "key-specific-password");
 ----

asciidoc/modules/con_mg_changes-in-vertx-amqp-client.adoc

@@ -5,7 +5,7 @@ The following section describes the changes in {VertX} AMQP client.
 
 == Removed methods in AMQP client that contain `AmqpMessage` argument
 
-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 types of methods cannot be used.
+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.
 
 |===
 |Removed methods|Replacing methods

asciidoc/modules/con_mg_changes-in-vertx-circuit-breaker.adoc

@@ -5,11 +5,11 @@ The following section describes the changes in {VertX} circuit breaker.
 
 == Removed execute command methods in circuit breaker
 
-The following methods are deprecated in `CircuitBreaker` class because they cannot be used with futures.
+The following methods have been removed from the `CircuitBreaker` class because they cannot be used with futures.
 
 [options="header"]
 |===
 |Removed methods|Replacing methods
-|`CircuitBreaker.executeCommand`| `CircuitBreaker.execute`
-|`CircuitBreaker.executeCommandWithFallback`| `CircuitBreaker.executeWithFallback`
+|`CircuitBreaker.executeCommand()`| `CircuitBreaker.execute()`
+|`CircuitBreaker.executeCommandWithFallback()`| `CircuitBreaker.executeWithFallback()`
 |===

asciidoc/modules/con_mg_changes-in-vertx-grpc.adoc

@@ -5,7 +5,7 @@ The following section describes the changes in {VertX} gRPC.
 
 == New gRPC compiler plugin
 
-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 {VertX} {v4}, the module `protoc-gen-grpc-java` is no 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.
 
@@ -96,7 +96,7 @@ VertxGreeterGrpc.GreeterVertxImplBase service =
 
 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}.
+The following example shows the use of promise in {VertX} {v3x}.
 
 [source,java]
 ----
@@ -111,7 +111,7 @@ GreeterGrpc.GreeterVertxImplBase service =
   }
 ----
 
-The following example shows use of futures in {VertX} {v4}.
+The following example shows the use of futures in {VertX} {v4}.
 
 [source,java]
 ----

asciidoc/modules/con_mg_changes-in-vertx-jdbc-client.adoc

@@ -9,7 +9,8 @@ In {VertX} {v4}, the SQL client has been updated to include the following client
 
 * Reactive MySQL client
 * Reactive DB2 client
-* Existing JDBC client that includes the JDBC client API and the SQL client API.
+* Continues to include reactive PostgreSQL client. This client was available in {VertX} {v3x} releases as well.
+* Existing JDBC client now includes both the JDBC client API and the SQL client API
 
 The reactive implementations use the database network protocols. This makes them resource-efficient.
 
@@ -37,7 +38,7 @@ The following example shows how to create a pool in {VertX} {v4}.
 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.
+NOTE: Though the {VertX} {v3x} APIs are supported in {VertX} {v4}, it is recommended that you use the new JDBC 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.
 
@@ -49,10 +50,10 @@ The following example shows how to manage connections for queries in {VertX} {v3
 client.getConnection(res -> {
   if (res.succeeded()) {
     SQLConnection connection = res.result();
-    // very important! do not forget to return the connection
+    // Important, do not forget to return the connection
     connection.close();
   } else {
-    // Failed to get connection - deal with it
+    // Failed to get connection
   }
 });
 ----
@@ -65,10 +66,10 @@ The following example shows how to manage connections for queries in {VertX} {v4
 pool
   .getConnection()
   .onFailure(e -> {
-    // failed to get a connection
+    // Failed to get a connection
   })
   .onSuccess(conn -> {
-    // very important! don't forget to return the connection
+    // Important, do not forget to return the connection
     conn.close();
   });
 ----
@@ -114,7 +115,7 @@ The following example shows how to run queries without managing the connection i
 client.query("SELECT * FROM user WHERE emp_id > ?", new JsonArray().add(1000), res -> {
   if (res.succeeded()) {
     ResultSet rs = res2.result();
-    // Do something with results
+    // You can use these results in your application
   }
 });
 ----
@@ -144,22 +145,22 @@ The following example shows how to run queries on managed connections in {VertX}
 pool
   .getConnection()
   .onFailure(e -> {
-    // failed to get a connection
+    // 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
+        // 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"));
         }
-        // very important! don't forget to return the connection
+        // Important, do not forget to return the connection
         conn.close();
       });
   });
@@ -235,6 +236,6 @@ client
 
 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.
+* For an argument 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 types are not bound by JSON limitations. You can now use database specific types instead of text constants for the type name.

asciidoc/modules/con_mg_changes-in-vertx-mqtt.adoc

@@ -7,26 +7,28 @@ The following section describes the changes in {VertX} MQTT.
 
 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 {VertX} {v4}.
 
-The following example shows the use of `publish()` method in {VertX} {v3x} releases:
+The following example shows the use of `publish()` method in {VertX} {v3x} releases.
 
+[source,java,options="nowrap",subs="attributes+"]
 ----
 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 {VertX} {v4} release:
+The following example shows the use of `publish()` method in {VertX} {v4} release.
 
+[source,java,options="nowrap",subs="attributes+"]
 ----
 client.publish("hello", Buffer.buffer("hello"), MqttQoS.EXACTLY_ONCE, false, false);
 client.publish("hello", Buffer.buffer("hello"), MqttQoS.AT_LEAST_ONCE, false, false);
 ----
 
-== Mqtt will message returns a buffer
+== `MqttWill` messages return buffer
 
 The `MqttWill` data object wraps a string message as an {VertX} buffer instead of a byte array.
 
-== Removed the deprecated will and authorization methods from MQTT
+== Removed the deprecated `MqttWill` and authorization methods from MQTT
 
 The following MQTT methods have been removed:
 

asciidoc/modules/con_mg_changes-in-vertx-service-discovery.adoc

@@ -3,7 +3,7 @@
 
 The following section describes the changes in {VertX} service discovery.
 
-== Removed create methods that contain `ServiceDiscovery` argument from service discovery
+== Removed create methods from service discovery that contain `ServiceDiscovery` argument 
 
 The following create methods in service discovery that have `Handler<AmqpMessage>` as an argument have been removed. These methods cannot be used with futures.
 

asciidoc/modules/con_mg_changes-in-vertx-service-proxy.adoc

@@ -9,6 +9,7 @@ The `ServiceProxyProcessor` class has been removed.
 
 To use the service proxy code generator, you must import `vertx-codegen` with processor classifier in your classpath:
 
+[source,java,options="nowrap",subs="attributes+"]
 ----
 <dependencies>
   <dependency>

asciidoc/modules/con_mg_changes-in-vertx-web.adoc

@@ -111,7 +111,7 @@ 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 (e.g. in a local map)
+  // Retrieve the writeHandlerID and store it (For example, in a local map)
   String writeHandlerID = sockJSSocket.writeHandlerID();
 }));
 ----

asciidoc/modules/con_mg_handling_deprecations_and_removals.adoc

@@ -3,7 +3,7 @@
 
 Some features and functions have been deprecated or removed in {VertX} {v4}. Before you migrate your applications to {VertX} {v4}, check for deprecations and removals.
 
-* Some APIs were deprecated in a {VertX} {v3x} release and new equivalent APIs were provided in that release.
+* Some APIs were deprecated in an {VertX} {v3x} release and new equivalent APIs were provided in that release.
 
 * The deprecated APIs have been removed in {VertX} {v4}.