/*
 * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.spi.cluster;


import io.vertx.core.Promise;
import io.vertx.core.Vertx;
import io.vertx.core.shareddata.AsyncMap;
import io.vertx.core.shareddata.Counter;
import io.vertx.core.shareddata.Lock;

import java.util.List;
import java.util.Map;

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 should be used to run the operation on a worker. 
Author:
Tim Fox/**
 *
 * 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 {@link io.vertx.core.Vertx#executeBlocking}
 * should be used to run the operation on a worker.
 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
public interface ClusterManager {

  
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). 
Params:
vertx –        the Vert.x instance
nodeSelector – the NodeSelector that must receive RegistrationUpdateEvent./**
   * Invoked before this cluster node tries to join the cluster.
   * <p>
   * Implementations must signal the provided {@code nodeSelector} when messaging handler registrations are added or removed
   * by sending a {@link RegistrationUpdateEvent} with {@link NodeSelector#registrationsUpdated(RegistrationUpdateEvent)}.
   *
   * @param vertx        the Vert.x instance
   * @param nodeSelector the {@link NodeSelector} that must receive {@link RegistrationUpdateEvent}.
   */
  void init(Vertx vertx, NodeSelector nodeSelector);

  
Return an AsyncMap for the given name. /**
   * Return an {@link AsyncMap} for the given {@code name}.
   */
  <K, V> void getAsyncMap(String name, Promise<AsyncMap<K, V>> promise);

  
Return a synchronous map for the given name. /**
   * Return a synchronous map for the given {@code name}.
   */
  <K, V> Map<K, V> getSyncMap(String name);

  
Attempts to acquire a Lock for the given name within timeout milliseconds. /**
   * Attempts to acquire a {@link Lock} for the given {@code name} within {@code timeout} milliseconds.
   */
  void getLockWithTimeout(String name, long timeout, Promise<Lock> promise);

  
Return a Counter for the given name. /**
   * Return a {@link Counter} for the given {@code name}.
   */
  void getCounter(String name, Promise<Counter> promise);

  
Return the unique node identifier for this node.
/**
   * Return the unique node identifier for this node.
   */
  String getNodeId();

  
Return a list of node identifiers corresponding to the nodes in the cluster.
/**
   * Return a list of node identifiers corresponding to the nodes in the cluster.
   */
  List<String> getNodes();

  
Set a listener that will be called when a node joins or leaves the cluster.
/**
   * Set a listener that will be called when a node joins or leaves the cluster.
   */
  void nodeListener(NodeListener listener);

  
Store the details about this clustered node.
/**
   * Store the details about this clustered node.
   */
  void setNodeInfo(NodeInfo nodeInfo, Promise<Void> promise);

  
Get details about this clustered node.
/**
   * Get details about this clustered node.
   */
  NodeInfo getNodeInfo();

  
Get details about a specific node in the cluster.
Params:
nodeId – the clustered node id/**
   * Get details about a specific node in the cluster.
   *
   * @param nodeId the clustered node id
   */
  void getNodeInfo(String nodeId, Promise<NodeInfo> promise);

  
Join the cluster.
/**
   * Join the cluster.
   */
  void join(Promise<Void> promise);

  
Leave the cluster.
/**
   * Leave the cluster.
   */
  void leave(Promise<Void> promise);

  
Is the cluster manager active?
Returns:
true if active, false otherwise/**
   * Is the cluster manager active?
   *
   * @return true if active, false otherwise
   */
  boolean isActive();

  
Share a new messaging handler registration with other nodes in the cluster.
/**
   * Share a new messaging handler registration with other nodes in the cluster.
   */
  void addRegistration(String address, RegistrationInfo registrationInfo, Promise<Void> promise);

  
Signal removal of a messaging handler registration to other nodes in the cluster.
/**
   * Signal removal of a messaging handler registration to other nodes in the cluster.
   */
  void removeRegistration(String address, RegistrationInfo registrationInfo, Promise<Void> promise);

  
Get the messaging handler currently registered in the cluster.
/**
   * Get the messaging handler currently registered in the cluster.
   */
  void getRegistrations(String address, Promise<List<RegistrationInfo>> promise);

  
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/**
   * 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.
   *
   * @return null if the cluster manager does not start a server or the host couldn't be determined
   */
  default String clusterHost() {
    return null;
  }

  
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/**
   * 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.
   *
   * @return 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
   */
  default String clusterPublicHost() {
    return null;
  }
}