DOCSEARCHbyAlgolia
Submit Docs

Java UUID Generator (JUG)

repository·main·Indexed 21 days ago

https://github.com/cowtowncoder/java-uuid-generator

A comprehensive library for generating, converting, and sorting UUIDs according to RFC-9562. It supports classic versions (1, 3, 4, 5) and modern lexicographically sortable versions (6, 7). The library includes the Generators factory for thread-safe UUID creation, UUIDUtil for high-performance byte array and string conversions, and UUIDComparator for correct unsigned sorting.

Tokens
1.3K
Snippets
5
Records
7
Agent score
26%

What's inside Java UUID Generator (JUG)

  1. Sort UUIDs correctly using UUIDComparator

    main

    The standard java.util.UUID.compareTo() implementation is flawed for unsigned comparison (it uses signed 64-bit comparison, which causes incorrect ordering for certain UUIDs).

    To achieve the expected lexicographic/unsigned sorting order, always use com.fasterxml.uuid.UUIDComparator.

  2. Install Java UUID Generator (JUG) via Maven or Gradle

    main

    To use JUG in your Java project, add the following dependency to your build configuration.

    Note on Logging: For versions 4.x and up, JUG uses the slf4j API. You must provide a logging implementation (like Logback or Log4j2) in your application to see logs.

    <!-- Maven -->
<dependency>
  <groupId>com.fasterxml.uuid</groupId>
  <artifactId>java-uuid-generator</artifactId>
  <version>5.1.0</version>
</dependency>
    // Gradle
implementation 'com.fasterxml.uuid:java-uuid-generator:5.1.0'

  3. Use default Time-Based (Version 1) Generator

    main

    If you need a Version 1 UUID and want JUG to automatically detect your network interface, use Generators.defaultTimeBasedGenerator(). It attempts to find the network interface corresponding to the default route for outgoing traffic.

    import com.fasterxml.uuid.Generators;
import com.fasterxml.uuid.generators.TimeBasedGenerator;
import java.util.UUID;

TimeBasedGenerator gen = Generators.defaultTimeBasedGenerator();
UUID uuid = gen.generate();

  4. Generate different UUID versions using Generators

    main

    JUG provides a Generators factory class to create various types of UUIDs. Generators are fully thread-safe and can be shared across multiple threads.

    Supported versions include:

    • Version 1: Time/location-based
    • Version 3 & 5: Name hash-based
    • Version 4: Random number-based
    • Version 6: Reordered version 1 (lexicographically sortable)
    • Version 7: Unix-timestamp + random (lexicographically sortable)
    import com.fasterxml.uuid.Generators;
import java.util.UUID;

// Version 1
UUID uuid1 = Generators.timeBasedGenerator().generate(); 

// Version 4
UUID uuid4 = Generators.randomBasedGenerator().generate(); 

// Version 5
UUID uuid5 = Generators.nameBasedGenerator().generate("string to hash"); 

// Version 6
UUID uuid6 = Generators.timeBasedReorderedGenerator().generate(); 

// Version 7
UUID uuid7 = Generators.timeBasedEpochGenerator().generate(); 

// Version 7 with per-call random values (JUG 5.0+)
UUID uuid7Random = Generators.timeBasedEpochRandomGenerator().generate();

  5. Convert UUIDs to byte arrays using UUIDUtil

    main

    While java.util.UUID provides toString(), it does not provide a way to convert to a byte[]. Use UUIDUtil for efficient conversion.

    import com.fasterxml.uuid.UUIDUtil;
import java.util.UUID;

UUID uuid = ...;

// Create a new byte array
byte[] asBytes = UUIDUtil.asByteArray(uuid);

// Use an existing buffer
byte[] outputBuffer = new byte[1000];
UUIDUtil.toByteArray(uuid, outputBuffer, 100); // appends at position 100

  6. Construct UUIDs from Strings or byte arrays using UUIDUtil

    main

    For high-performance conversion of Strings or byte arrays back into java.util.UUID instances, use UUIDUtil. This is optimized and faster than the standard java.util.UUID.fromString() method.

    import com.fasterxml.uuid.UUIDUtil;
import java.util.UUID;

// From String
UUID uuidFromStr = UUIDUtil.uuid("ebb8e8fe-b1b1-11d7-8adb-00b0d078fa18");

// From 16-byte array
byte[] rawUuidBytes = ...;
UUID uuidFromBytes = UUIDUtil.uuid(rawUuidBytes);

  7. Use JUG as a Command-Line Interface (CLI)

    main

    You can use the JUG JAR file as a standalone CLI tool to generate UUIDs.

    Command Syntax: java -jar <jar-name> -c <count> <version_flag>

    Flags:

    • -c or --count: Number of UUIDs to generate.
    • r: Random-based version (Version 4).

    Example (Generate 5 Random UUIDs):

    java -jar target/java-uuid-generator-5.1.0-SNAPSHOT.jar -c 5 r

    Note: For older versions where the Main-Class is not specified in the manifest, use: java -cp target/java-uuid-generator-5.1.0-SNAPSHOT.jar com.fasterxml.uuid.Jug -c 5 r