Merge pull request #262 from radcortez/#248

ConfigValueConfigSource to retrieve Configuration value location.

doc/modules/ROOT/pages/config-sources/config-sources.adoc

@@ -9,13 +9,16 @@ In addition to the default Config Sources specified by MicroProfile Config (Envi
 and `microprofile-config.properties` file), SmallRye Config provides the following additional Sources:
 
 * <<properties-config-source>>
+* <<configvalueproperties-config-source>>
 * <<filesystem-config-source>>
 * <<hocon-config-source>>
 * <<yaml-config-source>>
 * <<zookeeper-config-source>>
 
 include::properties-config-source.adoc[]
 
+include::configvalueproperties-config-source.adoc[]
+
 include::filesystem-config-source.adoc[]
 
 include::hocon-config-source.adoc[]

doc/modules/ROOT/pages/config-sources/configvalueproperties-config-source.adoc

@@ -0,0 +1,14 @@
+[[configvalueproperties-config-source]]
+== Config Value Properties Config Source
+
+Creates a Config Source with `ConfigValue` support from a properties file (referenced by its URL).
+
+The `ConfigValue` is a metadata object, containing additional information to each configuration. This includes the
+Config Source origin, ordinal, or the line number from where the Config was loaded. This is useful for debugging
+information.
+
+=== Usage
+
+This Config Source is not automatically registered. This means that need to provide your own
+`ConfigSourceProvider` implementation and registration via `ServiceLoader` to use this Config Source like documented in
+MicroProfile Config `ConfigSource` specification.

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

@@ -1,16 +1,33 @@
 package io.smallrye.config;
 
+import java.util.Objects;
+
+/**
+ * The ConfigValue is a metadata object that holds additional information after the lookup of a configuration.
+ * <p>
+ *
+ * Right now, it is able to hold information like the configuration name, value, the Config Source from where
+ * the configuration was loaded, the ordinal of the Config Source and a line number from where the configuration was
+ * read if exists.
+ * <p>
+ *
+ * This is used together with {@link ConfigValueConfigSource} and {@link ConfigSourceInterceptor} to expose the
+ * Configuration lookup metadata.
+ */
 public class ConfigValue {
     private final String name;
     private final String value;
     private final String configSourceName;
     private final int configSourceOrdinal;
 
+    private final int lineNumber;
+
     private ConfigValue(final ConfigValueBuilder builder) {
         this.name = builder.name;
         this.value = builder.value;
         this.configSourceName = builder.configSourceName;
         this.configSourceOrdinal = builder.configSourceOrdinal;
+        this.lineNumber = builder.lineNumber;
     }
 
     public String getName() {
@@ -29,6 +46,10 @@ public int getConfigSourceOrdinal() {
         return configSourceOrdinal;
     }
 
+    public int getLineNumber() {
+        return lineNumber;
+    }
+
     public ConfigValue withName(final String name) {
         return from().withName(name).build();
     }
@@ -45,12 +66,36 @@ public ConfigValue withConfigSourceOrdinal(final int configSourceOrdinal) {
         return from().withConfigSourceOrdinal(configSourceOrdinal).build();
     }
 
+    public ConfigValue withLineNumber(final int lineNumber) {
+        return from().withLineNumber(lineNumber).build();
+    }
+
+    @Override
+    public boolean equals(final Object o) {
+        if (this == o) {
+            return true;
+        }
+        if (o == null || getClass() != o.getClass()) {
+            return false;
+        }
+        final ConfigValue that = (ConfigValue) o;
+        return name.equals(that.name) &&
+                value.equals(that.value) &&
+                configSourceName.equals(that.configSourceName);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(name, value, configSourceName);
+    }
+
     ConfigValueBuilder from() {
         return new ConfigValueBuilder()
                 .withName(name)
                 .withValue(value)
                 .withConfigSourceName(configSourceName)
-                .withConfigSourceOrdinal(configSourceOrdinal);
+                .withConfigSourceOrdinal(configSourceOrdinal)
+                .withLineNumber(lineNumber);
     }
 
     public static ConfigValueBuilder builder() {
@@ -62,6 +107,7 @@ public static class ConfigValueBuilder {
         private String value;
         private String configSourceName;
         private int configSourceOrdinal;
+        private int lineNumber = -1;
 
         public ConfigValueBuilder withName(final String name) {
             this.name = name;
@@ -83,6 +129,11 @@ public ConfigValueBuilder withConfigSourceOrdinal(final int configSourceOrdinal)
             return this;
         }
 
+        public ConfigValueBuilder withLineNumber(final int lineNumber) {
+            this.lineNumber = lineNumber;
+            return this;
+        }
+
         public ConfigValue build() {
             return new ConfigValue(this);
         }

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

@@ -0,0 +1,67 @@
+package io.smallrye.config;
+
+import java.util.Collections;
+import java.util.Map;
+
+import org.eclipse.microprofile.config.spi.ConfigSource;
+
+/**
+ * Extends the original {@link ConfigSource} to expose methods that return a {@link ConfigValue}. The
+ * {@link ConfigValue} allows to retrieve additional metadata associated with the configuration resolution.
+ * <p>
+ *
+ * This is to work around the limitation from the original {@link ConfigSource}. It exposes everything as plain Strings
+ * and it is not possible to retrieve additional information associated with the Configuration. The
+ * ConfigValueConfigSource tries to make this possible.
+ * <p>
+ *
+ * Ideally, this should move the the MicroProfile Config API, once the concept is well-proven.
+ */
+public interface ConfigValueConfigSource extends ConfigSource {
+    /**
+     * Return the {@link ConfigValue} for the specified property in this configuration source.
+     *
+     * @param propertyName the property name
+     * @return the ConfigValue, or {@code null} if the property is not present
+     */
+    ConfigValue getConfigValue(String propertyName);
+
+    /**
+     * Return the properties in this configuration source as a Map of String and {@link ConfigValue}.
+     *
+     * @return a map containing properties of this configuration source
+     */
+    Map<String, ConfigValue> getConfigValueProperties();
+
+    /**
+     * Return the properties in this configuration source as a map.
+     * <p>
+     *
+     * This wraps the original {@link ConfigValue} map returned by
+     * {@link ConfigValueConfigSource#getConfigValueProperties()} and provides a view over the original map
+     * via {@link ConfigValueMapView}.
+     *
+     * @return a map containing properties of this configuration source
+     */
+    @Override
+    default Map<String, String> getProperties() {
+        return Collections.unmodifiableMap(new ConfigValueMapView(getConfigValueProperties()));
+    }
+
+    /**
+     * Return the value for the specified property in this configuration source.
+     * <p>
+     *
+     * This wraps the original {@link ConfigValue} returned by {@link ConfigValueConfigSource#getConfigValue(String)}
+     * and unwraps the property value contained {@link ConfigValue}. If the {@link ConfigValue} is null the unwrapped
+     * value and return is also null.
+     *
+     * @param propertyName the property name
+     * @return the property value, or {@code null} if the property is not present
+     */
+    @Override
+    default String getValue(String propertyName) {
+        final ConfigValue value = getConfigValue(propertyName);
+        return value != null ? value.getValue() : null;
+    }
+}

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

@@ -0,0 +1,123 @@
+package io.smallrye.config;
+
+import java.util.AbstractCollection;
+import java.util.AbstractMap;
+import java.util.AbstractSet;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * The ConfigValueMapView is view over a Map of String configs names and ConfigValue value.
+ * <p>
+ *
+ * Use this to wrap the ConfigValue map and expose it where a Map of String name and String value is required.
+ */
+public class ConfigValueMapView extends AbstractMap<String, String> {
+    private final Map<String, ConfigValue> delegate;
+
+    ConfigValueMapView(final Map<String, ConfigValue> delegate) {
+        this.delegate = Collections.unmodifiableMap(delegate);
+    }
+
+    @Override
+    public int size() {
+        return delegate.size();
+    }
+
+    @Override
+    public boolean isEmpty() {
+        return delegate.isEmpty();
+    }
+
+    @Override
+    public boolean containsKey(final Object key) {
+        return delegate.containsKey(key);
+    }
+
+    @Override
+    public boolean containsValue(final Object value) {
+        return values().contains(value);
+    }
+
+    @Override
+    public String get(final Object key) {
+        final ConfigValue configValue = delegate.get(key);
+        return configValue != null ? configValue.getValue() : null;
+    }
+
+    private transient Set<Map.Entry<String, String>> entrySet;
+    private transient Collection<String> values;
+
+    @Override
+    public Set<String> keySet() {
+        return delegate.keySet();
+    }
+
+    @Override
+    public Set<Map.Entry<String, String>> entrySet() {
+        if (entrySet == null) {
+            entrySet = new AbstractSet<Entry<String, String>>() {
+                @Override
+                public Iterator<Entry<String, String>> iterator() {
+                    return new Iterator<Entry<String, String>>() {
+                        final Iterator<Entry<String, ConfigValue>> delegate = ConfigValueMapView.this.delegate.entrySet()
+                                .iterator();
+
+                        @Override
+                        public boolean hasNext() {
+                            return delegate.hasNext();
+                        }
+
+                        @Override
+                        public Entry<String, String> next() {
+                            final Entry<String, ConfigValue> next = delegate.next();
+                            final ConfigValue configValue = next.getValue();
+                            final String value = configValue != null ? configValue.getValue() : null;
+                            return new AbstractMap.SimpleImmutableEntry<>(next.getKey(), value);
+                        }
+                    };
+                }
+
+                @Override
+                public int size() {
+                    return delegate.size();
+                }
+            };
+        }
+        return entrySet;
+    }
+
+    @Override
+    public Collection<String> values() {
+        if (values == null) {
+            values = new AbstractCollection<String>() {
+                @Override
+                public Iterator<String> iterator() {
+                    final Iterator<ConfigValue> delegate = ConfigValueMapView.this.delegate.values().iterator();
+
+                    return new Iterator<String>() {
+                        @Override
+                        public boolean hasNext() {
+                            return delegate.hasNext();
+                        }
+
+                        @Override
+                        public String next() {
+                            final ConfigValue configValue = delegate.next();
+                            return configValue != null ? configValue.getValue() : null;
+                        }
+                    };
+                }
+
+                @Override
+                public int size() {
+                    return delegate.size();
+                }
+            };
+        }
+        return values;
+    }
+}