Skip to content

Roadmap to 1.0.0: Modernization & Enhanced Interface Architecture #7

Open

Description

@szkiba

The goal of ini4j 1.0.0 is to modernize the library by significantly enhancing its existing Interface-based capabilities. While ini4j has long supported binding interfaces to INI files, this release transforms that feature into a Modern Configuration Engine with full type safety, annotation support, and declarative configuration.

This release formalizes two distinct usage patterns:

  1. Interface-Based API (Enhanced): The recommended way for application development. We are augmenting the existing proxy mechanism with a new annotation suite and factory methods to provide a strictly typed, schema-first experience.
  2. Map-Based API (Core): Recommended for tooling, scripting, and dynamic scenarios. It requires no compile-time preparation and offers immediate, familiar access to arbitrary keys.

🔄 Backward Compatibility

The existing API remains fully supported.
Current implementations using the Ini class directly or the existing as() proxy method will continue to work. The new annotations and factory methods are additive enhancements.

🚀 Core Features

1. Enhanced Interface Architecture (Declarative)

We are upgrading the existing proxy mechanism to support a robust "Schema-First" approach. The new Factory method binds files directly to interfaces, handling parsing rules and type conversion automatically based on annotations.

  • Pros: Compile-time checks, IDE autocompletion, clean business logic.
  • Cons: Requires defining an interface upfront.
  • New Entry Point: Ini.load(Class<T>, File) (Wraps the existing proxy logic with enhanced configuration).

2. Fluent Core API (Imperative / Map-Based)

For users who need flexibility or are working with unknown file structures, the Map-based API is being enhanced with a Fluent style. Mutator methods in the core Ini and Settings classes will return the instance (this) to allow method chaining.

  • Pros: No setup required, supports dynamic keys, ideal for scripting.

  • Cons: String-based keys (susceptible to typos), manual type conversion.

  • Before:

    Ini ini = new Ini();
    ini.put("server", "port", "8080");
    ini.put("server", "host", "localhost");
  • After (v1.0.0):

    Ini ini = new Ini()
        .put("server", "port", "8080")
        .put("server", "host", "localhost");

3. Standardized Annotation Suite

A comprehensive set of annotations will be introduced to handle mapping, defaults, and formatting for the Interface API. This fills the gaps in the previous version where binding relied heavily on naming conventions.

Annotation Target Description
@Config Type Defines parsing rules (Encoding, Strictness, Tree Mode) on the interface itself.
@Section Method Maps a method to a specific [Section] name (Ini only).
@Option Method Maps a method to a specific key name.
@Default Method Provides a fallback value if the key is missing.
@Format Method Polymorphic pattern for parsing Dates (e.g., yyyy-MM-dd) or Numbers.

4. Settings API (Evolution of OptionsMap)

To better support flat configuration files (like .properties), the functionality previously found in OptionsMap will be refactored into a new class named Settings.

  • Purpose: To provide a robust, structured replacement for java.util.Properties that preserves comments, maintains insertion order, and supports both Interface and Map-based access.
  • Unified Experience: Settings utilizes the same new annotation suite (@Option, @Default, @Config) as Ini.

5. Modern I/O (NIO.2)

Internal I/O logic will be rewritten to use java.nio.file.Path.

  • Benefit: Enables loading configurations from non-standard file systems (e.g., inside ZIP/JAR files).
  • Compatibility: Standard File-based constructors will remain available as wrappers around the new logic to ensure existing code does not break.

🛠 Proposed API Examples

1. Structured Configuration (Interface / Declarative)
Best for: Long-lived applications where schema is known.

// Define the Schema
@Config(tree = true, strictOperator = true)
public interface DatabaseConfig {
    
    // Existing capability enhanced with explicit mapping
    @Section("database")
    DbSection getDb();

    interface DbSection {
        @Option("host")
        @Default("localhost")
        String getHostname();

        @Format("yyyy-MM-dd")
        LocalDate getLastBackup();
    }
}

// Load and Access
DatabaseConfig db = Ini.load(DatabaseConfig.class, new File("db.ini"));

2. Dynamic Configuration (Map-Based / Fluent)
Best for: Scripts, generic tools, or when schema is unknown.

// No interface needed - immediate access
Ini ini = new Ini()
    .put("database", "host", "localhost")
    .put("database", "port", "5432");

ini.store(new File("output.ini"));

✅ Task List

  • Core: Update BeanInvocationHandler to support new annotation logic (@Option, @Default, @Format).
  • Core: Implement Ini.load() and Settings.load() factory methods.
  • Core (API): Update put, add, and remove methods in Ini and Settings to return this (Fluent API).
  • Refactor: Introduce Settings class (replacing OptionsMap usage in v1.x).
  • I/O: Refactor internal readers/writers to use java.nio.file.Path.
  • Annotations: Create @Config annotation and connect it to parser settings.
  • Docs: Update README to feature Enhanced Interface-based usage while documenting Map-based usage as the Dynamic/Scripting alternative.
  • Tests: Add comprehensive tests for Proxy round-trip saving (ensuring config.store() preserves comments).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions