/*
 * 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.shareddata;

import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.Promise;

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


/**
 * An asynchronous map.
 * <p>
 * {@link AsyncMap} does <em>not</em> allow {@code null} to be used as a key or value.
 *
 * @implSpec Implementations of the interface must handle {@link io.vertx.core.shareddata.impl.ClusterSerializable}
 * implementing objects.
 * @author <a href="http://tfox.org">Tim Fox</a>
 */
@VertxGen
public interface AsyncMap<K, V> {

  /**
   * Get a value from the map, asynchronously.
   *
   * @param k  the key
   * @param resultHandler - this will be called some time later with the async result.
   */
  default void get(K k, Handler<AsyncResult<@Nullable V>> resultHandler) {
    get(k).setHandler(resultHandler);
  }

  /**
   * Same as {@link #get(K, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<@Nullable V> get(K k);

  /**
   * Put a value in the map, asynchronously.
   *
   * @param k  the key
   * @param v  the value
   * @param completionHandler - this will be called some time later to signify the value has been put
   */
  default void put(K k, V v, Handler<AsyncResult<Void>> completionHandler) {
    put(k, v).setHandler(completionHandler);
  }

  /**
   * Same as {@link #put(K, V, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<Void> put(K k, V v);

  /**
   * Like {@link #put} but specifying a time to live for the entry. Entry will expire and get evicted after the
   * ttl.
   *
   * @param k  the key
   * @param v  the value
   * @param ttl  The time to live (in ms) for the entry
   * @param completionHandler  the handler
   */
  default void put(K k, V v, long ttl, Handler<AsyncResult<Void>> completionHandler) {
    put(k, v, ttl).setHandler(completionHandler);
  }

  /**
   * Same as {@link #put(K, V, long, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<Void> put(K k, V v, long ttl);

  /**
   * Put the entry only if there is no entry with the key already present. If key already present then the existing
   * value will be returned to the handler, otherwise null.
   *
   * @param k  the key
   * @param v  the value
   * @param completionHandler  the handler
   */
  default void putIfAbsent(K k, V v, Handler<AsyncResult<@Nullable V>> completionHandler) {
    putIfAbsent(k, v).setHandler(completionHandler);
  }

  /**
   * Same as {@link #putIfAbsent(K, V, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<@Nullable V> putIfAbsent(K k, V v);

  /**
   * Link {@link #putIfAbsent} but specifying a time to live for the entry. Entry will expire and get evicted
   * after the ttl.
   *
   * @param k  the key
   * @param v  the value
   * @param ttl  The time to live (in ms) for the entry
   * @param completionHandler  the handler
   */
  default void putIfAbsent(K k, V v, long ttl, Handler<AsyncResult<@Nullable V>> completionHandler) {
    putIfAbsent(k, v, ttl).setHandler(completionHandler);
  }

  /**
   * Same as {@link #putIfAbsent(K, V, long, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<@Nullable V> putIfAbsent(K k, V v, long ttl);

  /**
   * Remove a value from the map, asynchronously.
   *
   * @param k  the key
   * @param resultHandler - this will be called some time later to signify the value has been removed
   */
  default void remove(K k, Handler<AsyncResult<@Nullable V>> resultHandler) {
    remove(k).setHandler(resultHandler);
  }

  /**
   * Same as {@link #remove(K, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<@Nullable V> remove(K k);

  /**
   * Remove a value from the map, only if entry already exists with same value.
   *
   * @param k  the key
   * @param v  the value
   * @param resultHandler - this will be called some time later to signify the value has been removed
   */
  default void removeIfPresent(K k, V v, Handler<AsyncResult<Boolean>> resultHandler) {
    removeIfPresent(k, v).setHandler(resultHandler);
  }

  /**
   * Same as {@link #removeIfPresent(K, V, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<Boolean> removeIfPresent(K k, V v);

  /**
   * Replace the entry only if it is currently mapped to some value
   *
   * @param k  the key
   * @param v  the new value
   * @param resultHandler  the result handler will be passed the previous value
   */
  default void replace(K k, V v, Handler<AsyncResult<@Nullable V>> resultHandler) {
    replace(k, v).setHandler(resultHandler);
  }

  /**
   * Same as {@link #replace(K, V, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<@Nullable V> replace(K k, V v);

  /**
   * Replace the entry only if it is currently mapped to a specific value
   *
   * @param k  the key
   * @param oldValue  the existing value
   * @param newValue  the new value
   * @param resultHandler the result handler
   */
  default void replaceIfPresent(K k, V oldValue, V newValue, Handler<AsyncResult<Boolean>> resultHandler) {
    replaceIfPresent(k, oldValue, newValue).setHandler(resultHandler);
  }

  /**
   * Same as {@link #replaceIfPresent(K, V, V, Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<Boolean> replaceIfPresent(K k, V oldValue, V newValue);

  /**
   * Clear all entries in the map
   *
   * @param resultHandler  called on completion
   */
  default void clear(Handler<AsyncResult<Void>> resultHandler) {
    clear().setHandler(resultHandler);
  }

  /**
   * Same as {@link #clear(Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<Void> clear();

  /**
   * Provide the number of entries in the map
   *
   * @param resultHandler  handler which will receive the number of entries
   */
  default void size(Handler<AsyncResult<Integer>> resultHandler) {
    size().setHandler(resultHandler);
  }

  /**
   * Same as {@link #size(Handler)} but returns a {@code Future} of the asynchronous result
   */
  Future<Integer> size();

  /**
   * Get the keys of the map, asynchronously.
   * <p>
   * Use this method with care as the map may contain a large number of keys,
   * which may not fit entirely in memory of a single node.
   * In this case, the invocation will result in an {@link OutOfMemoryError}.
   *
   * @param resultHandler invoked when the operation completes
   */
  @GenIgnore
  default void keys(Handler<AsyncResult<Set<K>>> resultHandler) {
    keys().setHandler(resultHandler);
  }

  /**
   * Same as {@link #keys(Handler)} but returns a {@code Future} of the asynchronous result
   */
  @GenIgnore
  Future<Set<K>> keys();

  /**
   * Get the values of the map, asynchronously.
   * <p>
   * Use this method with care as the map may contain a large number of values,
   * which may not fit entirely in memory of a single node.
   * In this case, the invocation will result in an {@link OutOfMemoryError}.
   *
   * @param resultHandler invoked when the operation completes
   */
  @GenIgnore
  default void values(Handler<AsyncResult<List<V>>> resultHandler) {
    values().setHandler(resultHandler);
  }

  /**
   * Same as {@link #values(Handler)} but returns a {@code Future} of the asynchronous result
   */
  @GenIgnore
  Future<List<V>> values();

  /**
   * Get the entries of the map, asynchronously.
   * <p>
   * Use this method with care as the map may contain a large number of entries,
   * which may not fit entirely in memory of a single node.
   * In this case, the invocation will result in an {@link OutOfMemoryError}.
   *
   * @param resultHandler invoked when the operation completes
   */
  @GenIgnore
  default void entries(Handler<AsyncResult<Map<K, V>>> resultHandler) {
    entries().setHandler(resultHandler);
  }

  /**
   * Same as {@link #entries(Handler)} but returns a {@code Future} of the asynchronous result
   */
  @GenIgnore
  Future<Map<K, V>> entries();
}
