Options Tutorial - java.util.Properties replacement

Options (org.ini4j.Options) is a java.util.Properties replacement with several useful features, like:

  • variable/macro substitution. You may refer to other property's value with ${NAME} expression, where NAME is the name of the referred property. ofcourse you can use more than one property reference per property, and you can mix constant text and property references:
    player.name = Joe
player.greetings = Hi ${player.name}!
player.domain = foo.bar
player.email = ${player.name}@${player.domain}
  • multiply property values. You can refer to multi value properties with integer indexes. Ofcource it is also works in macro/variable substitutions: ${user.fortuneNumber[2]}
    player.fortuneNumber = 33
player.fortuneNumber = 44
player.fortuneNumber = 55
player.fortuneNumber = 66

magicNumber = ${player.foruneNumber[1]}

    The magicNumber property will have value: 44

  • as Java class, Options is basicly map of Strings indexed with Strings. It is standard Collection API (ok, it is a bit enhanced to deal with multi values, but in general it is a Map<String,String>).
  • Java Beans api. You can read/write properties in type safe way. To do it you just define an interface, call Options#as() method. This method will provide an implementation of given interface on top of Options. Property types are mapped automatically between Java type and String.

Why need Options

With standard Properties class there is several small problem. Most of them came from backward compatibility.

  • not implements Map<String,String>, but Map<Object,Object>. If you want to use Collections api, it is a bit unconfortable.
  • only single property values allowed. Probably you already see ugly workarounds: index number in property names, like: file.1, file.2 ...
  • no macro/variable substitution. In some environment, like Apache Ant, you can use $name like references, but with standard java.util.Properties you can't.

As side effect of [ini4j] development, there is a solution for aboves. This is the org.ini4j.Options class, which is basicly a feature rich replacement for java.util.Properties.

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

Instantiating

There is nothing special with instantiating Options object, but there is a few constructor, to simplify loading data. These constructors simply call the load() method on newly created instance. Ofcource these constructors are throws IOException.

    void sample01(File file) throws IOException
    {
        Options opt = new Options();

        //
        // or instantiate and load data:
        //
        opt = new Options(new FileReader(file));

Map of String

    void sample02(Options opt)
    {
        Set<String> optionNames = opt.keySet();

        //
        String age = opt.get("age");
        String weight = opt.fetch("weight");
        String height = opt.fetch("height");

The Options is a MultiMap<String,String>, that is, a map that assigns String values to String keys. So the get method is used to get values inside the options. To get a value, besides get() you can also use fetch() which resolves any occurrent ${option} format variable references in the needed value.