java 47 lines · 8 steps

How to generate a ULID in Java

A ULID packs a millisecond timestamp and random entropy into a sortable, Crockford base32 string.

Explained by highlit

Intermediate base32-encoding bit-manipulation identifiers secure-random

1public final class Ulid {
2 
  private static final char[] ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ".toCharArray();
  private static final SecureRandom RANDOM = new SecureRandom();
  private static final int TIME_LENGTH = 10;
  private static final int RANDOM_LENGTH = 16;
7 
  private Ulid() {
  }
10 
  public static String generate() {
      return generate(System.currentTimeMillis());
  }
14 
  public static String generate(long timestamp) {
      if (timestamp < 0 || timestamp > 0xFFFFFFFFFFFFL) {
          throw new IllegalArgumentException("timestamp out of ULID range");
      }
      char[] chars = new char[TIME_LENGTH + RANDOM_LENGTH];
      encodeTime(timestamp, chars);
      encodeRandom(chars);
      return new String(chars);
  }
24 
  private static void encodeTime(long timestamp, char[] out) {
      for (int i = TIME_LENGTH - 1; i >= 0; i--) {
          out[i] = ENCODING[(int) (timestamp & 0x1F)];
          timestamp >>>= 5;
      }
  }
31 
  private static void encodeRandom(char[] out) {
      byte[] entropy = new byte[10];
      RANDOM.nextBytes(entropy);
      long bits = 0L;
      int available = 0;
      int entropyIndex = 0;
      for (int i = TIME_LENGTH; i < out.length; i++) {
          if (available < 5) {
              bits = (bits << 8) | (entropy[entropyIndex++] & 0xFFL);
              available += 8;
          }
          available -= 5;
          out[i] = ENCODING[(int) ((bits >>> available) & 0x1F)];
      }
  }
47}

01 / 01

STEP 01

Walkthrough

Space play ←→ step click any line

Three takeaways

1Crockford's base32 alphabet omits I, L, O, and U to stay unambiguous when read by humans.
2Encoding five bits per character means bytes must be buffered and drained in 5-bit chunks.
3Putting the timestamp first makes ULIDs lexicographically sortable by creation time.

Related explainers

java

@RestController
@RequestMapping("/api/reports")
public class ReportController {

Header-driven endpoints in a Spring controller

rest api request headers dependency injection

Intermediate 7 steps

java

public final class CaseConverter {
 
    private static final Pattern CAMEL_BOUNDARY =
            Pattern.compile("([a-z0-9])([A-Z])|([A-Z]+)([A-Z][a-z])");

Converting camelCase to snake_case in Java

regex string-manipulation utility-class

Intermediate 7 steps

java

@Component
public class RegionCacheWarmer implements SmartInitializingSingleton {
 
    private static final Logger log = LoggerFactory.getLogger(RegionCacheWarmer.class);

Warming a Spring cache at startup

caching startup-hook dependency-injection

Intermediate 7 steps

java

public final class EmailNormalizer {
 
    private static final Pattern EMAIL_PATTERN = Pattern.compile(
        "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$"

Normalizing email addresses in Java

validation regex normalization

Intermediate 8 steps

java

@RestController
@RequestMapping("/api/products")
@RequiredArgsConstructor
public class ProductBatchController {

Batch JSON Merge Patch in Spring

json-merge-patch rest-api partial-update

Intermediate 8 steps

java

public class TimedFetchService {
 
    private final ExecutorService executor = Executors.newFixedThreadPool(8);
    private final HttpClient httpClient = HttpClient.newHttpClient();