readable-ids

The readable-ids library makes it possible to generate IDs that are easy for humans to read. It is based on dictionaries that can either be created individually or selected from a supplied selection of different dictionaries. The library offers various modifications and merging strategies that can be customized or created for specific applications. This allows developers to create flexible and user-friendly IDs that are both easy to read and easy to remember.

Usage

Add the Dependency to Your Project

Gradle

implementation 'de.adrianlange:readable-ids-core:0.0.1'

Maven

<dependency>
    <groupId>de.adrianlange</groupId>
    <artifactId>readable-ids-core</artifactId>
    <version>0.0.1</version>
</dependency>

Create New Readable IDs Generator From Simple Dictionary

public class FooDictionary extends SimpleTokenDictionary {

  private static final String[][] DICTIONARY = new String[][] {
          new String[] { "blue", "red", "yellow", "brown", "green", "black", "brown", "white" },
          new String[] { "balloon", "chair", "bird", "pillow" }
  };

  public FooDictionary() {
    super(DICTIONARY);
  }
}

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new FooDictionary());
for (int i = 0; i < 5; i++) {
  System.out.println(generator.nextId());
}
/*
 * generates:
 *  blackballoon
 *  yellowballoon
 *  greenpillow
 *  blackchair
 *  yellowchair
 */

You can easily create your own dictionary by extending SimpleTokenDictionary or even implement TokenDictionary.

Increase Existing Dictionaries With Decorator Dictionaries

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new AppendNumberDictionary(new FooDictionary()));
for (int i = 0; i < 5; i++) {
  System.out.println(generator.nextId());
}
/*
 * generates:
 *  blackballoon-612
 *  yellowballoon-35
 *  greenpillow-706
 *  blackchair-1
 *  yellowchair-532
 */

Another preedefined decorator dictionary is PrependAmountGermanDictionary.

Modify All Tokens Before Creating a Token

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new FooDictionary())
        .withTokenModifier(new UpperCaseModifier());
for (int i = 0; i < 5; i++) {
  System.out.println(generator.nextId());
}
/*
 * generates:
 *  BLACKBALLOON
 *  YELLOWBALLOON
 *  GREENPILLOW
 *  BLACKCHAIR
 *  YELLOWCHAIR
 */

Other given modifiers are LowerCaseModifier and ReplaceGermanSpecialCharactersModifier.

You can easily create your own modifier by implementing the interface TokenModifier.

Change the Way Tokens are Joined Forming an ID

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new FooDictionary())
        .withTokenJoiner(new SeparatorJoiner("-"));
for (int i = 0; i < 5; i++) {
  System.out.println(generator.nextId());
}
/*
 * generates:
 *  black-balloon
 *  yellow-balloon
 *  green-pillow
 *  black-chair
 *  yellow-chair
 */

You can easily create your own joiner by implementing the interface TokenJoiner.

English Dictionary with Adjectives and Nouns

To use the English dictionary you need to include the following dependency.

implementation 'de.adrianlange:readable-ids-dictionary-english-adjective-noun:0.0.1'

<dependency>
    <groupId>de.adrianlange</groupId>
    <artifactId>readable-ids-dictionary-english-adjective-noun</artifactId>
    <version>0.0.1</version>
</dependency>

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new EnglishAdjectiveNounDictionary())
        .withIdJoiner(new SeparatorJoiner("_"));
for (int i = 0; i < 5; i++) {
  System.out.println(generator.nextId());
}
/*
 * generates:
 *  famous_cork
 *  incredible_move
 *  magical_blood
 *  gracious_moon
 *  meticulous_skirt
 */

German Dictionary with Adjectives and Nouns

To use the German dictionary you need to include the following dependency.

implementation 'de.adrianlange:readable-ids-dictionary-german-adjective-noun:0.0.1'

<dependency>
    <groupId>de.adrianlange</groupId>
    <artifactId>readable-ids-dictionary-german-adjective-noun</artifactId>
    <version>0.0.1</version>
</dependency>

Use it preferably with the token modifier ReplaceGermanSpecialCharactersModifier:

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new GermanAdjectiveNounDictionary())
        .withTokenModifier(new ReplaceGermanSpecialCharactersModifier())
        .withTokenModifier(new LowerCaseModifier())
        .withIdJoiner(new KebapCaseJoiner());
for (int i = 0; i < 5; i++) {
  System.out.println(generator.nextId());
}
/*
 * generates:
 *  beachtliche-reinigungen
 *  nachhaltige-elefanten
 *  vertrauenswuerdige-spieler
 *  hoefliche-heckenpflanzen
 *  interessante-insekten
 */

Using Multiple Dictionaries

You can use multiple dictionaries at once in one Readable ID generator. Just call .withTokenDictionary(...) multiple times.

var generator = new ReadableIdGenerator()
        .withTokenDictionary(new FirstDictionary())
        .withTokenDictionary(new SecondDictionary());

When requesting a new ID, the generator first randomly selects one of the dictionaries from which an ID is then generated. Because all dictionaries have the same probability of being selected when generating an ID, the chance of duplicates among the IDs can be much higher when using another significantly smaller dictionary compared to the use of a single, extensive dictionary.

You can get the estimated number of possible combinations possible from the given dictionaries, assuming that there are no duplicates / overlaps within the dictionaries and that a good RandomGenerator is used:

long possibleCombinations = generator.getNumberOfPossibleCombinations();

Using Multiple Modules of readable-ids

To avoid having to maintain the module version individually, it is advisable to use the BOM.

Gradle

implementation(platform("de.adrianlange:readable-ids:0.0.1"))
implementation("de.adrianlange:readable-ids-dictionary-english-adjective-noun")
implementation("de.adrianlange:readable-ids-dictionary-german-adjective-noun")

Maven

 <dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>de.adrianlange</groupId>
            <artifactId>readable-ids</artifactId>
            <version>0.0.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependency>
    <groupId>de.adrianlange</groupId>
    <artifactId>readable-ids-dictionary-english-adjective-noun</artifactId>
</dependency>
<dependency>
    <groupId>de.adrianlange</groupId>
    <artifactId>readable-ids-dictionary-german-adjective-noun</artifactId>
</dependency>

Changelog

A list of changes can be found under CHANGELOG.md.