io.jstach.ezkv.kvs (Ezkv API 0.3.0)

module io.jstach.ezkv.kvs

The EZKV core module, a non-opinionated Java configuration system that supports recursive chain loading of configuration from key-value pairs ( io.jstach.ezkv:ezkv-kvs:0.3.0 ). This module is designed for use cases where early-stage configuration is needed, even before application logging is set up.

Ezkv focuses on loading streams of key-value pairs (represented as KeyValues) from various URI-based resources, such as classpath resources, files, system properties, and environment variables. The system is highly configurable and can be extended to support additional media types and URI patterns using the ServiceLoader mechanism.

Features

Zero opinions: No assumptions on loading order or resource names; fully user-defined.
Zero dependencies (besides java.base and org.jspecify for nullability annotations).
Immutable and thread-safe design, except for Builder classes.
Simple interpolation mechanism, configurable through key-value pairs.
Support for sensitive data handling and flexible resource chaining.
Extensibility through custom media type handlers and URI schemes.

Maven Coordinates


 <dependency>
     <groupId>io.jstach.ezkv</groupId>
     <artifactId>ezkv-kvs</artifactId>
     <version>0.3.0</version>
 </dependency>

Basic Usage

Example of loading key-value pairs from various sources:

var kvs = KeyValuesSystem.defaults()
    .loader()
    .add("classpath:/start.properties")
    .add("system:///")                   // add system properties to override
    .add("env:///")                      // add environment variables to override
    .add("cmd:///?_filter_sed=s/^-D//")  // add command line arguments with the -D prefix
    .load();

// Convert to a map and use it with other frameworks:
var map = kvs.toMap();
ConfigurableEnvironment env = applicationContext.getEnvironment();
env.getPropertySources().addFirst(new MapPropertySource("start", map));

Example Properties Files

start.properties

message=Hello ${user.name}
_load_foo=classpath:/foo.properties
port.prefix=1

foo.properties

user.name=Barf
message=Merchandising
db.port=${port.prefix}5672
_load_user=file:/${user.home}/.config/myapp/user.properties
_flags_user=sensitive,no_require

user.properties

secret=12345 # my luggage combination
port.prefix=3

Technical Details

All classes, except for Builder classes, are immutable and thread-safe, ensuring safe concurrent use.
Null values are neither returned nor accepted as input, unless explicitly marked with Nullable.

Extensibility

The module supports extension through KeyValuesServiceProvider, which can be implemented to add custom media types and URI loaders. Implementations can be discovered and loaded using the ServiceLoader mechanism.

Since:: 1.0
Author:: agentgt

Packages

Exports

Package

Description

io.jstach.ezkv.kvs

Ezkv Key Value loading system that allows loading of key values from URI-based resources.
Services

Uses

Type

Description

KeyValuesServiceProvider

A service provider interface (SPI) for extending ezkv's capabilities to support additional media types and URI patterns.

Module io.jstach.ezkv.kvs