Ini Tutorial - How to use [ini4j] api

This tutorial familiarize the reader with the usage of the [ini4j] library's natural interface.

Code sniplets in this tutorial tested with the following .ini file: dwarfs.ini

Data model

Data model for .ini files is represented by org.ini4j.Ini class. This class implements Map<String,Section>. It mean you can access sections using java.util.Map collection API interface. The Section is also a map, which is implements Map<String,String>.

    void sample01(Ini ini)
        Ini.Section section = ini.get("happy");

        // read some values
        String age = section.get("age");
        String weight = section.get("weight");
        String homeDir = section.get("homeDir");

        // .. or just use java.util.Map interface...
        Map<String, String> map = ini.get("happy");

        age = map.get("age");
        weight = map.get("weight");
        homeDir = map.get("homeDir");

        // get all section names
        Set<String> sectionNames = ini.keySet();

Loading and storing data

There is several way to load data into Ini object. It can be done by using load methods or overloaded constructors. Data can be load from InputStream, Reader, URL or File.

You can store data using store methods. Data can store to OutputStream, Writer, or File.

    void sample02(File file) throws IOException
        Ini ini = new Ini();

        ini.load(new FileReader(file));

        // or instantiate and load data:
        ini = new Ini(new FileReader(file));
        File copy = File.createTempFile("sample", ".ini");;

Macro/variable substitution

To get a value, besides get() you can also use fetch() which resolves any occurrent ${section/option} format variable references in the needed value.

    void sample03(Ini ini)
        Ini.Section dopey = ini.get("dopey");

        // get method doesn't resolve variable references
        String weightRaw = dopey.get("weight");  // = ${bashful/weight}
        String heightRaw = dopey.get("height");  // = ${doc/height}

        // to resolve references, you should use fetch method
        String weight = dopey.fetch("weight");  // = 45.7
        String height = dopey.fetch("height");  // = 87.7

Assuming we have an .ini file with the following sections:

 weight = ${bashful/weight}
 height = ${doc/height}

 weight = 45.7
 height = 98.8

 weight = 49.5
 height = 87.7

Multi values

[ini4j] library introduces MultiMap interface, which is extends normal Map, but allows multiply values per keys. You can simply index values for a given key, similar to indexed properties in JavaBeans api.

    void sample04(Ini ini)
        Ini.Section sneezy = ini.get("sneezy");
        String n1 = sneezy.get("fortuneNumber", 0);  // = 11
        String n2 = sneezy.get("fortuneNumber", 1);  // = 22
        String n3 = sneezy.get("fortuneNumber", 2);  // = 33
        String n4 = sneezy.get("fortuneNumber", 3);  // = 44

        // ok, lets do in it easier...
        int[] n = sneezy.getAll("fortuneNumber", int[].class);

Tree model

Beyond two level map model, Ini class provides tree model. You can access Sections as tree. It means that section names becomes path names, with a path separator character ('/' and '\' on Wini and Reg).

    void sample05()
        Ini ini = new Ini();

        // lets add a section, it will create needed intermediate sections as well

        Ini.Section root;
        Ini.Section sec;

        root = ini.get("root");
        sec = root.getChild("child").getChild("sub");

        // or...
        sec = root.lookup("child", "sub");

        // or...
        sec = root.lookup("child/sub");

        // or even...
        sec = ini.get("root/child/sub");

If you are using Wini instead of Ini class, the path separator become '\'.