Initial *INCOMPLETE* working revision of specification document

api/src/main/java/jakarta/config/ConfigException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2023 Contributors to the Eclipse Foundation
  *
  * See the NOTICE file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -21,6 +21,9 @@
 /**
  * A {@link RuntimeException} thrown when a problem is encountered in
  * an implementation of the Jakarta Config specfication.
+ *
+ * <p><strong>\u26A0 Caution:</strong> you are reading an incomplete
+ * draft specification that is subject to change.</p>
  */
 public class ConfigException extends RuntimeException {
 

api/src/main/java/jakarta/config/InvalidConfigurationClassException.java

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2023 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package jakarta.config;
+
+/**
+ * A {@link ConfigException} thrown when a configuration class was
+ * found to be invalid.
+ *
+ * <p><strong>\u26A0 Caution:</strong> you are reading an incomplete
+ * draft specification that is subject to change.</p>
+ */
+public class InvalidConfigurationClassException extends ConfigException {
+
+    /**
+     * Creates a new {@link InvalidConfigurationClassException}.
+     */
+    public InvalidConfigurationClassException() {
+        super();
+    }
+
+    /**
+     * Creates a new {@link InvalidConfigurationClassException}.
+     *
+     * @param message a detail message; may be {@code null}
+     */
+    public InvalidConfigurationClassException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new {@link InvalidConfigurationClassException}.
+     *
+     * @param cause the {@link Throwable} responsible for this {@link
+     * InvalidConfigurationClassException}'s existence; may be {@code null}
+     */
+    public InvalidConfigurationClassException(Throwable cause) {
+        super(cause);
+    }
+
+    /**
+     * Creates a new {@link InvalidConfigurationClassException}.
+     *
+     * @param message a detail message; may be {@code null}
+     *
+     * @param cause the {@link Throwable} responsible for this {@link
+     * InvalidConfigurationClassException}'s existence; may be {@code null}
+     */
+    public InvalidConfigurationClassException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+}

api/src/main/java/jakarta/config/Loader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2023 Contributors to the Eclipse Foundation
  *
  * See the NOTICE file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -21,14 +21,17 @@
 import java.util.ServiceLoader;
 
 /**
- * A loader of configuration-related objects.
+ * A loader of configuration objects.
+ *
+ * <p><strong>\u26A0 Caution:</strong> you are reading an incomplete
+ * draft specification that is subject to change.</p>
  *
  * <p>Sample usage:</p>
  *
  * <blockquote><pre>{@linkplain Loader Loader} loader = {@linkplain Loader Loader}.{@linkplain Loader#bootstrap() bootstrap()};
- *MyConfigurationRelatedObject object = null;
+ *MyConfigurationObject object = null;
  *try {
- *  object = loader.{@linkplain #load(Class) load(MyConfigurationRelatedObject.class)};
+ *  object = loader.{@linkplain #load(Class) load(MyConfigurationObject.class)};
  *} catch ({@linkplain NoSuchObjectException} noSuchObjectException) {
  *  // object is <a href="doc-files/terminology.html#absent">absent</a>
  *} catch ({@linkplain ConfigException} configException) {
@@ -48,11 +51,11 @@
 public interface Loader {
 
     /**
-     * Loads a configuration-related object of the supplied {@code
-     * type} and returns it.
+     * Loads a configuration object of the supplied {@code type} and
+     * returns it.
      *
      * <p><strong>Note:</strong> The rules governing how it is
-     * determined whether any given configuration-related object is
+     * determined whether any given configuration object is
      * "of the supplied {@code type}" are currently wholly
      * undefined.</p>
      *
@@ -79,60 +82,21 @@ public interface Loader {
      * but the requested object was <a
      * href="doc-files/terminology.html#absent">absent</a>
      *
-     * @exception ConfigException if the invocation was sound but the
-     * object could not be loaded for any reason not related to <a
-     * href="doc-files/terminology.html#absent">absence</a>
-     *
-     * @exception IllegalArgumentException if the suplied {@code type}
-     * was invalid for any reason
-     *
-     * @exception NullPointerException if the supplied {@code type}
-     * was {@code null}
-     */
-    public <T> T load(Class<T> type);
-
-    /**
-     * Loads a configuration-related object of the supplied {@code
-     * type} and returns it.
-     *
-     * <p><strong>Note:</strong> The rules governing how it is
-     * determined whether any given configuration-related object is
-     * "of the supplied {@code type}" are currently wholly
-     * undefined.</p>
-     *
-     * <p>Implementations of this method must not return {@code
-     * null}.</p>
-     *
-     * <p>Implementations of this method must be idempotent.</p>
-     *
-     * <p>Implementations of this method must be safe for concurrent
-     * use by multiple threads.</p>
-     *
-     * <p>Implementations of this method may or may not return a <a
-     * href="doc-files/terminology.html#determinate">determinate</a>
-     * value.</p>
-     *
-     * @param <T> the type of object to load
-     *
-     * @param type the type of object to load; must not be {@code null}
-     *
-     * @return the loaded object; never {@code null}
-     *
-     * @exception NoSuchObjectException if the invocation was sound
-     * but the requested object was <a
-     * href="doc-files/terminology.html#absent">absent</a>
+     * @exception InvalidConfigurationClassException if the supplied
+     * configuration class was structurally invalid
      *
      * @exception ConfigException if the invocation was sound but the
      * object could not be loaded for any reason not related to <a
      * href="doc-files/terminology.html#absent">absence</a>
      *
-     * @exception IllegalArgumentException if the suplied {@code type}
-     * was invalid for any reason
+     * @exception IllegalArgumentException if the supplied {@code
+     * type} was invalid for any reason other than structural
+     * invalidity
      *
      * @exception NullPointerException if the supplied {@code type}
      * was {@code null}
      */
-    public <T> T load(TypeToken<T> type);
+    public <T> T load(Class<T> type);
 
     /**
      * <em>{@linkplain #bootstrap(ClassLoader) Bootstraps}</em> a
@@ -246,9 +210,9 @@ public static Loader bootstrap(ClassLoader classLoader) {
             .orElseThrow(NoSuchObjectException::new);
         try {
             return loader.load(Loader.class);
-        } catch (NoSuchObjectException absentValueException) {
+        } catch (NoSuchObjectException | UnsupportedOperationException e) {
             System.getLogger(Loader.class.getName())
-                .log(System.Logger.Level.DEBUG, absentValueException::getMessage, absentValueException);
+                .log(System.Logger.Level.DEBUG, e::getMessage, e);
             return loader;
         }
     }

api/src/main/java/jakarta/config/NoSuchObjectException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Contributors to the Eclipse Foundation
+ * Copyright (c) 2022, 2023 Contributors to the Eclipse Foundation
  *
  * See the NOTICE file(s) distributed with this work for additional
  * information regarding copyright ownership.
@@ -19,8 +19,11 @@
 package jakarta.config;
 
 /**
- * A {@link ConfigException} thrown when a configuration-related
- * object was not found.
+ * A {@link ConfigException} thrown when a configuration object was
+ * 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 {