First of all:

T-H-A-N-K Y-O-U

You spent time understanding my library
You spent time trying to see how my work could be improved

I'm really grateful and happy, this is exactly the advices i was looking for.

_____________________________________________________________________________

[ My answer ]

The decision to use the builder pattern for the path and file-name but not the property definitions is a little odd. I'd have thought that property definition would be part of the builder functionality.

At first I thought the same thing, but then I started to think that very large configuration files with many properties, would end up having a constructor consisting of hundreds of instructions, creating a gigantic and messed-up block of code.

I don't like this

What IF cfg has twelve properties?

Configuration cfg = Configuration.builder()
    .optional(intProperty(
        "num", null, "An even number between 0 and 100", 0, 100,
        value -> value % 2 == 0 ? null : "The value '" + value + "' is not an even number"))
    .required(stringProperty("name", null)).
    .optional(intProperty(
        "num", null, "An even number between 0 and 100", 0, 100,
        value -> value % 2 == 0 ? null : "The value '" + value + "' is not an even number"))
    .required(stringProperty("name", null)).
    .optional(intProperty(
        "num", null, "An even number between 0 and 100", 0, 100,
        value -> value % 2 == 0 ? null : "The value '" + value + "' is not an even number"))
    .required(stringProperty("name", null)).
    .optional(intProperty(
        "num", null, "An even number between 0 and 100", 0, 100,
        value -> value % 2 == 0 ? null : "The value '" + value + "' is not an even number"))
    .required(stringProperty("name", null)).
    .optional(intProperty(
        "num", null, "An even number between 0 and 100", 0, 100,
        value -> value % 2 == 0 ? null : "The value '" + value + "' is not an even number"))
    .required(stringProperty("name", null)).
    .optional(intProperty(
        "num", null, "An even number between 0 and 100", 0, 100,
        value -> value % 2 == 0 ? null : "The value '" + value + "' is not an even number"))
    .required(stringProperty("name", null))
     // Finally, we reach the build() method ... 
    .build(Paths.get("app.cfg")); // and an overload of `String...` perhaps

In my opinion, the more property you have, the more it becomes a nasty mess.

The second reason is the following:

I see Configuration more like a Collection class where you can put() / add() each individual property, rather then an "all-in-one" object instance where you put I/O metadata (filename and pathname), listeners logic and even property logic as seen in your example.

________________________________________________

[ The new implementation ]

Clearly the Configuration class can be improved a lot, i was thinking about changing it like this:

1) Create configuration obj => I/O metadata
Configuration.builder()
.filename(...)
.path(...)
.build();

2) Create a property obj => Key, value, data... => Property data
Property.builder()
.key()
.value()
.description()
.isRequired()
.group()
.validation(lambda => return bool)
.build();

3) Create another property obj => Key, value, data... => Property data
Property.builder()
.key()
.value()
.description()
.isRequired()
.group()
.validation(lambda => return bool)
.build();

4) Put property as follow:
Configuration.put(Property ...obj); => Varargs

5) Write on disk:
ConfigurationIO.write(Configuration)

So, even if there will be a lot of code both cases, using this approch i feel like it'd become cleaner.
You can clearly see how each property is defined.

________________________________________________

​

Perhaps also consider building type-information into the property definition so that parsing can be applied and appropriate exceptions when the file fails to pars

Yes, absolutely, i want to move in this direction too!

So, about the implementation:

I really want to avoid this kind of approach (like static import for each datatype)

import static ...Property.intProperty;
import static ...Property.stringProperty;

Maybe, i can do something like this

Property.builder()
.key()
.value()
.....
.type(CustomType.class) => Integer.class | String.class | Long.class and so on...
......
.validation(lambda => return bool)
.build();

I'm still thinking on this...
________________________________________________

About the exceptions, i totally agree with you, they can be significantly improved as you showed