Building a Vert.x Clustered Event Bus with Hazelcast: From Setup to Verification

Problem: Scaling Vert.x Verticles Across JVMs

When a Vert.x application grows beyond a single JVM, you need a way for verticles on different nodes to exchange messages without writing custom networking code. The clustered event bus solves this by transparently forwarding messages over a shared Hazelcast cluster.

Solution Overview: Enable Clustering with Hazelcast

Adding the Dependency

Include the Hazelcast library that matches the Vert.x version you are using. For Vert.x 4.x, the coordinates are:

io.vertx:vertx-hazelcast:4.4.5

Add it to your build (Maven example):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-hazelcast</artifactId>
  <version>4.4.5</version>
</dependency>

Configuring VertxOptions

Tell Vert.x to start in clustered mode and optionally point it at a Hazelcast XML file.

VertxOptions opts = new VertxOptions()
    .setClustered(true)
    .setHazelcastConfigPath("hazelcast.xml");
Vertx.clusteredVertx(opts, res -> {
  if (res.succeeded()) {
    Vertx vertx = res.result();
    // deploy verticles here
  } else {
    System.err.println("Failed to form cluster: " + res.cause());
  }
});

If you omit the path, Hazelcast uses its default configuration (multicast discovery).

Worked Example: Chat Verticles

Sender Verticle

public class SenderVerticle extends AbstractVerticle {
  @Override
  public void start() {
    vertx.setPeriodic(1000, id -> {
      vertx.eventBus().publish("chat", "ping-" + System.currentTimeMillis());
    });
  }
}

Receiver Verticle

public class ReceiverVerticle extends AbstractVerticle {
  @Override
  public void start() {
    vertx.eventBus().consumer("chat", msg -> {
      System.out.println("Received: " + msg.body());
    });
  }
}

Running the Two Nodes

1. Build a fat JAR that contains your verticles, Vert.x core, and the Hazelcast dependency.
2. Open two terminal windows (you need read/execute permission on the JAR).
3. In the first terminal, start node A:

java -jar my-vertx-app.jar run SenderVerticle -clustered -hazelcast-config hazelcast.xml

1. In the second terminal, start node B:

java -jar my-vertx-app.jar run ReceiverVerticle -clustered -hazelcast-config hazelcast.xml

You should see the receiver printing a line roughly every second. No further configuration is required; the event bus forwards the publish/subscribe across the Hazelcast cluster.

Trade‑offs and Limitations

• Each message incurs a Hazelcast network round‑trip, adding latency compared to an in‑VM bus.
• The Hazelcast distributed data structures consume extra heap; monitor memory usage as traffic grows.
• All nodes must run the same Hazelcast version (or a compatible range) and agree on the discovery mechanism (multicast or TCP). A mismatch can cause split‑brain or failed cluster formation.

Practical Verification Steps

1. Check the logs of each node for the line "Successfully connected to Hazelcast cluster" (or similar) after startup.
2. Verify that the receiver’s output matches the expected frequency; you can count lines over a minute to ensure no loss.
3. Stop one node (Ctrl‑C) and confirm the other continues to log locally‑only messages (if any) without errors.
4. Restart the stopped node; after it rejoins the cluster, the receiver should resume receiving messages from the sender without manual re‑deployment.

Actionable Closing

Start with the minimal configuration shown above, run the two‑node test on a single machine, and observe the message flow. Once you are confident the cluster forms correctly, move to a staging environment, enable Hazelcast management center or JMX to monitor cluster size, memory, and message throughput. Adjust the Hazelcast XML (e.g., set TCP‑only discovery, tune backup counts) to match your production network and reliability requirements.