/*
 * JBoss, Home of Professional Open Source
 * Copyright 2010 Red Hat Inc. and/or its affiliates and other
 * contributors as indicated by the @author tags. All rights reserved.
 * See the copyright.txt in the distribution for a full listing of
 * individual contributors.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.infinispan.distribution.ch;

import org.infinispan.remoting.transport.Address;

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

/**
 * A consistent hash algorithm implementation.  Implementations would typically be constructed via reflection so should
 * implement a public, no-arg constructor.
 *
 * @author Manik Surtani
 * @author Mircea.Markus@jboss.com
 * @since 4.0
 */
public interface ConsistentHash {

   /**
    * Sets the collection of cache addresses in the cluster.  The implementation should store these internally and use
    * these to locate keys.
    *
    * @param caches A set of unique caches in cluster.
    */
   void setCaches(Set<Address> caches);

   /**
    * Should return a collection of cache addresses in the cluster.
    *
    * @return set of unique of cache addresses
    */
   Set<Address> getCaches();

   /**
    * Locates a key, given a replication count (number of copies).
    *
    * @param key       key to locate
    * @param replCount replication count (number of copies)
    * @return a list of addresses where the key resides, where this list is a subset of the addresses set in {@link
    *         #setCaches(java.util.Set)}.  Should never be null, and should contain replCount elements or the max
    *         number of caches available, whichever is smaller.
    */
   List<Address> locate(Object key, int replCount);

   /**
    * The logical equivalent of calling {@link #locate(Object, int)} multiple times for each key in the collection of
    * keys. Implementations may be optimised for such a bulk lookup, or may just repeatedly call {@link #locate(Object,
    * int)}.
    *
    * @param keys      keys to locate
    * @param replCount replication count (number of copies) for each key
    * @return Map of locations, keyed on key.
    */
   Map<Object, List<Address>> locateAll(Collection<Object> keys, int replCount);

   /**
    * Test to see whether a key is mapped to a given address.
    * @param a address to test
    * @param key key to test
    * @param replCount repl count
    * @return true if the key is mapped to the address; false otherwise
    */
   boolean isKeyLocalToAddress(Address a, Object key, int replCount);

   /**
    * Returns a list of values between 0 and the hash space limit, or hash id,
    * for a particular address. If virtual nodes are disabled, the list will
    * only contain a single element, whereas if virtual nodes are enabled, this
    * list's size will be the number of virtual nodes configured. If there are
    * no hash ids for that address, it returns an empty list.
    *
    * @return A list of N size where N is the configured number of virtual
    *         nodes, or an empty list if there're no hash ids associated with
    *         the address.
    */
   List<Integer> getHashIds(Address a);

   /**
    * Returns the nodes that need will replicate their state if the specified node crashes. The return collection
    * should contain all the nodes that backup-ed on leaver and one of the nodes which acted as a backup for the leaver .
    * <p>
    * Pre: leaver must be present in the caches known to this CH, as returned by {@link #getCaches()}
    * @param leaver the node that leaves the cluster
    * @param replCount
    * @deprecated No longer supported. This method doesn't make sense with virtual nodes enabled.
    */
   @Deprecated
   List<Address> getStateProvidersOnLeave(Address leaver, int replCount);

   /**
    * Returns the nodes that would act as state providers when a new node joins:
    * - the nodes for which the joiner is a backup
    * - the nodes that held joiner's state
    * @deprecated No longer supported. This method doesn't make sense with virtual nodes enabled.
    */
   @Deprecated
   List<Address> getStateProvidersOnJoin(Address joiner, int replCount);

   /**
    * Returns the nodes that backup data for the supplied node including the node itself.
    * @deprecated No longer supported. This method doesn't make sense with virtual nodes enabled.
    */
   @Deprecated
   List<Address> getBackupsForNode(Address node, int replCount);

   /**
    * Should be equivalent to return the first element of {@link #locate(Object, int)}.
    * Useful as a performance optimization, as this is a frequently needed information.
    * @param key key to locate
    * @return
    */
   Address primaryLocation(Object key);
}