Evgenij Kolpakov own site
Programs kz-pompei-hotconfig kz-pompei-scheduler MIT licence Forum
Login or Register

github: https://github.com/pompei-kz/hotconfig

kz-pompei-hotconfig

Hot configuration for Java services, backed by files, JDBC, or etcd.

Java Gradle TestNG Version License: MIT

kz-pompei-hotconfig turns a plain Java interface into a live configuration object. The first read creates a configuration file or storage row from defaults, later reads return typed values, and refresh checks pick up changes from the backing storage.

AppConfigInterface conf = factory.createConf(AppConfigInterface.class);

int port = conf.port(); // read from config file (or SQL DB, or etcd)
boolean enabled = conf.enabled();

Contents

Quick Start

This example mirrors the configuration pattern tested in HotConfigFactoryTest, but uses ConfigTunnelFile as the storage tunnel.

1. Dependency

Add this to build.gradle / dependencies

implementation "kz.pompei.hotconfig:kz-pompei-hotconfig-core:0.0.7"

2. Define A Configuration Interface

import kz.pompei.hotconfig.core.ann.ConfDefaultValue;
import kz.pompei.hotconfig.core.ann.ConfDoc;
import kz.pompei.hotconfig.core.ann.ConfFolder;

@ConfDoc("about1\nabout2\nabout3")
@ConfFolder("cool/folder")
public interface TestConf1 {

  @ConfDoc("description1\ndescription2")
  @ConfDefaultValue("def value 1")
  String param1();

  @ConfDoc("description3\ndescription4\ndescription5")
  @ConfDefaultValue("20 + 1024")
  int accessPort();
}

3. Create A Factory Backed By Files

import java.nio.file.Path;
import kz.pompei.hotconfig.core.ConfigTunnelFile;
import kz.pompei.hotconfig.core.HotConfigFactory;

Path baseDir = Path.of("/path/to/config/root");

var tunnel = ConfigTunnelFile.builder()
                             .baseDir(baseDir)
                             .noticeExtension(".notice")
                             .build();

HotConfigFactory factory = HotConfigFactory.builder()
                                           .tunnel(tunnel)
                                           .extension(".hot")
                                           .build();

TestConf1 config = factory.createConf(TestConf1.class);

String param1     = config.param1();     // "def value 1"
int    accessPort = config.accessPort(); // 1044

4. Inspect The Generated File

On the first read, the library creates:

/path/to/config/root/cool/folder/TestConf1.hot

With content generated from annotations:

#about1
#about2
#about3

#description1
#description2
param1=def value 1

#description3
#description4
#description5
accessPort=20 + 1024

5. Edit and read new values

Edit the file manually:

param1=SKY TREE
accessPort=20 + 1024 + 700

Then read new values without restart application


String updatedParam1 = config.param1();     // "SKY TREE"
int    accessPort    = config.accessPort(); // 1744

Features

Modules

Module Description
kz-pompei-hotconfig-core Core API, proxy factory, file tunnel, annotations, parser, and models.
kz-pompei-hotconfig-jdbc JDBC tunnel for PostgreSQL and MariaDB.
kz-pompei-hotconfig-etcd etcd v3 tunnel implemented with jetcd.

Installation

The library is published to Maven Central. It requires Java 21.

Use kz-pompei-hotconfig-core for file-backed configuration. Add kz-pompei-hotconfig-jdbc or kz-pompei-hotconfig-etcd when you need those storage backends.

Gradle

repositories {
  mavenCentral()
}

dependencies {
  implementation "kz.pompei.hotconfig:kz-pompei-hotconfig-core:0.0.7"
  // If you store configs in files, no extra modules are needed

  // Optional storage backends

  // Add this if you want to store configs in SQL database
  implementation "kz.pompei.hotconfig:kz-pompei-hotconfig-jdbc:0.0.7"
  
  // Add this if you want to store configs in etcd database
  implementation "kz.pompei.hotconfig:kz-pompei-hotconfig-etcd:0.0.7"
}

Maven

<dependencies>
  <dependency>
    <groupId>kz.pompei.hotconfig</groupId>
    <artifactId>kz-pompei-hotconfig-core</artifactId>
    <version>0.0.7</version>
  </dependency>

  <!-- If you store configs in files, no extra modules are needed -->

  <!-- Optional storage backends -->

  <!-- Add this if you want to store configs in SQL database -->
  <dependency>
    <groupId>kz.pompei.hotconfig</groupId>
    <artifactId>kz-pompei-hotconfig-jdbc</artifactId>
    <version>0.0.7</version>
  </dependency>

  <!-- Add this if you want to store configs in etcd database -->
  <dependency>
    <groupId>kz.pompei.hotconfig</groupId>
    <artifactId>kz-pompei-hotconfig-etcd</artifactId>
    <version>0.0.7</version>
  </dependency>
</dependencies>

Configuration Interfaces

A configuration interface is a plain Java interface with no-argument methods. Each method name becomes a parameter name.

@ConfFolder("app")
@ConfDoc("Application configuration")
public interface AppConf {
  @ConfDoc("HTTP port")
  @ConfDefaultValue("8080")
  int port();

  @ConfDefaultValue("true")
  boolean enabled();

  @ConfDefaultValue("localhost")
  String host();
}

Annotations:

Annotation Target Purpose
@ConfFolder("folder") interface Places the configuration under a folder.
@ConfDoc("text") interface or method Writes comments into generated configuration storage.
@ConfDefaultValue("value") method Defines the value used when the parameter is absent.

Only zero-argument methods are supported.

Value Parsing

Configuration values are stored as strings. ParseUtil converts them to the Java return type of the interface method.

Supported target types:

Environment Substitution

Use $ENV{NAME} to resolve environment variables before type conversion:

port=$ENV{APP_PORT}
workers=$ENV{WORKER_COUNT} * 2

String Escapes

Supported escape sequences:

Input Result
\n newline
\t tab
\r carriage return
\b backspace
\f form feed
\\ backslash
\" double quote
\' single quote

For numeric targets, whitespace, _, backslash separators, and escaped control characters are ignored where applicable.

Numbers

Numeric parsing accepts:

1 234
1_234
12,5
-12.5
1.3e+4
0.456e-17
-17.45E+61
0xAfeE76a03
0b100110101  - binary
0o16542      - octal

Base-prefixed integer literals:

Prefix Base Example
0x / 0X hexadecimal 0x234, 0xAfeE76a03
0b / 0B binary 0b100110101, 0B0011010110
0o / 0O octal 0o16542, 0O643

Leading-zero numbers without a base prefix stay decimal:

00034 == 34
01896 == 1896

Expressions

Numeric target types can evaluate expressions:

1 + 2
17 - 3
10 * 34
450 / 10
3 + 7*3
$ENV{NAME} * 16
(23 + 4)*(100 - 45)

Supported operators:

Precedence follows normal mathematics. A + or - after e or E is part of exponent notation; elsewhere it is an operator.

Integer targets:

Floating-point targets:

Boolean targets:

Storage Backends

Files

ConfigTunnelFile stores each configuration as a UTF-8 text file.

ConfigTunnelFile tunnel = ConfigTunnelFile.builder()
  .baseDir(Path.of("/path/to/config/root"))
  .noticeExtension(".notice")
  .build();

HotConfigFactory factory = HotConfigFactory.builder()
  .tunnel(tunnel)
  .build();

Example generated file:

#Application configuration

#HTTP port
port=8080

enabled=true
host=localhost

The file tunnel uses file modification time as the modification marker. Notice lines are stored in a sibling UTF-8 file at localPath + noticeExtension.

JDBC

kz-pompei-hotconfig-jdbc stores configurations in a database table. PostgreSQL and MariaDB are detected from JDBC metadata.

import kz.pompei.hotconfig.jdbc.ConfigTunnelJdbc;

ConfigTunnelJdbc tunnel = ConfigTunnelJdbc.builder()
                                          .connectionGet(() -> dataSource.getConnection())
                                          .tableName("hotconfig")
                                          .build();

The table and schema are created automatically when missing. Column names are configurable through ConfigTunnelJdbcBuilder. Parameter order is stored in colOrder, defaulting to the order_index integer column. Notice lines are stored in the colNotice text column on the configuration row only. If you already have a table from an older version, add this column manually before using notice storage. Parameter errors are stored in the colError text column on parameter rows. Existing JDBC tables must add this column manually before using version 0.0.7.

etcd

kz-pompei-hotconfig-etcd stores each configuration under one etcd key.

import io.etcd.jetcd.Client;
import kz.pompei.hotconfig.etcd.ConfigTunnelEtcd;

try (Client client = Client.builder().endpoints("http://localhost:17403").build();

     ConfigTunnelEtcd tunnel = ConfigTunnelEtcd.builder()
                                               .client(client)
                                               .keyPrefix("/kz-pompei-conf-etcd/")
                                               .build()) {

  HotConfigFactory factory = HotConfigFactory.builder()
                                             .tunnel(tunnel)
                                             .build();
}

The etcd tunnel uses the key modRevision as the modification marker. Notice lines are stored under a separate key at localPath + noticeExtension.

Notice Lines

ConfigTunnel supports notice text associated with a configuration:

import java.util.List;

tunnel.writeNoticeLines("app/AppConf.hotconf", List.of("invalid port", "fallback was used"));
List<String> notices = tunnel.readNoticeLines("app/AppConf.hotconf");

Notice lines are separate from @ConfDoc comments and are not attached to individual parameters. For file and etcd tunnels, writing an empty notice list deletes the existing notice file or key.

Parameter Errors

ConfParam.error stores validation or parsing error text associated with a parameter. File and etcd tunnels write it immediately after the name=value line using the #ERROR prefix by default:

port=bad value
#ERROR Cannot parse integer
#ERROR source=manual edit

File and etcd tunnels write multiline errors as consecutive prefixed lines and join them back with newline characters when read. The configurable error prefix is the text after the mandatory leading #; for example, ERROR is stored as #ERROR . Backslashes in file and etcd error text are stored as-is. If error is null, the #ERROR line is absent. JDBC stores the same error text in the configurable colError text column.

Changelog

Release notes are kept in CHANGELOG.md. Detailed notes for this release are in versions/0.0.7.md.

Build And Test

Requirements:

Run core tests:

./gradlew :kz-pompei-hotconfig-core:test

Start local integration services:

bash docker/docker-recreate.bash

Then run backend tests:

./gradlew :kz-pompei-hotconfig-jdbc:test
./gradlew :kz-pompei-hotconfig-etcd:test

Run all tests:

./gradlew test

Project Layout

kz-pompei-hotconfig
├── kz-pompei-hotconfig-core
├── kz-pompei-hotconfig-jdbc
├── kz-pompei-hotconfig-etcd
├── utils
├── docker
├── versions
└── build.gradle

Notes for contributors:

Roadmap Ideas

License

This project is licensed under the MIT License.