Buralo Identifier

Overview

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

Java Compatibility

This library was created using Java 17.

Getting Started without Spring Boot

• Add the following dependency to your pom.xml:

  <dependency>
      <groupId>com.buralo</groupId>
      <artifactId>buralo-identifier-core</artifactId>
      <version>1.2.0</version>
  </dependency>

• Instantiate UUIDIdentifierService which implements the IdenterifierService:

  private final IdentifierService identifierService = new UUIDIdentifierService();

Spring Boot Usage

• Add the following dependencies to your pom.xml:

  <dependency>
      <groupId>com.buralo</groupId>
      <artifactId>buralo-identifier-core</artifactId>
      <version>1.2.0</version>
  </dependency>

  <dependency>
      <groupId>com.buralo</groupId>
      <artifactId>buralo-identifier-spring</artifactId>
      <version>1.2.0</version>
  </dependency>

• The buralo-identifier-spring contains auto-configuration that exports an IdenifierService and IdentifierConverter bean. The IdentifierConverter bean allows conversion from the string r

• Auto-wire the IdentifierService bean:

  @Autowired
  private IdentifierService identifierService;

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] arrary 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.

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 1 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.

License & Source Code

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