Búraló Technologies Identifier

Overview

Generate domain object identifiers from UUIDs that are globally unique and sortable in their binary and textual representation.

Java Compatibility

• Versions 2.0.x & 2.1.x — Java 21

• Versions 2.2.x & 3.x.x — Java 25

Getting Started without Spring Boot

• Add the following dependency to your pom.xml:

  <dependency>
      <groupId>com.buralotech.oss.identifier</groupId>
      <artifactId>buralotech-identifier-core</artifactId>
      <version>3.2.0</version>
  </dependency>

• Instantiate UUIDIdentifierService which implements the IdenterifierService and provide it with the delegate corresponding to the UUID format you wish to use:

  private final IdentifierService identifierService = new UUIDIdentifierService(new UUIDVersion7Delegate());

The following delegates are available:

• UUIDVersion7Delegate (recommended) — uses the standard Type 7 UUID format which was designed with database locality in mind.

• UUIDVersion6Delegate — uses the standard Type 6 UUID format which was designed with database locality in mind.

• UUIDVersion4Delegate — uses the standard Type 4 UUID format which is not recommended if database locality is important.

Spring Boot Usage

• Add the following dependencies to your pom.xml:

  <dependency>
      <groupId>com.buralotech.oss.identifier</groupId>
      <artifactId>buralotech-identifier-core</artifactId>
      <version>3.2.0</version>
  </dependency>

  <dependency>
      <groupId>com.buralotech.oss.identifier</groupId>
      <artifactId>buralotech-identifier-spring</artifactId>
      <version>3.2.0</version>
  </dependency>

• The buralotech-identifier-spring contains autoconfiguration that exports an IdentifierService and IdentifierConverter bean. The IdentifierConverter bean allows conversion from the string representation.

• Auto-wire the IdentifierService bean:

  @Autowired
  private IdentifierService identifierService;

• Type 7 UUIDs are used by default. The previously deprecated modified Type 1 UUIDs are no longer supported.

• Type 6 UUIDs are also supported and can be used by setting the same property as follows:

  buralotech.identifier.generator=v6

• Type 4 UUIDs are also supported and can be used by setting the same property as follows:

  buralotech.identifier.generator=v4

Generating identifiers

• Generate an identifier:

  var id = identifierService.generate();

• id is a record of type UUIDIdentifier which implements the Identifier interface.

• id.binary() returns a byte[16] array that con be stored in a BINARY(16) column in the database.

  PreparedStatement ps = /* ... */;
  ps.setBytes(1, id.binary());

• id.text() returns a 22 character URL-safe string that can be used in RESTful APIs as part of the URI path or in request/response payloads.

• id.hex() returns a 32 character hexadecimal representation of the identifier.

• id.uuidString() returns a 36 character UUID string representation of the identifier.

• id.uuid() coverts the identifier to a UUID.

Parsing binary and text representations

• If you read byte[16] from a BINARY(16) database column use the identifierService.fromBinary(bytes []) method to convert it to an Identifier:

  ResultSet rs = /* ... */;
  var bytes = rs.getBytes(1);
  var id = identifierService.fromBinary(bytes);

• To convert a String passed via request URI or payload you can use the identifierService.fromText(String) method.

Working with timestamps

• Type 6 and Type 7 UUIDs contain the timestamp of the generation time. This means the identifier can do double duty since it is both the unique identifier and the creation date/time.

• You can extract the timestamp from the identifier using IdentifierService.toInstant(Identifier).

• If you want to search for entities created with a certain time window you can us IdentifierService.asLowerBound(Temporal) and IdentifierService.asUpperBound(Temporal) to get identifiers to use in the range query.

Property Based Testing

Integration with the jqwik property based testing framework was added in version 1.5.1.

• Add the following dependency:

  <dependency>
      <groupId>com.buralotech.oss.identifier</groupId>
      <artifactId>buralotech-identifier-jqwik</artifactId>
      <version>3.2.0</version>
      <scope>test</scope>
  </dependency>

• Then you can inject values by just using the @Property and @ForAll annotations:

  @Property
  void someTest(@ForAll Identifier id) {
      // ...
  }

• By default, Type 7 based identifiers are generated. You can add the @IdentifierParam annotation to explicitly specify one of Type 4, 6 or 7.

  @Property
  void someTest(@ForAll @IdentifierParam(version = 6) Identifier id) {
      // ...
  }

License & Source Code

The Búraló Technologies Identifier is made available under the Apache License and the source code is hosted on GitHub at https://github.com/BuraloOSS/buralo-identiifer.