Introduce EnhancedConfig

implementation/src/main/java/io/smallrye/config/EnhancedConfig.java

@@ -0,0 +1,162 @@
+package io.smallrye.config;
+
+import java.io.Serializable;
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.NoSuchElementException;
+import java.util.Optional;
+import java.util.function.IntFunction;
+
+import org.eclipse.microprofile.config.Config;
+import org.eclipse.microprofile.config.spi.ConfigSource;
+import org.eclipse.microprofile.config.spi.Converter;
+
+import io.smallrye.common.annotation.Experimental;
+
+public interface EnhancedConfig extends Config, Serializable {
+    String SMALLRYE_CONFIG_PROFILE = "smallrye.config.profile";
+    String SMALLRYE_CONFIG_PROFILE_PARENT = "smallrye.config.profile.parent";
+    String SMALLRYE_CONFIG_LOCATIONS = "smallrye.config.locations";
+    String SMALLRYE_CONFIG_MAPPING_VALIDATE_UNKNOWN = "smallrye.config.mapping.validate-unknown";
+    String SMALLRYE_CONFIG_LOG_VALUES = "smallrye.config.log.values";
+
+    <T, C extends Collection<T>> C getValues(String name, Class<T> itemClass, IntFunction<C> collectionFactory);
+
+    <T, C extends Collection<T>> C getValues(String name, Converter<T> converter, IntFunction<C> collectionFactory);
+
+    <T, C extends Collection<T>> C getIndexedValues(String name, Converter<T> converter,
+            IntFunction<C> collectionFactory);
+
+    List<String> getIndexedProperties(String property);
+
+    List<Integer> getIndexedPropertiesIndexes(String property);
+
+    /**
+     * Return the content of the direct sub properties as the requested type of Map.
+     *
+     * @param name The configuration property name
+     * @param kClass the type into which the keys should be converted
+     * @param vClass the type into which the values should be converted
+     * @param <K> the key type
+     * @param <V> the value type
+     * @return the resolved property value as an instance of the requested Map (not {@code null})
+     * @throws IllegalArgumentException if a key or a value cannot be converted to the specified types
+     * @throws NoSuchElementException if no direct sub properties could be found.
+     */
+    <K, V> Map<K, V> getValues(String name, Class<K> kClass, Class<V> vClass);
+
+    /**
+     * Return the content of the direct sub properties as the requested type of Map.
+     *
+     * @param name The configuration property name
+     * @param keyConverter The converter to use for the keys.
+     * @param valueConverter The converter to use for the values.
+     * @param <K> The type of the keys.
+     * @param <V> The type of the values.
+     * @return the resolved property value as an instance of the requested Map or {@code null} if it could not be found.
+     * @throws IllegalArgumentException if a key or a value cannot be converted to the specified types
+     */
+    <K, V> Map<K, V> getValuesAsMap(String name, Converter<K> keyConverter, Converter<V> valueConverter);
+
+    /**
+     * This method handles calls from both {@link Config#getValue} and {@link Config#getOptionalValue}.<br>
+     */
+    <T> T getValue(String name, Converter<T> converter);
+
+    /**
+     * This method handles converting values for both CDI injections and programatical calls.<br>
+     * <br>
+     * <p>
+     * Calls for converting non-optional values ({@link Config#getValue} and "Injecting Native Values")
+     * should throw an {@link Exception} for each of the following:<br>
+     * <p>
+     * 1. {@link IllegalArgumentException} - if the property cannot be converted by the {@link Converter} to the specified type
+     * <br>
+     * 2. {@link NoSuchElementException} - if the property is not defined <br>
+     * 3. {@link NoSuchElementException} - if the property is defined as an empty string <br>
+     * 4. {@link NoSuchElementException} - if the {@link Converter} returns {@code null} <br>
+     * <br>
+     * <p>
+     * Calls for converting optional values ({@link Config#getOptionalValue} and "Injecting Optional Values")
+     * should only throw an {@link Exception} for #1 ({@link IllegalArgumentException} when the property cannot be converted to
+     * the specified type).
+     */
+    <T> T convertValue(ConfigValue configValue, Converter<T> converter);
+
+    /**
+     * Determine whether the <em>raw value</em> of a configuration property is exactly equal to the expected given
+     * value.
+     *
+     * @param name the property name (must not be {@code null})
+     * @param expected the expected value (may be {@code null})
+     * @return {@code true} if the values are equal, {@code false} otherwise
+     */
+    boolean rawValueEquals(String name, String expected);
+
+    @Override
+    ConfigValue getConfigValue(String name);
+
+    /**
+     * Get the <em>raw value</em> of a configuration property.
+     *
+     * @param name the property name (must not be {@code null})
+     * @return the raw value, or {@code null} if no property value was discovered for the given property name
+     */
+    String getRawValue(String name);
+
+    /**
+     * Return the content of the direct sub properties as the requested type of Map.
+     *
+     * @param name The configuration property name
+     * @param kClass the type into which the keys should be converted
+     * @param vClass the type into which the values should be converted
+     * @param <K> the key type
+     * @param <V> the value type
+     * @return the resolved property value as an instance of the requested Map (not {@code null})
+     * @throws IllegalArgumentException if a key or a value cannot be converted to the specified types
+     */
+    <K, V> Optional<Map<K, V>> getOptionalValues(String name, Class<K> kClass, Class<V> vClass);
+
+    <T> Optional<T> getOptionalValue(String name, Converter<T> converter);
+
+    <T, C extends Collection<T>> Optional<C> getOptionalValues(String name, Class<T> itemClass,
+            IntFunction<C> collectionFactory);
+
+    <T, C extends Collection<T>> Optional<C> getOptionalValues(String name, Converter<T> converter,
+            IntFunction<C> collectionFactory);
+
+    <T, C extends Collection<T>> Optional<C> getIndexedOptionalValues(String name, Converter<T> converter,
+            IntFunction<C> collectionFactory);
+
+    ConfigMappings getConfigMappings();
+
+    <T> T getConfigMapping(Class<T> type);
+
+    <T> T getConfigMapping(Class<T> type, String prefix);
+
+    /**
+     * Checks if a property is present in the {@link Config} instance.
+     * <br>
+     * Because {@link ConfigSource#getPropertyNames()} may not include all available properties, it is not possible to
+     * reliably determine if the property is present in the properties list. The property needs to be retrieved to make
+     * sure it exists. The lookup is done without expression expansion, because the expansion value may not be
+     * available, and it is not relevant for the final check.
+     *
+     * @param name the property name.
+     * @return true if the property is present or false otherwise.
+     */
+    @Experimental("Check if a property is present")
+    boolean isPropertyPresent(String name);
+
+    Iterable<ConfigSource> getConfigSources(Class<?> type);
+
+    @Experimental("To retrieve a ConfigSource by name")
+    Optional<ConfigSource> getConfigSource(String name);
+
+    <T> T convert(String value, Class<T> asType);
+
+    <T> Converter<T> requireConverter(Class<T> asType);
+
+    List<String> getProfiles();
+}