Skip to main content

INI Basics

Juneau supports converting POJOs to and from the classic INI configuration file format using native serializers and parsers implemented without any external dependencies. INI organizes data as sections ([sectionName]) containing key-value pairs, and is a familiar format for application and tool configuration files. The IniSerializer converts POJOs directly to INI text, and the IniParser creates POJOs directly from INI text.

INI support is included in juneau-marshall.

Maven
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-marshall</artifactId>
    <version>${juneau.version}</version>
</dependency>

Quick Start​

The Ini marshaller pairs a serializer and parser behind a single convenience API:

public class Contact {
    public String name;
    public int age;
    public Address address;

    public Contact() {}
    public Contact(String name, int age, Address address) {
        this.name = name;
        this.age = age;
        this.address = address;
    }
}

public class Address {
    public String street;
    public String city;
    public String state;
    // constructors omitted
}

Contact contact = new Contact("Alice", 30, new Address("123 Main St", "Boston", "MA"));

// Serialize a bean to INI
String ini = Ini.DEFAULT.of(contact);

// Parse INI back into a bean
Contact parsed = Ini.DEFAULT.to(ini, Contact.class);

Produces:

name = Alice
age = 30

[address]
street = 123 Main St
city = Boston
state = MA

Serialization​

Use the default serializer directly, or the marshaller for convenience:

// Use the default serializer instance (thread-safe and reusable)
String ini = IniSerializer.DEFAULT.write(myBean);

// DEFAULT_READABLE inserts blank lines between sections
String pretty = IniSerializer.DEFAULT_READABLE.write(myBean);

// Use the marshaller
String ini2 = Ini.of(myBean);

// Readable (spaced) output via the IniR variant marshaller
String pretty2 = IniR.of(myBean);

The readable configuration is exposed as the dedicated IniR variant marshaller (backed by IniSerializer.DEFAULT_READABLE). It is a first-class Ini facade, so it exposes the same static of(...) / to(...) shortcut surface as Ini itself. (This replaces the former Ini.DEFAULT_READABLE constant, removed in 10.0.0.)

Bean-to-INI mapping​

Java constructINI representation
Simple bean/map propertiesKey-value pairs in the default (top) section
Nested beans[sectionName] sections
Deeply nested beans[path/to/section] section paths
Map<String,?> values[sectionName] sections
Collections and complex map valuesJSON5-encoded inline values
null valuesUnquoted null token

Collections and complex values are embedded as JSON5 inline strings so they remain fully round-trippable:

name = Alice
age = 30
tags = ['a','b','c']

[address]
street = 123 Main St
city = Boston
state = MA
note

The top-level object must be a bean or a Map<String,?>. Top-level collections, arrays, and scalar values are not supported and cause a SerializeException.

Parsing​

// Use the default parser instance
Contact contact = IniParser.DEFAULT.read(ini, Contact.class);

// Parse into a generic map
Map<String,Object> map = IniParser.DEFAULT.read(ini, Map.class, String.class, Object.class);

// Use the marshaller
Contact contact2 = Ini.DEFAULT.to(ini, Contact.class);

Values are interpreted by type:

INI valueParsed as
Unquoted nullJava null
Unquoted true / falseBoolean
Unquoted numbersNumber (int, long, float, or double as appropriate)
Single-quoted strings ('...')String (with '' unescaped to a single quote)
Values starting with [ or {Delegated to the JSON parser (arrays / objects)
ISO 8601 date/time stringsDate, Calendar, or java.time.* when the target requires it
ISO 8601 duration stringsjava.time.Duration
Other unquoted tokensString

Sections such as [address] map to nested bean or map properties, and section paths such as [employment/company] map to deeply nested properties.

Configuration Options​

The serializer builder exposes INI-specific formatting options:

// Colon separator, no surrounding spaces, and property-description comments
IniSerializer s = IniSerializer.create()
    .kvSeparator(':')
    .spacedSeparator(false)
    .useComments()
    .build();

String ini = s.write(myBean);
Builder methodDescriptionDefault
kvSeparator(char)Key-value separator character — = or :=
spacedSeparator(boolean)Add spaces around the separator (key = value vs key=value)true
useComments()Emit # comments from bean property descriptionsfalse

The same options can be applied declaratively via the @IniConfig annotation on classes and methods (kvSeparator, spacedSeparator, useComments, rank), which is the mechanism used to configure serializers and parsers on REST classes.

Per-property behavior can be customized with the @Ini annotation on bean properties:

Annotation attributeDescription
section()Override the section header name for the property
comment()Comment text emitted before the property
json5Encoding()Force JSON5 encoding even for simple values

Media Types​

  • Produces: text/ini
  • Accepts: text/ini, text/x-ini

REST Integration​

INI serializer and parser support are included in BasicUniversalConfig, so REST resources that implement it can produce and consume INI content alongside the other built-in formats:

@Rest
public class MyResource extends RestServlet implements BasicUniversalConfig { ... }

Format-specific options can be applied to a resource with the @IniConfig annotation.

See Also​