371 - clarify javadoc on config.getConfigSources (#581)

* 371 - clarify javadoc on config.getConfigSources Signed-off-by: Emily Jiang <[email protected]>
eclipse · Aug 24, 2020 · 4257183 · 4257183
1 parent a908d5f
commit 4257183
Show file tree

Hide file tree

Showing 5 changed files with 12 additions and 7 deletions.
diff --git a/.gitignore b/.gitignore
@@ -16,4 +16,4 @@ test-output
 .vscode/
 # Ignore a release.conf for perform_release/* script usage
 release.conf
-spec/.DS_Store
+*/.DS_Store
diff --git a/api/src/main/java/org/eclipse/microprofile/config/Config.java b/api/src/main/java/org/eclipse/microprofile/config/Config.java
@@ -267,9 +267,10 @@ default <T> Optional<List<T>> getOptionalValues(String propertyName, Class<T> pr
 
     /**
      * Return all of the currently registered {@linkplain ConfigSource configuration sources} for this configuration.
-     * The returned sources will be sorted by descending ordinal value and name, which can be iterated in a thread-safe
-     * manner.
-     *
+     * <p>
+     * The returned sources will be sorted by descending ordinal value and name, which can be iterated in a thread-safe 
+     * manner. The {@link java.lang.Iterable Iterable} contains a fixed number of {@linkplain ConfigSource configuration sources}, 
+     * determined at application start time, and the config sources themselves may be static or dynamic.
      * @return the configuration sources
      */
     Iterable<ConfigSource> getConfigSources();

diff --git a/api/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java b/api/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java
@@ -44,8 +44,10 @@
  */
 public interface ConfigSourceProvider {
     /**
-     * Return the {@link ConfigSource} instances that are provided by this provider. An empty {@code Iterable} may
-     * be returned if no sources are to be provided.
+     * Return the {@link ConfigSource} instances that are provided by this provider.  
+     * The {@link java.lang.Iterable Iterable} contains a fixed number of {@linkplain ConfigSource configuration sources}, 
+     * determined at application start time, and the config sources themselves may be static or dynamic.
+     * An empty {@link java.lang.Iterable Iterable} may be returned if no sources are to be provided.
      *
      * @param forClassLoader the class loader which should be used for discovery and resource loading purposes
      * @return the {@link ConfigSource} instances to register to the configuration

diff --git a/spec/src/main/asciidoc/configsources.asciidoc b/spec/src/main/asciidoc/configsources.asciidoc
@@ -24,7 +24,8 @@
 == ConfigSources
 
 A `ConfigSource` is exactly what its name says: a source for configured values.
-The `Config` uses all configured implementations of `ConfigSource` to look up the property in question.
+The `Config` uses all configured implementations of `ConfigSource` to look up the property in question. Dynamically added config sources after the `Config` object has been built would be ignored, 
+which means `Config.getConfigSources` always returns the same collection of `ConfigSource`s. The same rule applies to `ConfigSourceProvider.getConfigSources`.
 
 === ConfigSource Ordering
 

diff --git a/spec/src/main/asciidoc/release_notes.asciidoc b/spec/src/main/asciidoc/release_notes.asciidoc
@@ -45,6 +45,7 @@ A full list of changes delivered in the 2.0 release can be found at link:https:/
 - Update to Jakarta EE8 APIs for MP 4.0 (link:https://github.com/eclipse/microprofile-config/issues/469[469])
 - Enable MicroProfile Config repo to be built with Java 11 (link:https://github.com/eclipse/microprofile-config/issues/555[555])
 - TCK changes: (link:https://github.com/eclipse/microprofile-config/issues/563[563]) (link:https://github.com/eclipse/microprofile-config/issues/319[319])
+- Spec clarification: (link:https://github.com/eclipse/microprofile-config/issues/371[371])
 
 [[release_notes_14]]
 == Release Notes for MicroProfile Config 1.4