Initial *INCOMPLETE* working revision of specification document #170
Conversation
|
This pull request begins to flesh out what a specification should start to look like. There is a ridiculously long way to go. (It incorporates work previously done in #151 (and mostly agreed upon on phone calls although the agreement was never captured in minutes or our discussion areas or the mailing list) which has been closed in favor of this PR, which will be ongoing.) All (hopefully rigorous and precise) words are drawn from (mostly not rigorous or precise) discussions we've had in the past, some of which, but not all, are reachable from the discussions area in this project, some of which, but not all, are inferable from our sparsely-kept meeting minutes, and sadly none of which are present, by majority opinion, on our mailing list for some reason. I've tried diligently to capture the spirit of what I thought people were trying to say. In some cases it was very hard. My point here is: I haven't "snuck anything in". This is all stuff we have said directly or implied. Really. 💥 📣 If you look at this PR only by reading the The specification as it appears in this PR is INCOMPLETE. I still have work to do. If you don't see your Special Pet Subject™ in it, that doesn't necessarily mean I've ignored it. It either means (a) we never discussed it or, more likely, never agreed on it, in which case it doesn't go in the spec yet, or (b) I haven't had time to put it in yet. To evaluate this PR, please check it out and build the project (at least I've also attached a tarball containing the generated HTML files: |
| * <p><strong>\u26A0 Caution:</strong> you are reading an incomplete | ||
| * draft specification that is subject to change.</p> | ||
| */ | ||
| public class InvalidConfigurationClassException extends ConfigException { |
There was a problem hiding this comment.
Maybe just InvalidConfigurationException?
| @@ -48,11 +51,11 @@ | |||
| public interface Loader { | |||
There was a problem hiding this comment.
Wondering if this should be ConfigLoader or ConfigurationLoader?
| * not found. | ||
| * | ||
| * <p><strong>\u26A0 Caution:</strong> you are reading an incomplete | ||
| * draft specification that is subject to change.</p> | ||
| */ | ||
| public class NoSuchObjectException extends ConfigException { |
There was a problem hiding this comment.
Maybe use NoSuchElementException instead of creating a new exception?
| . A `public` instance method of a configuration class may declare parameters. | ||
|
|
||
| .. If a `public`, non-`default` instance method of a configuration class declares parameters, and the configuration | ||
| class is supplied as part of a load request, a Jakarta Config implementation may choose to either: | ||
|
|
||
| ... Implement the method somehow, provided that it fulfils all other structural requirements, or | ||
|
|
||
| ... Implement the method such that it throws either: | ||
|
|
||
| .... a `jakarta.config.NoSuchObjectException`, or | ||
|
|
||
| .... a `java.lang.UnsupportedOperationException` |
There was a problem hiding this comment.
I think we can simplify this, and just don't allow instance methods with parameters.
| <5> This configuration class, considered apart from its members, and apart from its declaring class, represents a | ||
| configuration to which the configuration paths it represents are relative. | ||
|
|
||
| <6> This method, `partNumbers()`, considered on its own, represents a single-element configuration path, comprising a |
There was a problem hiding this comment.
I'm not sure if the representation of the name should be in camelCase. For instance, JPA Jakarta properties use kebab-case.
Signed-off-by: Laird Nelson <[email protected]>
Signed-off-by: Laird Nelson <[email protected]>
Signed-off-by: Laird Nelson <[email protected]>
…PDF generation. Changes are part of cleanup after rebase. Signed-off-by: Laird Nelson <[email protected]>
…face" Signed-off-by: Laird Nelson <[email protected]>
…terface change Signed-off-by: Laird Nelson <[email protected]>
| System.getLogger(Loader.class.getName()) | ||
| .log(System.Logger.Level.DEBUG, absentValueException::getMessage, absentValueException); | ||
| .log(System.Logger.Level.DEBUG, e::getMessage, e); | ||
| return loader; |
There was a problem hiding this comment.
Shouldn't this throw an InvalidConfigurationException?
There was a problem hiding this comment.
Or maybe NoSuchElementException?
| <6> This method, `partNumbers()`, considered on its own, represents a single-element configuration path, comprising a | ||
| single configuration key whose canonical representation is `partNumbers`, relative to the configuration represented by | ||
| its declaring class, that (hopefully) resolves to a `List<Integer>`-typed representation of a configuration value. |
There was a problem hiding this comment.
We need to clarify how each element in the list is represented as well. My proposal is that each element name is determined by enclosing their index in square brackets, like [0].
|
|
||
| CAUTION: You are reading an incomplete DRAFT specification. The following is subject to change. | ||
|
|
||
| == Overview |
There was a problem hiding this comment.
It seems this section is very similar to the Goals section. Maybe they can be merged?
| <1> The `MyConfigurationObject.class` argument is a _xref:terminology.adoc#configuration-interface[configuration | ||
| interface]_ and here represents a _xref:terminology.adoc#load-request[load request]_. | ||
|
|
||
| . *The implementor's `jakarta.config.Loader` implementation builds the object and returns it.* | ||
|
|
||
| .. If the implementor's `jakarta.config.Loader` implementation determines that the supplied load request either: | ||
| ... does not identify a configuration object, or | ||
| ... would result in an invalid configuration object | ||
|
|
||
| + | ||
| …it throws a `jakarta.config.NoSuchObjectException`. |
There was a problem hiding this comment.
Is the goal to specify if such objects are subject to pre-validation? For instance, the Config system, discovers or registers candidates or is it something that happens on the fly (when calling the loader to load)?
No description provided.