Repository navigation
Description
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:
- 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.
- 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.Propertiesthat preserves comments, maintains insertion order, and supports both Interface and Map-based access. - Unified Experience:
Settingsutilizes the same new annotation suite (@Option,@Default,@Config) asIni.
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
BeanInvocationHandlerto support new annotation logic (@Option,@Default,@Format). - Core: Implement
Ini.load()andSettings.load()factory methods. - Core (API): Update
put,add, andremovemethods inIniandSettingsto returnthis(Fluent API). - Refactor: Introduce
Settingsclass (replacingOptionsMapusage in v1.x). - I/O: Refactor internal readers/writers to use
java.nio.file.Path. - Annotations: Create
@Configannotation 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