Hashids.java

Hashids creates short, unique, decodable hashes from unsigned (long) integers. It is designed for obfuscating IDs in URLs, tracking, or making pages unguessable.

Key Features:

• Uniqueness: Hashes are unique and decodable back to the original numbers.
• Multi-integer support: Can encode multiple numbers into a single hash.
• Obfuscation: It is designed to make IDs unguessable and unpredictable (e.g., incrementing numbers do not result in obvious patterns in the hashes).
• Curse Word Avoidance: By default, the algorithm avoids generating common English curse words by restricting certain character combinations.

Note on Security: Hashids is intended for obfuscation, not for security or compression. It should not be used as a replacement for cryptographic security measures.

Hashids is available in Maven Central. Use the following configuration to add it to your project.

Maven (pom.xml):

<dependency>
  <groupId>org.hashids</groupId>
  <artifactId>hashids</artifactId>
  <version>1.0.3</version>
</dependency>

Gradle/Android (build.gradle):

compile 'org.hashids:hashids:1.0.3'

Hashids provides specialized methods for handling hex-encoded strings, such as MongoDB ObjectIDs.

Warning: The algorithm used for hex values is not compatible with the algorithm used for long integers. You cannot use decodeHex to retrieve a long ID that was originally encoded with encode.

Hashids hashids = new Hashids("This is my salt");
String hash = hashids.encodeHex("507f1f77bcf86cd799439011"); // goMYDnAezwurPKWKKxL2
String objectId = hashids.decodeHex(hash); // 507f1f77bcf86cd799439011

The Hashids class allows you to generate short, unique, decodable hashes from one or more unsigned (long) integers.

Important:

• You must use the same salt for both encoding and decoding. If the salt differs, decoding will return an empty array.
• All integers must be greater than or equal to zero.
• While the library uses long, it is limited to the JavaScript compatibility limit of (2^53 - 1). Providing a larger number will throw an IllegalArgumentException.

import org.hashids;

// Encoding a single number
Hashids hashids = new Hashids("this is my salt");
String hash = hashids.encode(12345L);

// Decoding
long[] numbers = hashids.decode("NkK9");

// Encoding multiple numbers
String multiHash = hashids.encode(683L, 94108L, 123L, 5L);

// Decoding multiple numbers
long[] multiNumbers = hashids.decode("aBMswoO2UB3Sj");

You can customize the Hashids instance to control the output format:

1. Minimum Length: Set a minimum number of characters for the generated hash. The default is 0 (shortest possible).
2. Custom Alphabet: Provide a specific string of characters to be used for the hash generation.

Constructor Signatures:

• new Hashids(String salt)
• new Hashids(String salt, int minLength)
• new Hashids(String salt, int minLength, String alphabet)

// Specifying minimum hash length of 8
Hashids hashids = new Hashids("this is my salt", 8);
String hash = hashids.encode(1L);

// Specifying custom alphabet
Hashids hashidsCustom = new Hashids("this is my salt", 0, "0123456789abcdef");
String hashCustom = hashidsCustom.encode(1234567L);