/*
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
 * agreements. See the NOTICE file distributed with this work for additional information regarding
 * copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance with the License. You may obtain a
 * copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package org.apache.geode.internal.concurrent;

import java.util.concurrent.ConcurrentMap;

/**
 * Factory to create a value on demand for custom map <code>create</code> methods rather than
 * requiring a pre-built object as in {@link ConcurrentMap#putIfAbsent(Object, Object)} that may be
 * ultimately thrown away.
 * <p>
 * Now also has a bunch of callbacks including for replace/remove etc.
 *
 * @since GemFire 7.0
 *
 * @param <K> the type of key of the map
 * @param <V> the type of value of the map
 * @param <C> the type of context parameter passed to the creation/removal methods
 * @param <P> the type of extra parameter passed to the creation/removal methods
 */
public interface MapCallback<K, V, C, P> {

  /**
   * Token to return from {@link #removeValue} to indicate that remove has to be aborted.
   */
  Object ABORT_REMOVE_TOKEN = new Object();

  /**
   * Token object to indicate that {@link #removeValue} does not need to compare against provided
   * value before removing from segment.
   */
  Object NO_OBJECT_TOKEN = new Object();

  /**
   * Create a new instance of the value object given the key and provided parameters for
   * construction. Invoked by the <code>create</code> method in custom map impls.
   *
   * @param key the key for which the value is being created
   * @param context any context in which this method has been invoked
   * @param createParams parameters, if any, required for construction of a new value object
   *
   * @return the new value to be inserted in the map
   */
  V newValue(K key, C context, P createParams, MapResult result);

  /**
   * Invoked when an existing value in map is read by the <code>create</code> method in custom map
   * impls.
   *
   * @param key the key for which the value is being created
   * @param oldValue the value read by create that will be returned
   * @param context any context in which this method has been invoked
   * @param params parameters, if any, required for construction of value
   *
   * @return updated value to be put in the map, if non-null; if null then retry the map operation
   *         internally
   */
  V updateValue(K key, V oldValue, C context, P params);

  /**
   * Invoked after put is successful with the result of {@link #updateValue}.
   *
   * @param key the key provided to the put() operation
   * @param mapKey the existing key in the map
   * @param newValue the new value to be replaced
   * @param context any callback argument passed to put overload
   */
  void afterUpdate(K key, K mapKey, V newValue, C context);

  /**
   * Returns true if {@link #updateValue} should be invoked else false.
   */
  boolean requiresUpdateValue();

  /**
   * Invoked when an existing value in map is read by read ops.
   *
   * @param oldValue the value read by create that will be returned
   */
  void oldValueRead(V oldValue);

  /**
   * Check if the existing value should be removed by the custom <code>remove</code> methods that
   * take MapCallback as argument.
   *
   * If this method returns null, then proceed with remove as usual, if this method returns
   * {@link #ABORT_REMOVE_TOKEN} then don't do the remove, and if this method returns any other
   * object then replace the map value instead of removing.
   *
   * @param key the key of the entry to be removed from the map
   * @param value the value to be removed
   * @param existingValue the current value in the map
   * @param context any context in which this method has been invoked
   * @param removeParams parameters, if any, to be passed for cleanup of the object
   */
  Object removeValue(Object key, Object value, V existingValue, C context, P removeParams);

  /**
   * Invoked after removal of an entry. Some implementations (CustomEntryConcurrentHashMap) will
   * invoke this for both successful or failed removal (in latter case existingValue will be null)
   * while others invoke this only for successful remove.
   *
   * @param key the key of the entry removed from the map; some implementations
   *        (ConcurrentSkipListMap) will return the actual key in the map while others will provide
   *        the passed key
   * @param value the value to be removed sent to the two argument remove
   * @param existingValue the actual value in map being removed
   * @param context any context in which this method has been invoked
   * @param removeParams parameters, if any, to be passed for cleanup of the object
   */
  void postRemove(Object key, Object value, V existingValue, C context, P removeParams);

  /**
   * Invoked when an existing value in map is read by the <code>replace</code> method in custom map
   * impls, and is to be replaced by a new value.
   *
   * @param key the key for which the value is being replaced
   * @param oldValue the old value passed to replace method
   * @param existingValue the current value in the map
   * @param newValue the new value passed to replace method
   * @param context any context in which this method has been invoked
   * @param params parameters, if any, required for construction of a value
   *
   * @return updated value to be actually put in the map, if non-null; if null then retry the map
   *         operation internally
   */
  V replaceValue(K key, V oldValue, V existingValue, V newValue, C context, P params);

  /**
   * Invoked after the node is found and just before the replace. The replace may still either
   * succeed or fail.
   *
   * @param mapKey the existing key in the map
   * @param newValue the new value to be replaced
   * @param context any context argument passed to replace
   * @param params any callback parameters passed to the replace method
   */
  Object beforeReplace(K mapKey, V newValue, C context, P params);

  /**
   * Invoked after replace is successful and passing it the result of {@link #beforeReplace}.
   *
   * @param mapKey the existing key in the map
   * @param newValue the new value to be replaced
   * @param beforeResult the result of {@link #beforeReplace}
   * @param context any context argument passed to replace overload
   * @param params any callback parameters passed to the replace method
   */
  void afterReplace(K mapKey, V newValue, Object beforeResult, C context, P params);

  /**
   * Invoked after replace fails and passing it the result of {@link #beforeReplace}.
   *
   * @param mapKey the existing key in the map
   * @param newValue the new value to be replaced
   * @param beforeResult the result of {@link #beforeReplace}
   * @param context any context argument passed to replace overload
   * @param params any callback parameters passed to the replace method
   */
  void onReplaceFailed(K mapKey, V newValue, Object beforeResult, C context, P params);

  /**
   * Invoked after replace or delete fails at the end, passing it the intermediate values that were
   * returned by {@link #replaceValue}, {@link #updateValue} or {@link #removeValue} so it can
   * revert any side-affects of those methods.
   *
   * @param key the key for which the operation failed
   * @param oldValue the expected oldValue passed for a replace or remove operation
   * @param updatedValue the new replacement value for the map that failed (possibly changed by
   *        {@link #replaceValue}, {@link #updateValue} or {@link #removeValue} callbacks)
   * @param newValue the new value initially sent to the replace method; if null then it is for a
   *        delete or insert operation
   * @param context any context argument passed to the original method
   * @param params any callback parameters passed to the original method
   *
   * @return value to be returned as result of operation ignoring failure (or null for failure)
   */
  V onOperationFailed(K key, Object oldValue, V updatedValue, V newValue, C context, P params);

  /**
   * Invoked by some implementations like ConcurrentTHashSet to in its toArray.
   */
  void onToArray(C context);
}