Búraló Technologies Identifier

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

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>1.4.1</version>
</dependency>

Instantiate UUIDIdentifierService which implements the IdentifierService and provide it with the delegate corresponding to the UUID format you wish to use:
```
private final IdentifierService identifierService = new UUIDIdentifierService(new UUIDVersion6Delegate());
```

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.
UIDVersion1Delegate (deprecated) -- uses a modified/non-standard Type 1 UUID format to improve database locality.

Spring Boot Usage

Add the following dependencies to your pom.xml:

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

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

The buralotech-identifier-spring contains auto-configuration 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. If you want to use the now deprecated modified Type 1 UUIDs then you will need to override the following property:
```
buralotech.identifier.generator=v1
```
Type 6 UUIDs are also supported and can be used by setting the same property as follows:
```
buralotech.identifier.generator=v6
```

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.

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

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.