com.arcticicestudio.icecore.hashids

Class Hashids

java.lang.Object

com.arcticicestudio.icecore.hashids.Hashids

public final class Hashids
extends Object

A lightweight generator for short, unique, case-sensitive and non-sequential decodable hashes from positive unsigned (long) integer numbers.

Implementation of the Hashids algorithm:

• Generation of short, unique, case-sensitive and non-sequential decodable hashes of natural numbers
• Additional entropy through salt usage
• Configurable minimum hash size
• Combining of several numbers to one hash
• Deterministic hash computation given the same input and parametrization/configuration

An instance with the default interoperable configurations is available through the default constructor.

Configured instances can be created via Hashids.Builder to set a salt, define a ·minimum hash length or use a custom alphabet. Optional features can be enabled via the features(HashidsFeature) method. Please note that most features will break the interoperability with the origin algorithm implementation!

Instances of this class are thread-safe.

Version:

0.4.0

Author:

Arctic Ice Studio <development@arcticicestudio.com>

See Also:

IceCore Hashids GitHub Repository

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Hashids.Builder An immutable Hashids instance builder with optional features.

Field Summary

Fields

Modifier and Type	Field and Description
static char[]	DEFAULT_ALPHABET The default alphabet for the hash generation.
static long	MAX_INTEROP_NUMBER_SIZE The maximum number size to ensure interoperability with the origin algorithm implementation hashids .js.

Constructor Summary

Constructors

Constructor and Description
Hashids() Constructs a new instance without a salt, no minimum hash length, the default alphabet and no enabled features.

Method Summary

Modifier and Type	Method and Description
long[]	decode(String hash) Decodes the given hash into its numeric representation based on this instance configuration.
String	decodeHex(String hash) Decodes the given hash into its hexadecimal representation based on this instance configuration.
Optional<Long>	decodeOne(String hash) Decodes the given valid hash into its single numeric representation based on this instance configuration.
String	encode(long... numbers) Encodes the given positive numbers based on this instance configuration.
String	encodeHex(String hexNumbers) Encodes the given numbers in hexadecimal format based on this instance configuration.
boolean	equals(Object otherObject)
static String	getInteropVersion() Returns the version of the original algorithm implementation hashids .js with which the public API is interoperable.
static String	getVersion() Returns the version of the public API.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

MAX_INTEROP_NUMBER_SIZE

public static final long MAX_INTEROP_NUMBER_SIZE

The maximum number size to ensure interoperability with the origin algorithm implementation hashids .js.

This limit is based on the JavaScript Number.MAX_SAFE_INTEGER constant which represents the maximum safe integer.

The limit can be canceled by enabling the NO_MAX_INTEROP_NUMBER_SIZE feature. Please note that this will break the interoperability with the origin algorithm implementation!

See Also:

ECMAScript 2016 Language Specification

DEFAULT_ALPHABET

public static final char[] DEFAULT_ALPHABET

The default alphabet for the hash generation.

A customized alphabet can be set via the instance builder alphabet method.

Constructor Detail

Hashids

public Hashids()

Constructs a new instance without a salt, no minimum hash length, the default alphabet and no enabled features.

Method Detail

encode

public String encode(long... numbers)

Encodes the given positive numbers based on this instance configuration.

The given numbers size must not be larger than the maximum interoperability size unless the NO_MAX_INTEROP_NUMBER_SIZE feature is enabled. Please note that this will break the interoperability with the origin algorithm implementation!

Parameters:

numbers - the positive numbers to be encoded

Returns:

the resultant hash of the encoding of the numbers, empty otherwise

Throws:

IllegalArgumentException - if the EXCEPTION_HANDLING feature is enabled and the total length of numbers is zero, any numbers size is invalid or larger than the maximum interoperability size

NullPointerException - if the EXCEPTION_HANDLING feature is enabled and the given numbers are null

encodeHex

public String encodeHex(String hexNumbers)

Encodes the given numbers in hexadecimal format based on this instance configuration.

The given hexadecimal numbers must not be prefixed (0x or 0X) unless the ALLOW_HEXADECIMAL_NUMBER_PREFIX feature is enabled. Please note that this will break the interoperability with the origin algorithm implementation!

Parameters:

hexNumbers - the numbers in hexadecimal format to be encoded

Returns:

the resultant hash of the encoding of the hexadecimal numbers, empty otherwise

Throws:

IllegalArgumentException - if the EXCEPTION_HANDLING feature is enabled and any of the numbers is invalid

NullPointerException - if the EXCEPTION_HANDLING feature is enabled and the given numbers are null

decode

public long[] decode(String hash)

Decodes the given hash into its numeric representation based on this instance configuration.

Parameters:

hash - the hash to be decoded

Returns:

an array of long values with each numeric number present in the hash, empty otherwise

Throws:

IllegalArgumentException - if the EXCEPTION_HANDLING feature is enabled and the hash is invalid

NullPointerException - if the EXCEPTION_HANDLING feature is enabled and the given hash is null

decodeHex

public String decodeHex(String hash)

Decodes the given hash into its hexadecimal representation based on this instance configuration.

Parameters:

hash - the hash to be decoded

Returns:

the hexadecimal representation of the hash values with each numeric number present in the hash, empty otherwise

Throws:

NullPointerException - if the EXCEPTION_HANDLING feature is enabled and the given hash is null

decodeOne

public Optional<Long> decodeOne(String hash)

Decodes the given valid hash into its single numeric representation based on this instance configuration.

Simplifies the use-case where the amount of resulting numbers is known before to handle the return value as single value instead of an array. The given hash must resolve into a one number only, otherwise see the decode method.

Parameters:

hash - the valid hash to be decoded

Returns:

the decoded number if the given hash is valid, empty otherwise

Throws:

IllegalArgumentException - if the EXCEPTION_HANDLING feature is enabled and the hash is invalid

NullPointerException - if the EXCEPTION_HANDLING feature is enabled and the given hash is null

Since:

0.4.0

getVersion

public static String getVersion()

Returns the version of the public API.

Returns:

the version of the public API

Since:

0.2.0

See Also:

Arctic Versioning Specification, Semantic Versioning Specification

getInteropVersion

public static String getInteropVersion()

Returns the version of the original algorithm implementation hashids .js with which the public API is interoperable.

Returns:

the version of the original algorithm implementation with which the public API is interoperable

Since:

0.4.0

See Also:

Hashids Compatibility

equals

public boolean equals(Object otherObject)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object