io.vertx.core.spi.cluster

## Interface ClusterManager

- All Superinterfaces:
    VertxServiceProvider
  All Known Implementing Classes:
    HazelcastClusterManager, IgniteClusterManager, InfinispanClusterManager, ZookeeperClusterManager

      public interface ClusterManager
      extends VertxServiceProvider

  A cluster provider for Vert.x must implement this interface. In order for HA to work correctly, all implementations of this interface MUST be implemented such that: 1. Whenever a node joins or leaves the cluster the registered NodeListener (if any) MUST be called with the appropriate join or leave event. 2. For all nodes that are part of the cluster, the registered NodeListener MUST be called with the exact same sequence of join and leave events on all nodes. 3. For any particular join or leave event that is handled in any NodeListener, anywhere in the cluster, the List of nodes returned by getNodes must be identical. 4. All of the methods in the implementation must return immediately, i.e. they must not block while the operation is being executed. If the underlying implementation does block, then `Vertx.executeBlocking(io.vertx.core.Handler<io.vertx.core.Promise<T>>, boolean, io.vertx.core.Handler<io.vertx.core.AsyncResult<T>>)` should be used to run the operation on a worker.
  Author:
    Tim Fox

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addRegistration(String address, RegistrationInfo registrationInfo, Promise<Void> promise)` Share a new messaging handler registration with other nodes in the cluster.
    `default String` | `clusterHost()` If the cluster manager has its own server for data/membership, this returns the host it is listening to.
    `default String` | `clusterPublicHost()` If the cluster manager has its own server for data/membership, this returns the host it advertises to other nodes.
    `<K,V> void` | `getAsyncMap(String name, Promise<AsyncMap<K,V>> promise)` Return an `AsyncMap` for the given `name`.
    `void` | `getCounter(String name, Promise<Counter> promise)` Return a `Counter` for the given `name`.
    `void` | `getLockWithTimeout(String name, long timeout, Promise<Lock> promise)` Attempts to acquire a `Lock` for the given `name` within `timeout` milliseconds.
    `String` | `getNodeId()` Return the unique node identifier for this node.
    `NodeInfo` | `getNodeInfo()` Get details about this clustered node.
    `void` | `getNodeInfo(String nodeId, Promise<NodeInfo> promise)` Get details about a specific node in the cluster.
    `List<String>` | `getNodes()` Return a list of node identifiers corresponding to the nodes in the cluster.
    `void` | `getRegistrations(String address, Promise<List<RegistrationInfo>> promise)` Get the messaging handler currently registered in the cluster.
    `<K,V> Map<K,V>` | `getSyncMap(String name)` Return a synchronous map for the given `name`.
    `default void` | `init(io.vertx.core.impl.VertxBuilder builder)` Let the provider initialize the Vert.x builder.
    `void` | `init(Vertx vertx, NodeSelector nodeSelector)` Invoked before this cluster node tries to join the cluster.
    `boolean` | `isActive()` Is the cluster manager active?
    `void` | `join(Promise<Void> promise)` Join the cluster.
    `void` | `leave(Promise<Void> promise)` Leave the cluster.
    `void` | `nodeListener(NodeListener listener)` Set a listener that will be called when a node joins or leaves the cluster.
    `void` | `removeRegistration(String address, RegistrationInfo registrationInfo, Promise<Void> promise)` Signal removal of a messaging handler registration to other nodes in the cluster.
    `void` | `setNodeInfo(NodeInfo nodeInfo, Promise<Void> promise)` Store the details about this clustered node.

- - ### Method Detail

    - #### init

          default void init(io.vertx.core.impl.VertxBuilder builder)

      Description copied from interface: `VertxServiceProvider`
      Let the provider initialize the Vert.x builder.
      Specified by:
        `init` in interface `VertxServiceProvider`
      Parameters:
        `builder` - the builder

    - #### init

          void init(Vertx vertx,
                    NodeSelector nodeSelector)

      Invoked before this cluster node tries to join the cluster.

      Implementations must signal the provided `nodeSelector` when messaging handler registrations are added or removed by sending a `RegistrationUpdateEvent` with `NodeSelector.registrationsUpdated(RegistrationUpdateEvent)`.

      Parameters:
        `vertx` - the Vert.x instance
        `nodeSelector` - the `NodeSelector` that must receive `RegistrationUpdateEvent`.

    - #### getAsyncMap

          <K,V> void getAsyncMap(String name,
                                 Promise<AsyncMap<K,V>> promise)

      Return an `AsyncMap` for the given `name`.

    - #### getSyncMap

          <K,V> Map<K,V> getSyncMap(String name)

      Return a synchronous map for the given `name`.

    - #### getLockWithTimeout

          void getLockWithTimeout(String name,
                                  long timeout,
                                  Promise<Lock> promise)

      Attempts to acquire a `Lock` for the given `name` within `timeout` milliseconds.

    - #### getCounter

          void getCounter(String name,
                          Promise<Counter> promise)

      Return a `Counter` for the given `name`.

    - #### getNodeId

          String getNodeId()

      Return the unique node identifier for this node.

    - #### getNodes

          List<String> getNodes()

      Return a list of node identifiers corresponding to the nodes in the cluster.

    - #### nodeListener

          void nodeListener(NodeListener listener)

      Set a listener that will be called when a node joins or leaves the cluster.

    - #### setNodeInfo

          void setNodeInfo(NodeInfo nodeInfo,
                           Promise<Void> promise)

      Store the details about this clustered node.

    - #### getNodeInfo

          NodeInfo getNodeInfo()

      Get details about this clustered node.

    - #### getNodeInfo

          void getNodeInfo(String nodeId,
                           Promise<NodeInfo> promise)

      Get details about a specific node in the cluster.
      Parameters:
        `nodeId` - the clustered node id

    - #### join

          void join(Promise<Void> promise)

      Join the cluster.

    - #### leave

          void leave(Promise<Void> promise)

      Leave the cluster.

    - #### isActive

          boolean isActive()

      Is the cluster manager active?
      Returns:
        true if active, false otherwise

    - #### addRegistration

          void addRegistration(String address,
                               RegistrationInfo registrationInfo,
                               Promise<Void> promise)

      Share a new messaging handler registration with other nodes in the cluster.

    - #### removeRegistration

          void removeRegistration(String address,
                                  RegistrationInfo registrationInfo,
                                  Promise<Void> promise)

      Signal removal of a messaging handler registration to other nodes in the cluster.

    - #### getRegistrations

          void getRegistrations(String address,
                                Promise<List<RegistrationInfo>> promise)

      Get the messaging handler currently registered in the cluster.

    - #### clusterHost

          default String clusterHost()

      If the cluster manager has its own server for data/membership, this returns the host it is listening to. When users don't configure the eventbus cluster host, the value will serve as a default.
      Returns:
        null if the cluster manager does not start a server or the host couldn't be determined

    - #### clusterPublicHost

          default String clusterPublicHost()

      If the cluster manager has its own server for data/membership, this returns the host it advertises to other nodes. When users don't configure the eventbus cluster public host, the value will serve as a default.
      Returns:
        null if the cluster manager does not advertise a host that is different from the cluster host or the public host couldn't be determined

Copyright © 2025 Eclipse. All rights reserved.