Loader API option 2

[ljnelson]

Don't dive into the code without reading this description and understanding it, or without reading and understanding the javadocs.

This pull request is number two of three mutually exclusive options. It sketches a "loader" API for loading configuration-related objects in some vague unspecified manner. This pull request is named Option 2. You may also be interested in Option 1 (#131) and Option 3 (#133).

Sample usage:

Loader loader = loader.bootstrap();
MyConfigurationRelatedObject object = null;
try {
    object = loader.load(Request.builder(MyConfigurationRelatedObject.class).build());
} catch (NoSuchObjectException e) {
    // object is absent
}

In as many cases as I could, I asked for and incorporated some group opinions while working this sketch up. See for example #75, #109, #110, #119, #122 (particularly my comment and Roberto's response), #124, and #127, among others.

Option 2 (this PR) differs from Option 1 (#131) primarily by modeling the "loader API" with an explicit Request object as its sole parameter. This provides a place where evolution of what it means to request an object can proceed with minimal damage to the actual loader API itself (the Request interface changes, the load method does not). The Request comes with an associated Builder; I've sketched one or two additional qualifiers to show what "extra" information might look like. (If you're honed in on the details, you're reading too closely as it is way too early for that kind of thing.)

In Option 2 (this PR), as in Option 1 (#131), the Loader returns the loaded object directly. Following the group consensus arrived at in #119 (see Dmitry's comment in particular), whether or not the return value is determinate is deliberately left unspecified.

I personally prefer Option 3 (#133) which, IMHO, allows for more graceful API evolution over time.

Finally, and perhaps most importantly, I still think it is far too early for PRs and I would prefer to write documents first, but to date that has not met with success. Therefore I hope this (and the other options) will at least get the discussion going.

Signed-off-by: Laird Nelson ljnelson@gmail.com

[ljnelson]

Javadocs for Option 2 (this PR): jakarta.config-api-1.0.0-SNAPSHOT-javadoc.zip

[radcortez]

Closing in favor of #131. We will work on top of that one.