Module hash4j
Package com.dynatrace.hash4j.consistent

Interface ConsistentBucketSetHasher

public interface ConsistentBucketSetHasher
A hash function that maps a given hash consistently to a bucket from a set of buckets.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    addBucket()
    Creates a new bucket and returns the ID of the new bucket.
    int
    getBucket(long hash)
    Returns a bucket ID based on a 64-bit hash value of the key.
    int[]
    getBuckets()
    Returns an array of all bucket IDs.
    int
    getNumBuckets()
    Returns the total number of buckets.
    byte[]
    getState()
    Returns the internal state as byte array.
    boolean
    removeBucket(int bucketId)
    Removes the bucket with given ID.
    ConsistentBucketSetHasher
    setState(byte[] state)
    Sets the internal state of a ConsistentBucketSetHasher to the state held by the given byte array which was obtained from getState().

  • Method Details

    • addBucket

      int addBucket()
      Creates a new bucket and returns the ID of the new bucket.

      Note: The ID can be the same as that of a previously removed bucket.

      Returns:
      a bucket ID

    • removeBucket

      boolean removeBucket(int bucketId)
      Removes the bucket with given ID.
      Parameters:
      bucketId - the bucket ID
      Returns:
      true if there was a bucket with given ID

    • getBucket

      int getBucket(long hash)
      Returns a bucket ID based on a 64-bit hash value of the key.

      The returned bucket index is uniformly distributed. If the buckets are added or removed, remapping to other bucket indices is minimized.

      This function is not thread-safe!

      Parameters:
      hash - a 64-bit hash value of the key
      Returns:
      the bucket ID

    • getBuckets

      int[] getBuckets()
      Returns an array of all bucket IDs. In general, there is no particular ordering of IDs. However, the ordering is reproducible, if the same history of addBucket() and removeBucket(int) calls are applied to a new instance.
      Returns:
      an array of all bucket IDs

    • getNumBuckets

      int getNumBuckets()
      Returns the total number of buckets.
      Returns:
      the total number of buckets

    • getState

      byte[] getState()
      Returns the internal state as byte array.

      This functions allows to copy the internal state and propagate it to other instances in a distributed environment to enable distributed consistent mapping of keys to buckets.

      Returns:
      a new byte array holding the state

    • setState

      ConsistentBucketSetHasher setState(byte[] state)
      Sets the internal state of a ConsistentBucketSetHasher to the state held by the given byte array which was obtained from getState().

      Note: There is no guaranteed compatibility of states across different Hash4j library versions!

      Parameters:
      state - a byte array holding the state
      Returns:
      a reference to this
      Throws:
      IllegalArgumentException - if the state is invalid