DOC-278 vertx (#1623)

Moved Java code samples to the examples folder, and gave the Vertx
topics a copy edit, and structured the tutorial according to new
template

---------

Co-authored-by: Rob Swain <rob.swain@hazelcast.com>
Co-authored-by: Jack Green <jack.green@hazelcast.com>

Author: 3 people

docs/modules/integrate/pages/get-started-with-vertx.adoc

@@ -2,11 +2,13 @@
 
 This tutorial helps you integrate Vert.x with Hazelcast and use Hazelcast for distributed session management and other distributed data structures.
 
-In this tutorial, you will
+== Overview
 
-- start with a simple Vert.x Hello World application
-- add vertx-hazelcast module and enable distributed session management
-- use `io.vertx.core.shareddata.Counter` data structure to implement a unique id generator
+In this tutorial, you will learn how to:
+
+- Start with a simple Vert.x Hello World application.
+- Add the vertx-hazelcast module and enable distributed session management.
+- Use the `io.vertx.core.shareddata.Counter` data structure to implement a unique ID generator.
 
 == Prerequisites
 
@@ -25,7 +27,7 @@ In this tutorial, you will
 $ mvn clean package
 ----
 
-and start the application using:
+Then start the application using:
 
 [source,bash]
 ----
@@ -41,14 +43,15 @@ Aug 29, 2024 2:22:38 PM io.vertx.launcher.application.VertxApplication
 INFO: Succeeded in deploying verticle
 ----
 
-== Storing Data in Session
+== Store data in session
 
 Go to the `MainVerticle.java` file and replace the contents of the start method with the following:
 
-NOTE: This tutorial uses 2-space indentation, which is customary for Vertx projects due to the high number of nested callbacks.
+NOTE: This tutorial uses 2-space indentation, which is customary for Vert.x projects due to the high number of nested callbacks.
 
 [source,java]
 ----
+// include::ROOT:example$/vertx/vertxMainVerticleStart.java[] Save for later; keep code sample inline for now
   public void start() {
     // Create a Router
     Router router = router(vertx);
@@ -105,6 +108,8 @@ NOTE: This tutorial uses 2-space indentation, which is customary for Vertx proje
   }
 ----
 
+Next, test the server response:
+
 [source,bash]
 ----
 $ http put localhost:8888 message=Hello\ World!
@@ -139,15 +144,15 @@ content-type: application/json
 
 ----
 
-== Distributed Sessions
+== Distributed sessions
 
-Let's modify the code, so we can start multiple instances easily - the application will start on the defined port, and when the port is not available it will search for another port:
+Let's modify the code, so we can start multiple instances easily — the application will start on the defined port and, if the port is unavailable, it will search for another port:
 
 Add the following method to the `MainVerticle.java` class:
 
 [source,java]
 ----
-  private int findFreePort(int from) {
+private int findFreePort(int from) {
     for (int port = from; port < from + 100; port++) {
       try {
         new ServerSocket(port).close();
@@ -160,20 +165,20 @@ Add the following method to the `MainVerticle.java` class:
   }
 ----
 
-and use it in the `start` method:
+And then use it in the `start` method:
 
 [source,java]
 ----
-    ...
-    int port = findFreePort(8888);
-
-    // Create the HTTP server
-    vertx.createHttpServer()
-      // Handle every request using the router
-      .requestHandler(router)
-      // Start listening
-      .listen(port)
-    ...
+...
+int port = findFreePort(8888);
+
+// Create the HTTP server
+vertx.createHttpServer()
+  // Handle every request using the router
+  .requestHandler(router)
+  // Start listening
+  .listen(port)
+...
 ----
 
 Now, we can start two instances:
@@ -193,7 +198,7 @@ Aug 30, 2024 9:09:47 AM io.vertx.launcher.application.VertxApplication
 INFO: Succeeded in deploying verticle
 ----
 
-and we can see the session is not shared between the instances. Here is the request to the first instance:
+We can see the session is not shared between the instances. Here is the request to the first instance:
 
 [source, bash]
 ----
@@ -210,7 +215,7 @@ set-cookie: vertx-web.session=00f219c166ca50727d23eaaf9fe54229; Path=/
 }
 ----
 
-and here is the request to the 2nd instance. Notice the different port and that we use the cookie we received, but the data does not contain the previous message.
+And here is the request to the 2nd instance. Notice the different port and that we use the cookie we received, but the data does not contain the previous message.
 
 [source, bash]
 ----
@@ -229,12 +234,12 @@ set-cookie: vertx-web.session=a1486c5ed6416972fdc356e4d91d2397; Path=/
 
 We will fix that by using a Hazelcast Cluster Manager. There are two modules that provide Hazelcast Cluster Manager:
 
-- `io.vertx:vertx-hazelcast` - this module is maintained by the Vert.x team, with contributions from Hazelcast, and is built on top of open-source Hazelcast
+- `io.vertx:vertx-hazelcast` - this module is maintained by the Vert.x team, with contributions from Hazelcast, and is built on top of open-source Hazelcast.
 - `com.hazelcast:vertx-hazelcast-enterprise` - this module is maintained by the Hazelcast team and is built on top of the `vertx-hazelcast` but uses Hazelcast Enterprise instead. You need an enterprise license to use Hazelcast Enterprise.
 
-You can use either module for most of this tutorial. At the end of this tutorial you will need the `vertx-hazelcast-enterprise` module.
+You can use either module for most of this tutorial, however, at the end you will need the `vertx-hazelcast-enterprise` module.
 
-NOTE: You can get your trial key at https://hazelcast.com/get-started/?utm_source=docs-website[hazelcast.com] or you can use `vertx-hazelcast` and a community edition of Hazelcast.
+NOTE: You can get a trial key at https://hazelcast.com/get-started/?utm_source=docs-website[hazelcast.com] or you can use `vertx-hazelcast` and a {open-source-product-name} of Hazelcast.
 
 Add the following dependency to the `pom.xml`:
 
@@ -263,7 +268,7 @@ to the following:
 SessionStore store = ClusteredSessionStore.create(vertx);
 ----
 
-and from now on we will start the application with `-server` parameter, which tells Vert.x to look for a cluster manager implementation.
+From now on, we will start the application with the `-server` parameter, which tells Vert.x to look for a cluster manager implementation.
 
 We also need to provide a Hazelcast configuration file, and create a file cluster.xml in the `src/main/resources` directory:
 
@@ -325,7 +330,7 @@ Members {size:2, ver:2} [
 ...
 ----
 
-and
+And:
 
 [source,bash]
 ----
@@ -375,6 +380,8 @@ content-type: application/json
 
 == Using Counter
 
+Next, we'll use Hazelcast's distributed counter functionality to generate unique, incrementing IDs across a distributed system. The counter is maintained across all nodes in the Hazelcast cluster, ensuring each request gets a unique ID even when multiple servers are handling requests.
+
 Replace this part of the code at the end of the `start()` method:
 
 [source,java]
@@ -404,7 +411,7 @@ context.vertx()
   });
 ----
 
-When you now try the application, you can see the response contains an additional field named `requestId` and its value increments for every request.
+Now, when you try the application, you can see the response contains an additional field named `requestId` and its value increments for every request.
 
 [source,bash]
 ----
@@ -422,11 +429,11 @@ set-cookie: vertx-web.session=d9fb4cada5c0fc625089a38f3de13e3c; Path=/
 }
 ----
 
-== CP Subsystem backed Lock and Counter
+== CP Subsystem-backed Lock and Counter
 
-The module `vertx-hazelcast-enterprise` provides a different implementation of the `io.vertx.core.shareddata.Counter` and `io.vertx.core.shareddata.Lock` data structures. The implementation in `vertx-hazelcast` is based on the IMap data structure and provides guarantees defined in the xref:architecture:data-partitioning.adoc#best-effort-consistency[Best-effort consistency] section. This means that under certain network partition conditions the counter doesn't provide strong consistency guarantees and can generate duplicate values.
+The `vertx-hazelcast-enterprise` module provides a different implementation of the `io.vertx.core.shareddata.Counter` and `io.vertx.core.shareddata.Lock` data structures. The implementation in `vertx-hazelcast` is based on the IMap data structure and provides guarantees defined in the xref:architecture:data-partitioning.adoc#best-effort-consistency[Best-effort consistency] section—however, this means that under certain network partition conditions, the counter does not provide strong consistency guarantees and can generate duplicate values.
 
-The module `vertx-hazelcast-enterprise` uses the CP Subsystem from {enterprise-product-name} to implement the Lock and Counter.
+In contrast, the `vertx-hazelcast-enterprise` module uses the CP Subsystem from {enterprise-product-name} to implement strong consistency for the Lock and Counter.
 
 NOTE: For the rest of this tutorial you need to have an {enterprise-product-name} license.
 
@@ -441,7 +448,7 @@ Make sure you have the following dependency:
 </dependency>
 ----
 
-and your XML config contains a valid license key:
+And your XML config contains a valid license key:
 
 [source,xml]
 ----
@@ -459,3 +466,15 @@ Enable the CP subsystem, and in cluster.xml change the value of the `` property
 
 You need to start at least 3 instances for the cluster to form successfully. For complete documentation, see the xref:cp-subsystem:cp-subsystem.adoc[CP Subsystem] section.
 
+== Summary
+
+In this tutorial, you learned how to add the vertx-hazelcast module and enable distributed session management, as well as how to use the `io.vertx.core.shareddata.Counter` data structure to implement a unique id generator. 
+
+== Next steps
+
+You can dive deeper into the two available modules for integrating Hazelcast with Vert.x:
+
+- `io.vertx:vertx-hazelcast`: the open-source module maintained by the Vert.x team.
+- `com.hazelcast:vertx-hazelcast-enterprise`: the enterprise module with advanced features like strong consistency for locks and counters using the CP Subsystem.
+
+See: https://hazelcast.com/blog/seamless-integration-with-vert-x-boosting-performance-and-scalability-in-java-applications/[Seamless Integration with Vert.x]

docs/modules/integrate/pages/integrate-with-vertx.adoc

@@ -2,23 +2,25 @@
 
 Vert.x is a reactive application toolkit for creating resource-efficient, concurrent, asynchronous and flexible applications on the JVM.
 
-Hazelcast integrates with Vert.x in a form of a cluster manager - the link:https://vertx.io/docs/vertx-hazelcast/java/[Hazelcast Cluster Manager].
+Hazelcast integrates with Vert.x in the form of a cluster manager — the link:https://vertx.io/docs/vertx-hazelcast/java/[Hazelcast Cluster Manager].
 
+In Vert.x, a cluster manager is used for various functions including:
 
-In Vert.x a cluster manager is used for various functions including:
-
-- Discovery and group membership of Vert.x nodes in a cluster
-- Maintaining cluster-wide topic subscriber lists (so we know which nodes are interested in which event bus addresses)
-- Distributed Map support
-- Distributed Locks
-- Distributed Counters
+- Discovery and group membership of Vert.x nodes in a cluster.
+- Maintaining cluster-wide topic subscriber lists (so we know which nodes are interested in which event bus addresses).
+- Distributed Map support.
+- Distributed Locks.
+- Distributed Counters.
 
 There are 2 modules to choose from:
-- `io.vertx:vertx-hazelcast` - this module is part of Vert.x and is maintained by the Vert.x team with contributions from Hazelcast developers. This module is licensed under the Apache 2 license.
 
-- `com.hazelcast:vertx-hazelcast-enterprise` - this module is built on top of `vertx-hazelcast` and leverages functionality of {enterprise-product-name} to implement some of the cluster manager functionality (e.g. it uses the CP Subsystem to implement strongly consistent `io.vertx.core.shareddata.Lock` and `io.vertx.core.shareddata.Counter`).
+- `io.vertx:vertx-hazelcast` — this module is part of Vert.x and is maintained by the Vert.x team with contributions from Hazelcast developers. This module is licensed under the Apache 2 license.
+
+- `com.hazelcast:vertx-hazelcast-enterprise` — this module is built on top of `vertx-hazelcast` and leverages functionality of {enterprise-product-name} to implement some of the cluster manager functionality (e.g. it uses the CP Subsystem to implement strongly consistent Lock and Counter data structures: `io.vertx.core.shareddata.Lock` and `io.vertx.core.shareddata.Counter`).
+
+TIP: To learn how to add the vertx-hazelcast module and enable distributed session management, as well as how to implement a unique ID generator, see xref:get-started-with-vertx.adoc[Get started with Vert.x].
 
-== Using Vert.x Hazelcast Enterprise Cluster Manager
+== Use Vert.x Hazelcast Enterprise Cluster Manager
 [.enterprise]*Enterprise* 
 
 To use the Vert.x Hazelcast Enterprise Cluster Manager, add the following dependency to your Vert.x application:
@@ -47,7 +49,7 @@ The dependency is located in the Hazelcast private repository, and you need to a
 </repositories>
 ----
 
-Alternatively, if you need to use a snapshot version (you should never use a snapshot version in production,
+Alternatively, if you need to use a snapshot version (note, you should never use a snapshot version in production,
 but it might be useful to test if an issue has been fixed):
 
 [source,xml]
@@ -73,24 +75,24 @@ For other configuration methods see the link:https://vertx.io/docs/vertx-hazelca
 
 === Versioning and Hazelcast compatibility
 
-The Vert.x Hazelcast Enterprise module follows the versioning of Vertx. If you use an `x.y.z` version of Vert.x, you should use an `x.y.z` version of `vertx-hazelcast-enteprise`.
+The Vert.x Hazelcast Enterprise module follows the versioning of Vert.x. If you use an `x.y.z` version of Vert.x, you should use an `x.y.z` version of `vertx-hazelcast-enteprise`.
 
-The `vertx-hazelcast-enteprise` module is compatible with all Hazelcast versions supported at the time of the release of the `vertx-hazelcast-enteprise` module unless stated otherwise.
+The `vertx-hazelcast-enteprise` module is compatible with all Hazelcast versions supported at the time of the release of the `vertx-hazelcast-enteprise` module, unless stated otherwise.
 
 While older versions may work, such configurations are not supported.
 
-== Using Vert.x Hazelcast Cluster Manager
+== Use Vert.x Hazelcast Cluster Manager
 
-See the Vert.x Hazelcast Cluster Manager site for reference documentation for the `vertx-hazelcast` module.
+For reference documentation for the `vertx-hazelcast` module, see the Vert.x Hazelcast Cluster Manager site.
 
 You can also follow our xref:get-started-with-vertx.adoc[Get started with Vert.x guide].
 
-== Using a different Hazelcast version
+== Use a different Hazelcast version
 
-Due to Java compatibility reasons the Vert.x Hazelcast module doesn't depend on the latest version of Hazelcast.
-You can change the Hazelcast dependency to any version of Hazelcast you need, e.g. you can change it to Hazelcast 5.2.x for Java 8 compatibilty, or to the latest.
+Due to Java compatibility reasons, the Vert.x Hazelcast module does not depend on the latest version of Hazelcast.
+You can change the Hazelcast dependency to any version of Hazelcast you need.
 
-NOTE: The old versions may not be supported by Hazelcast anymore and don't receive any patches.
+NOTE: Older versions may not be supported by Hazelcast or receive any patches.
 
 There are multiple ways to replace the transitive dependency. The most reliable way is to exclude the `com.hazelcast:hazelcast` transitive dependency of the `vert-hazelcast` module and add a direct dependency on `com.hazelcast:hazelcast` to the pom.xml of your project.