Skip to content

Latest commit

 

History

History
88 lines (63 loc) · 3.15 KB

README.md

File metadata and controls

88 lines (63 loc) · 3.15 KB
Raw

Java implementation of Identifiers spec

Build Status Coverage Status Maven Central

About Identifiers

Identifiers are self-describing strings of data that can be decoded into semantically-meaningful values. Identifiers can define basic data types, like numbers and bytes. They can also describe values like geolocations, date-times and uuids.

Try out an online version at identifiers.io

Installing the Identifiers Library

Maven Central coordinates:

<dependency>
   <groupId>io.identifiers</groupId>
   <artifactId>identifiers</artifactId>
   <version>0.1.0</version>
</dependency>

Usage

Identifiers comes with a set of static factory methods to encode Identifier instances and decode these encoded strings.

import io.identifiers.Factory;
import io.identifiers.Identifier;

Identifier<String> stringId = Factory.forString.create("a string value");

String encodedDataId = stringId.toDataString(); // smaller, good for data storage and transmission
String encodedHumanId = stringId.toHumanString(); // good for human interaction like emails and URLs

Identifier<String> decodedStringId = Factory.decodeFromString(encodedDataId);
// also decodes human strings
decodedStringId = Factory.decodeFromString(encodedHumanId);

Factories are provided for the following identifier types:

  • string
  • boolean
  • integer (32-bit signed ints)
  • float (64-bit signed decimals)
  • long (64-bit signed ints)
  • bytes
  • UUID (any version)
  • Datetime (Java Instant type)
  • Geo (decimal latitude / longitude)

Structured Identifiers

All the factory methods come with List and Map factory methods to create typed structured identifiers.

import io.identifiers.Factory;
import io.identifiers.Identifier;

// For datetime IDs
import java.time.Instant;

// List identifiers are declared as generic Lists.
ListIdentifier<Boolean> booleanListId = Factory.forString.createList(true, false);

Map<String, Instant>> dates = new HashMap<>();
dates.put("before", Instant.parse("2010-01-01"));
dates.put("after", Instant.parse("2011-12-31"));

// Map identifiers are declared as generic Maps with String keys.
MapIdentifier<Instant> Factory.forDatetime.createMap(dates);

Composite Identifiers

Different types of identifiers can be combined into a composite identifier. They can be composed as either Lists or Maps.

import io.identifiers.Factory;
import io.identifiers.Identifier;

ListIdentifier<Identifier<?>> compositeListId = Factory.forComposite.createList(
	Factory.forString.create("s1"),
	Factory.forFloat.createList(22.1, 6543.87),
	Factory.forBoolean.createMap(java.util.Collections.singletonMap("flag", true)));