Integrate with Vert.x

6.0-SNAPSHOT 5.5 5.4 5.3 5.2 5.1 5.0

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 Hazelcast Cluster Manager.

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

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 Edition 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).

Using Vert.x Hazelcast Enterprise Cluster Manager

Enterprise

To use the Vert.x Hazelcast Enterprise Cluster Manager, add the following dependency to your Vert.x application:

<dependency>
  <groupId>com.hazelcast</groupId>
  <artifactId>vertx-hazelcast-enterprise</artifactId>
  <version>5.0.0-SNAPSHOT</version>
</dependency>

The dependency is located in the Hazelcast private repository, and you need to add that as well:

<repositories>
  <repository>
    <id>hazelcast-private-repository</id>
    <name>Hazelcast Private Repository</name>
    <url>https://repository.hazelcast.com/release/</url>
  </repository>
</repositories>

Alternatively, if you need to use a snapshot version:

<repositories>
  <repository>
    <id>hazelcast-private-snapshot-repository</id>
    <name>Hazelcast Private Snapshot Repository</name>
    <url>https://repository.hazelcast.com/snapshot/</url>
  </repository>
</repositories>

To enable clustering, start your Vert.x application with the -cluster parameter.

Configuration

Provide a file named cluster.xml on your classpath to configure a Hazelcast instance used by Vert.x.

To take advantage of the Lock and Counter data structures backed by the CP subsystem, you need to enable the CP Subsytem.

For other configuration methods see the Vert.x documentation.

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 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

See the Vert.x Hazelcast Cluster Manager site for reference documentation for the vertx-hazelcast module.

You can also follow our Get started with Vert.x guide.

Using 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.

The old versions may not be supported by Hazelcast anymore and don’t 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.

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-hazelcast</artifactId>
  <exclusions>
    <exclusion>
      <groupId>com.hazelcast</groupId>
      <artifactId>hazelcast</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>com.hazelcast</groupId>
  <artifactId>hazelcast</artifactId>
  <version>5.5.0</version>
</dependency>

Similarly, for vertx-hazelcast-enterprise:

<dependency>
  <groupId>com.hazelcast</groupId>
  <artifactId>vertx-hazelcast-enterprise</artifactId>
  <exclusions>
    <exclusion>
      <groupId>com.hazelcast</groupId>
      <artifactId>hazelcast</artifactId>
    </exclusion>
  </exclusions>
</dependency>
<dependency>
  <groupId>com.hazelcast</groupId>
  <artifactId>hazelcast</artifactId>
  <version>5.5.0</version>
</dependency>
lifebuoy

Help and support