Skip to content

Home

Jump to bottom
github-actions[bot] edited this page Dec 2, 2025 · 8 revisions

Okaeri Configs Wiki

⚠️ Note: This wiki has been primarily generated and maintained using AI assistance. While we strive for accuracy, please report any errors or inconsistencies in the GitHub Issues.

Welcome to the comprehensive documentation for Okaeri Configs - a powerful, lightweight Java configuration library that makes working with configuration files simple and type-safe.

What is Okaeri Configs?

Okaeri Configs is a modern Java configuration library that allows you to use Java classes as configuration adapters. It provides a clean, annotation-based approach to managing application settings across multiple formats and platforms.

Key Features

  • 🎯 Type-Safe Configurations: Use Java classes with getters/setters for compile-time safety
  • 💬 Comment Support: Add persistent comments and headers to your config files
  • 🔄 Multiple Formats: YAML, JSON, HJSON, TOML, XML, Properties, INI
  • 🎮 Platform Support: Special integrations for Bukkit, Bungee, and more
  • 📦 Lightweight: Core library is only ~177kB
  • ✅ Validation: Built-in validation support (Okaeri Validator, Jakarta EE)
  • 🔌 Extensible: Custom serializers, transformers, and format support
  • 🌍 Environment Variables: Built-in support for environment variable substitution

Quick Example

@Header("################################")
@Header("#   My Application Config      #")
@Header("################################")
public class AppConfig extends OkaeriConfig {

    @Comment("Application settings")
    private String appName = "MyApp";
    private Integer maxConnections = 100;

    @Variable("API_KEY")
    @Comment("API key (can be set via environment variable)")
    private String apiKey = "your-key-here";

    @Comment("Server configuration")
    private ServerConfig server = new ServerConfig();

    public static class ServerConfig extends OkaeriConfig {
        private String host = "localhost";
        private Integer port = 8080;
    }
}

Usage:

AppConfig config = ConfigManager.create(AppConfig.class, (it) -> {
    it.configure(opt -> {
        opt.configurer(new YamlSnakeYamlConfigurer());
        opt.bindFile(new File("config.yml"));
    });
    it.saveDefaults();
    it.load(true); // load and save to update comments/new fields
});

// Access with type safety
String appName = config.getAppName();
config.setMaxConnections(200);
config.save();

Documentation Structure

Getting Started

Core Concepts

Advanced Features

Help & Reference

Quick Links

Installation

Maven:

<repository>
    <id>okaeri-releases</id>
    <url>https://repo.okaeri.cloud/releases</url>
</repository>

<dependency>
    <groupId>eu.okaeri</groupId>
    <artifactId>okaeri-configs-yaml-snakeyaml</artifactId>
    <version>{VERSION}</version>
</dependency>

Gradle (Kotlin DSL):

maven("https://repo.okaeri.cloud/releases")
implementation("eu.okaeri:okaeri-configs-yaml-snakeyaml:{VERSION}")

See Getting Started for detailed installation instructions.

Common Configurations

Use Case Format Additional Dependencies
Bukkit Plugins YAML (Bukkit) okaeri-configs-yaml-bukkit + okaeri-configs-serdes-bukkit
Bungee Plugins YAML (Bungee) okaeri-configs-yaml-bungee
General Purpose YAML (SnakeYAML) okaeri-configs-yaml-snakeyaml
Standalone Apps XML or INI okaeri-configs-xml or okaeri-configs-properties (zero deps)

Zero External Dependencies

Uses only Java built-in APIs. Great for minimal footprint.

Format Module Comments Errors Notes
XML okaeri-configs-xml ✅ ✅ Uses Java built-in XML APIs
Properties okaeri-configs-properties ✅ ✅ Flat key=value format
INI okaeri-configs-properties ✅ ✅ Section-based [section] format

With External Dependencies

Format Module Comments Errors Notes
YAML okaeri-configs-yaml-snakeyaml ✅ ✅ Via SnakeYAML
YAML okaeri-configs-yaml-jackson ✅ ✅ Via Jackson (SnakeYAML underneath)
TOML okaeri-configs-toml-jackson ✅ ✅ TOML 1.0 via Jackson
HJSON okaeri-configs-hjson ✅ ❌ Human JSON via hjson-java
JSON okaeri-configs-json-gson ❌ ❌ Via Google GSON
JSON okaeri-configs-json-jackson ❌ ❌ Via Jackson
JSON okaeri-configs-json-simple ❌ ❌ Via json-simple, no pretty print

Environment Dependent

Special implementations for safe use in specific environments, e.g., game servers.

Platform Module Comments Errors Notes
Bukkit/Spigot/Paper okaeri-configs-yaml-bukkit ✅ ✅ No extra dependencies needed
BungeeCord/Waterfall okaeri-configs-yaml-bungee ✅ ✅ No extra dependencies needed

Legend: Comments = @Comment/@Header support | Errors = Rust-style error markers

Rust-Style Error Messages

Supported formats provide precise, Rust-style error messages that pinpoint exactly where serdes failed:

error[StringToIntegerTransformer]: Cannot transform 'database.port' to Integer from String
 --> config.yml:3:9
  |
3 |   port: not_a_port
  |         ^^^^^^^^^^ Expected whole number (e.g. 42, -10, 0)

Works with nested paths, lists, and maps:

error[StringToIntegerTransformer]: Cannot transform 'servers[1].port' to Integer from String
 --> config.yml:5:11
  |
5 |     port: invalid
  |           ^^^^^^^ Expected whole number (e.g. 42, -10, 0)

Even deeply nested structures:

error[StringToIntegerTransformer]: Cannot transform 'environments["production"].clusters[0].nodes[0].resources.cpu' to Integer from String
 --> config.yml:9:20
  |
9 |               cpu: invalid_cores
  |                    ^^^^^^^^^^^^^ Expected whole number (e.g. 42, -10, 0)

Community & Support

Contributing to the Wiki

Found an error or want to improve the documentation?

  1. Visit the GitHub repository
  2. Navigate to the .wiki/ directory
  3. Submit a pull request with your improvements

Ready to get started? Head over to Getting Started to create your first config!

Clone this wiki locally