TypeMap & TypeList incl. TypeConverter

Installation

Maven

<dependency>
  <groupId>berlin.yuna</groupId>
  <artifactId>type-map</artifactId>
  <version>${type-map.version}</version>
</dependency>

Gradle

implementation("berlin.yuna:type-map:${typeMapVersion}")

Introduction

Greetings, Java developer. Are you tired of wrangling primitive type conversions, fighting rogue JSON strings, and sacrificing your sanity to reflection-heavy libraries? Good news: the TypeMap/TypeList library exists to end this chaos. Designed with performance, simplicity, and GraalVM native compatibility in mind, it transforms the art of type management from a dreaded chore to a seamless experience.

Motivation

Most libraries promise ease, but under the hood, they hide performance-draining reflection or endless dependencies. Not this one. This library was forged from the frustration of clunky, bloated tools.

Benefits

• Pure Java: No external dependencies for a lightweight integration.
• Functional Design: Embraces modern Java functional paradigms.
• No Reflection: Ensures compatibility with GraalVM native images.
• High Performance: Tailored for efficiency in intensive workloads.
• Dynamic & Extendable: Simplifies adding new type conversions.
• Type Safety: Utilizes Java generics for compile-time type checking.
• Lazy Loading: Conversions occur only when needed, enhancing performance and reducing memory usage.

Classes

• Core Components:
  • Type
  • TypeSet
    • ConcurrentTypeSet
  • TypeList
    • ConcurrentTypeList
  • TypeMap
    • LinkedTypeMap
    • ConcurrentTypeMap
• Supportive Tools:
  • TypeConverter
  • JsonEncoder
  • JsonDecoder
  • XmlEncoder
  • XmlDecoder
  • ArgsDecoder
• Extension Mechanism:
  • TypeConversionRegister

Getting Started

Quick start (JSON or XML input):

TypeMap map = TypeMap.mapOf(jsonOrXml);
TypeList list = TypeList.listOf(jsonOrXml);

Basics

TypeMap typeMap = new TypeMap().putR("myTime", new Date());
OffsetDateTime timeValue = typeMap.asOffsetDateTime("myTime");
OffsetDateTime timeValue2 = typeMap.as(OffsetDateTime.class, "myTime");

TypeList typeList = new TypeList().addR(new Date());
OffsetDateTime timeValue = typeList.asOffsetDateTime(0);
OffsetDateTime timeValue2 = typeList.as(OffsetDateTime.class, 0);

Collections

TypeMap typeMap = new TypeMap().putR("myKey", new String[]{"1", "2", "3"});

TypeList list1 = typeMap.asList("myKey");
Integer numberThree = typeMap.asList("myKey").as(2, Integer.class);
List<Integer> list2 = typeMap.asList(Integer.class, "myKey");
List<Integer> list3 = typeMap.asList(ArrayList::new, Integer.class, "myKey");

TypeList typeList = new TypeList().addR(new String[]{"1", "2", "3"});

TypeList list1 = typeList.asList(0);
Integer numberThree = typeList.asList(0).as(2, Integer.class);
List<Integer> list2 = typeList.asList(Integer.class, 0);
List<Integer> list3 = typeList.asList(ArrayList::new, Integer.class, 0);

Maps

TypeMap typeMap = new TypeMap().putR("myKey", Map.of(6, new Date()));

LinkedTypeMap map1 = typeMap.asMap("myKey");
Map<Long, Instant> map2 = typeMap.asMap(Long.class, Instant.class, "myKey");
Map<Long, Instant> map3 = typeMap.asMap(HashMap::new, Long.class, Instant.class, "myKey");

TypeList typeList = new TypeList().addR(Map.of(6, new Date()));

LinkedTypeMap map1 = typeList.asMap(0);
Map<Long, Instant> map2 = typeList.asMap(Long.class, Instant.class, 0);
Map<Long, Instant> map3 = typeList.asMap(HashMap::new, Long.class, Instant.class, 0);

JSON & XML

TypeMap/TypeList use JsonDecoder/XmlDecoder internally; the decoder APIs are meant for advanced use.

String jsonString = "{"
    + "\"outerMap\":{"
    + "\"innerMap\":{\"timestamp\":1800000000000},"
    + "\"myList\":[\"BB\",1,true,null,1.2]"
    + "}"
    + "}";

TypeMap jsonMap = TypeMap.mapOf(jsonString);
LinkedTypeMap inner = jsonMap.asMap("outerMap", "innerMap");
List<Object> list = jsonMap.asList(Object.class, "outerMap", "myList");
TestEnum enumValue = jsonMap.as(TestEnum.class, "outerMap", "myList", 0);
Long timestamp = jsonMap.asLong("outerMap", "innerMap", "timestamp");
String backToJson = jsonMap.toJson();

String xmlString = "<root><id>7</id></root>";
TypeMap xmlMap = TypeMap.mapOf(xmlString);
Long id = xmlMap.asLong("id");

Streaming JSON (IO-backed streams must be closed)

try (Stream<Pair<Integer, Object>> stream = JsonDecoder.streamJsonArray(path)) {
    stream.forEach(pair -> System.out.println(pair.value()));
}

Args

ArgsDecoder is used internally

String[] cliArgs = {"myCommand1", "myCommand2", "--help", "-v2=true", "-param", "42"};
TypeMap map = new TypeMap(cliArgs);

Boolean help = map.asBoolean("help");
Boolean v2 = map.asBoolean("v2");
List<Integer> paramList = map.asList(Integer.class, "param");

TypeConverter

TypeConverter is the core of TypeMap/TypeList conversions

• TypeConverter.mapOf
• TypeConverter.convertObj
• TypeConverter.collectionOf
• JsonEncoder.toJson
• JsonDecoder.mapOf
• JsonDecoder.listOf
• JsonDecoder.typeOf

// ENUM
TestEnum enumValue = enumOf("BB", TestEnum.class);

// OBJECT
TestEnum enumValue2 = convertObj("BB", TestEnum.class);
Long longValue = convertObj("1800000000000", Long.class);
OffsetDateTime timeValue = convertObj("1800000000000", OffsetDateTime.class);

// MAP
TypeMap map1 = mapOf(Map.of("12", "34", "56", "78"));
Map<String, Integer> map2 = mapOf(Map.of("12", "34", "56", "78"), String.class, Integer.class);
Map<String, Integer> map3 = mapOf(Map.of("12", "34", "56", "78"), HashMap::new, String.class, Integer.class);

// COLLECTION
TypeList list1 = collectionOf(Arrays.asList("123", "456"));
Set<Integer> list2 = collectionOf(Arrays.asList("123", "456"), Integer.class);
Set<Integer> set1 = collectionOf(Arrays.asList("123", "456"), HashSet::new, Integer.class);

Register custom conversions

Exceptions are ignored and result in null

conversionFrom(String.class).to(Integer.class).register(Path::toUri);
TypeConversionRegister.registerTypeConvert(Path.class, File.class, Path::toFile);
TypeConversionRegister.registerTypeConvert(Path.class, URL.class, path -> path.toUri().toURL());