public final class
Hashing
extends
Object
Static methods to obtain
HashFunction
instances, and other static hashing-related
utilities.
A comparison of the various hash functions can be found
here
.
static
HashFunction
adler32
()
Returns a hash function implementing the Adler-32 checksum algorithm (32 hash bits) by
delegating to the
Adler32
Checksum
.
static
HashCode
combineOrdered
(
Iterable
<
HashCode
> hashCodes)
Returns a hash code, having the same bit length as each of the input hash codes, that combines
the information of these hash codes in an ordered fashion.
static
HashCode
combineUnordered
(
Iterable
<
HashCode
> hashCodes)
Returns a hash code, having the same bit length as each of the input hash codes, that combines
the information of these hash codes in an unordered fashion.
static
HashFunction
concatenating
(
HashFunction
first,
HashFunction
second,
HashFunction
... rest)
Returns a hash function which computes its hash code by concatenating the hash codes of the
underlying hash functions together.
static
HashFunction
concatenating
(
Iterable
<
HashFunction
> hashFunctions)
Returns a hash function which computes its hash code by concatenating the hash codes of the
underlying hash functions together.
static int
consistentHash
(
HashCode
hashCode,
int buckets)
Assigns to
hashCode
a "bucket" in the range
[0, buckets)
, in a uniform manner
that minimizes the need for remapping as
buckets
grows.
static int
consistentHash
(long input,
int buckets)
Assigns to
input
a "bucket" in the range
[0, buckets)
, in a uniform manner that
minimizes the need for remapping as
buckets
grows.
static
HashFunction
crc32
()
Returns a hash function implementing the CRC-32 checksum algorithm (32 hash bits) by delegating
to the
CRC32
Checksum
.
static
HashFunction
crc32c
()
Returns a hash function implementing the CRC32C checksum algorithm (32 hash bits) as described
by RFC 3720, Section 12.1.
static
HashFunction
farmHashFingerprint64
()
Returns a hash function implementing FarmHash's Fingerprint64, an open-source algorithm.
static
HashFunction
goodFastHash
(int minimumBits)
Returns a general-purpose,
temporary-use
, non-cryptographic hash function.
static
HashFunction
hmacMd5
(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
MD5 (128 hash bits) hash function and a
SecretSpecKey
created from the given byte array
and the MD5 algorithm.
static
HashFunction
hmacMd5
(
Key
key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
MD5 (128 hash bits) hash function and the given secret key.
static
HashFunction
hmacSha1
(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-1 (160 hash bits) hash function and a
SecretSpecKey
created from the given byte
array and the SHA-1 algorithm.
static
HashFunction
hmacSha1
(
Key
key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-1 (160 hash bits) hash function and the given secret key.
static
HashFunction
hmacSha256
(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-256 (256 hash bits) hash function and a
SecretSpecKey
created from the given byte
array and the SHA-256 algorithm.
static
HashFunction
hmacSha256
(
Key
key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-256 (256 hash bits) hash function and the given secret key.
static
HashFunction
hmacSha512
(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-512 (512 hash bits) hash function and a
SecretSpecKey
created from the given byte
array and the SHA-512 algorithm.
static
HashFunction
hmacSha512
(
Key
key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-512 (512 hash bits) hash function and the given secret key.
static
HashFunction
md5
()
Returns a hash function implementing the MD5 hash algorithm (128 hash bits) by delegating to
the MD5
MessageDigest
.
static
HashFunction
murmur3_128
()
static
HashFunction
murmur3_128
(int seed)
static
HashFunction
murmur3_32
()
static
HashFunction
murmur3_32
(int seed)
static
HashFunction
sha1
()
Returns a hash function implementing the SHA-1 algorithm (160 hash bits) by delegating to the
SHA-1
MessageDigest
.
static
HashFunction
sha256
()
Returns a hash function implementing the SHA-256 algorithm (256 hash bits) by delegating to the
SHA-256
MessageDigest
.
static
HashFunction
sha384
()
Returns a hash function implementing the SHA-384 algorithm (384 hash bits) by delegating to the
SHA-384
MessageDigest
.
static
HashFunction
sha512
()
Returns a hash function implementing the SHA-512 algorithm (512 hash bits) by delegating to the
SHA-512
MessageDigest
.
static
HashFunction
sipHash24
()
static
HashFunction
sipHash24
(long k0,
long k1)
goodFastHash
public static HashFunction goodFastHash(int minimumBits)
Returns a general-purpose,
temporary-use
, non-cryptographic hash function. The algorithm
the returned function implements is unspecified and subject to change without notice.
Warning:
a new random seed for these functions is chosen each time the
Hashing
class is loaded.
Do not use this method
if hash codes may escape the current
process in any way, for example being sent over RPC, or saved to disk.
Repeated calls to this method on the same loaded
Hashing
class, using the same value
for
minimumBits
, will return identically-behaving
HashFunction
instances.
minimumBits
- a positive integer (can be arbitrarily large)
Returns:
a hash function, described above, that produces hash codes of length
minimumBits
or greater
murmur3_32
public static HashFunction murmur3_32(int seed)
Returns a hash function implementing the
32-bit murmur3
algorithm, x86 variant
(little-endian variant), using the given seed value.
The exact C++ equivalent is the MurmurHash3_x86_32 function (Murmur3A).
murmur3_32
public static HashFunction murmur3_32()
Returns a hash function implementing the
32-bit murmur3
algorithm, x86 variant
(little-endian variant), using a seed value of zero.
The exact C++ equivalent is the MurmurHash3_x86_32 function (Murmur3A).
murmur3_128
public static HashFunction murmur3_128(int seed)
Returns a hash function implementing the
128-bit murmur3
algorithm, x64 variant
(little-endian variant), using the given seed value.
The exact C++ equivalent is the MurmurHash3_x64_128 function (Murmur3F).
murmur3_128
public static HashFunction murmur3_128()
Returns a hash function implementing the
128-bit murmur3
algorithm, x64 variant
(little-endian variant), using a seed value of zero.
The exact C++ equivalent is the MurmurHash3_x64_128 function (Murmur3F).
sipHash24
public static HashFunction sipHash24()
Since:
public static HashFunction sipHash24(long k0,
long k1)
Since:
public static HashFunction md5()
Returns a hash function implementing the MD5 hash algorithm (128 hash bits) by delegating to
the MD5
MessageDigest
.
Warning:
MD5 is not cryptographically secure or collision-resistant and is not
recommended for use in new code. It should be used for legacy compatibility reasons only.
Please consider using a hash function in the SHA-2 family of functions (e.g., SHA-256).
public static HashFunction sha1()
Returns a hash function implementing the SHA-1 algorithm (160 hash bits) by delegating to the
SHA-1
MessageDigest
.
Warning:
SHA1 is not cryptographically secure and is not recommended for use in new
code. It should be used for legacy compatibility reasons only. Please consider using a hash
function in the SHA-2 family of functions (e.g., SHA-256).
sha256
public static HashFunction sha256()
Returns a hash function implementing the SHA-256 algorithm (256 hash bits) by delegating to the
SHA-256
MessageDigest
.
sha384
public static HashFunction sha384()
Returns a hash function implementing the SHA-384 algorithm (384 hash bits) by delegating to the
SHA-384
MessageDigest
.
sha512
public static HashFunction sha512()
Returns a hash function implementing the SHA-512 algorithm (512 hash bits) by delegating to the
SHA-512
MessageDigest
.
hmacMd5
public static HashFunction hmacMd5(Key key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
MD5 (128 hash bits) hash function and the given secret key.
Parameters:
key
- the secret key
Throws:
IllegalArgumentException
- if the given key is inappropriate for initializing this MAC
Since:
hmacMd5
public static HashFunction hmacMd5(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
MD5 (128 hash bits) hash function and a
SecretSpecKey
created from the given byte array
and the MD5 algorithm.
Parameters:
key
- the key material of the secret key
Since:
hmacSha1
public static HashFunction hmacSha1(Key key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-1 (160 hash bits) hash function and the given secret key.
Parameters:
key
- the secret key
Throws:
IllegalArgumentException
- if the given key is inappropriate for initializing this MAC
Since:
hmacSha1
public static HashFunction hmacSha1(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-1 (160 hash bits) hash function and a
SecretSpecKey
created from the given byte
array and the SHA-1 algorithm.
Parameters:
key
- the key material of the secret key
Since:
hmacSha256
public static HashFunction hmacSha256(Key key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-256 (256 hash bits) hash function and the given secret key.
Parameters:
key
- the secret key
Throws:
IllegalArgumentException
- if the given key is inappropriate for initializing this MAC
Since:
hmacSha256
public static HashFunction hmacSha256(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-256 (256 hash bits) hash function and a
SecretSpecKey
created from the given byte
array and the SHA-256 algorithm.
Parameters:
key
- the key material of the secret key
Since:
hmacSha512
public static HashFunction hmacSha512(Key key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-512 (512 hash bits) hash function and the given secret key.
Parameters:
key
- the secret key
Throws:
IllegalArgumentException
- if the given key is inappropriate for initializing this MAC
Since:
hmacSha512
public static HashFunction hmacSha512(byte[] key)
Returns a hash function implementing the Message Authentication Code (MAC) algorithm, using the
SHA-512 (512 hash bits) hash function and a
SecretSpecKey
created from the given byte
array and the SHA-512 algorithm.
Parameters:
key
- the key material of the secret key
Since:
crc32c
public static HashFunction crc32c()
Returns a hash function implementing the CRC32C checksum algorithm (32 hash bits) as described
by RFC 3720, Section 12.1.
Since:
crc32
public static HashFunction crc32()
Since:
adler32
public static HashFunction adler32()
Since:
farmHashFingerprint64
public static HashFunction farmHashFingerprint64()
Returns a hash function implementing FarmHash's Fingerprint64, an open-source algorithm.
This is designed for generating persistent fingerprints of strings. It isn't
cryptographically secure, but it produces a high-quality hash with fewer collisions than some
alternatives we've used in the past. FarmHashFingerprints generated using this are byte-wise
identical to those created using the C++ version, but note that this uses unsigned integers
(see
UnsignedInts
). Comparisons between the two should
take this into account.
public static int consistentHash(HashCode hashCode,
int buckets)
Assigns to
hashCode
a "bucket" in the range
[0, buckets)
, in a uniform manner
that minimizes the need for remapping as
buckets
grows. That is,
consistentHash(h, n)
equals:
n - 1
, with approximate probability
1/n
consistentHash(h, n - 1)
, otherwise (probability
1 - 1/n
)
This method is suitable for the common use case of dividing work among buckets that meet the
following conditions:
You want to assign the same fraction of inputs to each bucket.
When you reduce the number of buckets, you can accept that the most recently added buckets
will be removed first. More concretely, if you are dividing traffic among tasks, you can
decrease the number of tasks from 15 and 10, killing off the final 5 tasks, and
consistentHash
will handle it. If, however, you are dividing traffic among servers
alpha
,
bravo
, and
charlie
and you occasionally need to take each of the
servers offline,
consistentHash
will be a poor fit: It provides no way for you to
specify which of the three buckets is disappearing. Thus, if your buckets change from
[alpha, bravo, charlie]
to
[bravo, charlie]
, it will assign all the old
alpha
traffic to
bravo
and all the old
bravo
traffic to
charlie
, rather than
letting
bravo
keep its traffic.
See the
Wikipedia article on
consistent hashing
for more information.
public static int consistentHash(long input,
int buckets)
Assigns to
input
a "bucket" in the range
[0, buckets)
, in a uniform manner that
minimizes the need for remapping as
buckets
grows. That is,
consistentHash(h,
n)
equals:
n - 1
, with approximate probability
1/n
consistentHash(h, n - 1)
, otherwise (probability
1 - 1/n
)
This method is suitable for the common use case of dividing work among buckets that meet the
following conditions:
You want to assign the same fraction of inputs to each bucket.
When you reduce the number of buckets, you can accept that the most recently added buckets
will be removed first. More concretely, if you are dividing traffic among tasks, you can
decrease the number of tasks from 15 and 10, killing off the final 5 tasks, and
consistentHash
will handle it. If, however, you are dividing traffic among servers
alpha
,
bravo
, and
charlie
and you occasionally need to take each of the
servers offline,
consistentHash
will be a poor fit: It provides no way for you to
specify which of the three buckets is disappearing. Thus, if your buckets change from
[alpha, bravo, charlie]
to
[bravo, charlie]
, it will assign all the old
alpha
traffic to
bravo
and all the old
bravo
traffic to
charlie
, rather than
letting
bravo
keep its traffic.
See the
Wikipedia article on
consistent hashing
for more information.
combineOrdered
public static HashCode combineOrdered(Iterable<HashCode> hashCodes)
Returns a hash code, having the same bit length as each of the input hash codes, that combines
the information of these hash codes in an ordered fashion. That is, whenever two equal hash
codes are produced by two calls to this method, it is
as likely as possible
that each
was computed from the
same
input hash codes in the
same
order.
Throws:
IllegalArgumentException
- if
hashCodes
is empty, or the hash codes do not all
have the same bit length
combineUnordered
public static HashCode combineUnordered(Iterable<HashCode> hashCodes)
Returns a hash code, having the same bit length as each of the input hash codes, that combines
the information of these hash codes in an unordered fashion. That is, whenever two equal hash
codes are produced by two calls to this method, it is
as likely as possible
that each
was computed from the
same
input hash codes in
some
order.
Throws:
IllegalArgumentException
- if
hashCodes
is empty, or the hash codes do not all
have the same bit length
concatenating
public static HashFunction concatenating(HashFunction first,
HashFunction second,
HashFunction... rest)
Returns a hash function which computes its hash code by concatenating the hash codes of the
underlying hash functions together. This can be useful if you need to generate hash codes of a
specific length.
For example, if you need 1024-bit hash codes, you could join two
sha512()
hash
functions together:
Hashing.concatenating(Hashing.sha512(), Hashing.sha512())
.
concatenating
public static HashFunction concatenating(Iterable<HashFunction> hashFunctions)
Returns a hash function which computes its hash code by concatenating the hash codes of the
underlying hash functions together. This can be useful if you need to generate hash codes of a
specific length.
For example, if you need 1024-bit hash codes, you could join two
sha512()
hash
functions together:
Hashing.concatenating(Hashing.sha512(), Hashing.sha512())
.
