Loader API option 3

[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 three 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 3. You may also be interested in Option 1 (#131) and Option 2 (#132).

Sample usage:

Loader loader = loader.bootstrap();
MyConfigurationRelatedObject object = null;
try {
    object = loader.load(Request.builder(MyConfigurationRelatedObject.class).build()).get();
} 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 3 (this PR) differs from Option 2 (#132) primarily by modeling the "loader API" with an explicit Response object as its return value. This provides a place where evolution of what it means to have loaded an object can proceed with minimal damage to the actual loader API itself (the Response interface changes, the load method does not). As in Option 2 (#132), the load method accepts a Request.

In Option 3 (this PR), as in Option 1 (#131) and Option 2 (#132), I followed the group consensus arrived at in #119 (see Dmitry's comment in particular) around the loaded object's determinacy (i.e. that it is unspecified for now to allow for evolution in the future). This option differs from the others in that it supplies a place for that evolution to occur: the Response object can tell you whether it is determinate or not. The Response object may be able to tell you other things about the returned object in the future.

I personally prefer this option over the others, but:

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 3 (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.