#59 - Added javadocs.

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

@@ -2,6 +2,18 @@
 
 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;

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

@@ -1,36 +1,63 @@
 package io.smallrye.config;
 
-import static java.util.stream.Collectors.toMap;
-
 import java.util.Map;
-import java.util.Set;
-import java.util.function.Function;
 
 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 getConfigValueProperties().entrySet()
- .stream()
- .collect(toMap(Map.Entry::getKey,
- new Function<Map.Entry<String, ConfigValue>, String>() {
- @Override
- public String apply(final Map.Entry<String, ConfigValue> entry) {
- return entry.getValue() != null ? entry.getValue().getValue() : null;
- }
- }));
- }
-
- @Override
- default Set<String> getPropertyNames() {
- return getProperties().keySet();
+ return 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);

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

@@ -5,6 +5,13 @@
 import java.io.Reader;
 import java.util.HashMap;
 
+/**
+ * Loads properties as {@link ConfigValue}.
+ * <p>
+ *
+ * This class is mostly a subset copy of {@link java.util.Properties}. This was required to be able to keep track of
+ * the line number from which the configuration was loaded.
+ */
 class ConfigValueProperties extends HashMap<String, ConfigValue> {
  private final String configSourceName;
  private final int configSourceOrdinal;