@Beta public final class Hashing extends Object
HashFunction
instances, and other static hashing-related
utilities.
A comparison of the various hash functions can be found here.
Modifier and Type | Method and Description |
---|---|
static HashFunction |
adler32()
Returns a hash function implementing the Adler-32 checksum algorithm (32 hash bits).
|
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).
|
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
SecretKeySpec 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
SecretKeySpec 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
SecretKeySpec 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
SecretKeySpec 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()
Deprecated.
If you must interoperate with a system that requires MD5, then use this method,
despite its deprecation. But if you can choose your hash function, avoid MD5, which is
neither fast nor secure. As of January 2017, we suggest:
|
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.
|
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.
|
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.
|
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.
|
static HashFunction |
sha1()
Deprecated.
If you must interoperate with a system that requires SHA-1, then use this method,
despite its deprecation. But if you can choose your hash function, avoid SHA-1, which is
neither fast nor secure. As of January 2017, we suggest:
|
static HashFunction |
sha256()
Returns a hash function implementing the SHA-256 algorithm (256 hash bits).
|
static HashFunction |
sha384()
Returns a hash function implementing the SHA-384 algorithm (384 hash bits).
|
static HashFunction |
sha512()
Returns a hash function implementing the SHA-512 algorithm (512 hash bits).
|
static HashFunction |
sipHash24()
Returns a hash function implementing the 64-bit
SipHash-2-4 algorithm using a seed value of
k = 00 01 02 ... . |
static HashFunction |
sipHash24(long k0,
long k1)
Returns a hash function implementing the 64-bit
SipHash-2-4 algorithm using the given seed.
|
public static HashFunction goodFastHash(int minimumBits)
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. For a general-purpose,
non-cryptographic hash function that will never change behavior, we suggest murmur3_128(int)
.
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)minimumBits
or greaterpublic static HashFunction murmur3_32(int seed)
The exact C++ equivalent is the MurmurHash3_x86_32 function (Murmur3A).
public static HashFunction murmur3_32()
The exact C++ equivalent is the MurmurHash3_x86_32 function (Murmur3A).
public static HashFunction murmur3_128(int seed)
The exact C++ equivalent is the MurmurHash3_x64_128 function (Murmur3F).
public static HashFunction murmur3_128()
The exact C++ equivalent is the MurmurHash3_x64_128 function (Murmur3F).
public static HashFunction sipHash24()
k = 00 01 02 ...
.public static HashFunction sipHash24(long k0, long k1)
@Deprecated public static HashFunction md5()
sha256()
or a higher-level API.
goodFastHash(int)
, though see its docs for caveats.
@Deprecated public static HashFunction sha1()
sha256()
or a higher-level API.
goodFastHash(int)
, though see its docs for caveats.
public static HashFunction sha256()
public static HashFunction sha384()
public static HashFunction sha512()
public static HashFunction hmacMd5(Key key)
key
- the secret keyIllegalArgumentException
- if the given key is inappropriate for initializing this MACpublic static HashFunction hmacMd5(byte[] key)
SecretKeySpec
created from the given byte array
and the MD5 algorithm.key
- the key material of the secret keypublic static HashFunction hmacSha1(Key key)
key
- the secret keyIllegalArgumentException
- if the given key is inappropriate for initializing this MACpublic static HashFunction hmacSha1(byte[] key)
SecretKeySpec
created from the given byte
array and the SHA-1 algorithm.key
- the key material of the secret keypublic static HashFunction hmacSha256(Key key)
key
- the secret keyIllegalArgumentException
- if the given key is inappropriate for initializing this MACpublic static HashFunction hmacSha256(byte[] key)
SecretKeySpec
created from the given byte
array and the SHA-256 algorithm.key
- the key material of the secret keypublic static HashFunction hmacSha512(Key key)
key
- the secret keyIllegalArgumentException
- if the given key is inappropriate for initializing this MACpublic static HashFunction hmacSha512(byte[] key)
SecretKeySpec
created from the given byte
array and the SHA-512 algorithm.key
- the key material of the secret keypublic static HashFunction crc32c()
This function is best understood as a checksum rather than a true hash function.
public static HashFunction crc32()
To get the long
value equivalent to Checksum.getValue()
for a HashCode
produced by this function, use HashCode.padToLong()
.
This function is best understood as a checksum rather than a true hash function.
public static HashFunction adler32()
To get the long
value equivalent to Checksum.getValue()
for a HashCode
produced by this function, use HashCode.padToLong()
.
This function is best understood as a checksum rather than a true hash function.
public static HashFunction farmHashFingerprint64()
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.
FarmHash fingerprints are encoded by HashCode.asBytes()
in little-endian order. This
means HashCode.asLong()
is guaranteed to return the same value that
farmhash::Fingerprint64() would for the same input (when compared using UnsignedLongs
's encoding of 64-bit unsigned numbers).
This function is best understood as a fingerprint rather than a true hash function.
public static int consistentHash(HashCode hashCode, int buckets)
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:
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)
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:
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 HashCode combineOrdered(Iterable<HashCode> hashCodes)
IllegalArgumentException
- if hashCodes
is empty, or the hash codes do not all
have the same bit lengthpublic static HashCode combineUnordered(Iterable<HashCode> hashCodes)
IllegalArgumentException
- if hashCodes
is empty, or the hash codes do not all
have the same bit lengthpublic static HashFunction concatenating(HashFunction first, HashFunction second, HashFunction... rest)
For example, if you need 1024-bit hash codes, you could join two sha512()
hash
functions together: Hashing.concatenating(Hashing.sha512(), Hashing.sha512())
.
public static HashFunction concatenating(Iterable<HashFunction> hashFunctions)
For example, if you need 1024-bit hash codes, you could join two sha512()
hash
functions together: Hashing.concatenating(Hashing.sha512(), Hashing.sha512())
.
Copyright © 2010–2017. All rights reserved.