Merge pull request #83 from eclipse/emily-config

Improve Javadoc etc

api/src/main/java/org/eclipse/microprofile/config/Config.java

@@ -64,14 +64,14 @@ public interface Config {
      *
      * An empty string representation is interpreted as not-existing configuration.
      *
-     * If this method gets used very often then consider to locally store the configured value.
+     * If this method is used very often then consider to locally store the configured value.
      *
      * @param <T>
      *             the property type
      * @param propertyName
      *             The configuration propertyName.
      * @param propertyType
-     *             The type into which the resolve property value should get converted
+     *             The type into which the resolve property value should be converted
      * @return the resolved property value as an Optional of the requested type.
      * The {@link IllegalArgumentException} will be thrown if the property cannot be converted to the specified type.
      */
@@ -85,13 +85,11 @@ public interface Config {
      *
      * @param propertyName
      *             The configuration propertyName.
-     * @return The resolved property value as a String-Optional, which will bypass converters.
+     * @return The resolved property value as a String, which will bypass any converters.
      *
-     * @throws IllegalArgumentException
-     *             is thrown if the propertyName maps to an object that is not a
-     *             String.
+     * 
      */
-    Optional<String> getString(String propertyName);
+    String getRawString(String propertyName);
 
     /**
      * Return a collection of property names.

api/src/main/java/org/eclipse/microprofile/config/ConfigProvider.java

@@ -36,7 +36,7 @@
  * </p>
  *
  * <p>
- * A {@link Config} contains the configuration for a certain situation. That
+ * A {@link Config} contains the configuration for a certain situation. This
  * might be the configuration found in a certain ClassLoader or even a manually
  * created Configuration
  * </p>
@@ -51,7 +51,7 @@
  * A 'Configuration' consists of the information collected from the registered {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources}.
  * These {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} get sorted according to
  * their <em>ordinal</em> defined via {@link org.eclipse.microprofile.config.spi.ConfigSource#getOrdinal()}.
- * That way it is possible to overwrite configuration by providing in a ConfigSource with higher importance from outside.
+ * Thus it is possible to overwrite configuration by providing in a ConfigSource with higher importance from outside.
  * </p>
  *
  * <p>
@@ -105,5 +105,4 @@ public static Config getConfig() {
     public static Config getConfig(ClassLoader cl) {
         return INSTANCE.getConfig(cl);
     }
-
 }

api/src/main/java/org/eclipse/microprofile/config/spi/ConfigProviderResolver.java

@@ -26,10 +26,10 @@
 
 /**
  * This class is not intended to be used by end-users but for
- * portable container integration purpose only!
+ * portable container integration purpose only.
  *
  * Service provider for ConfigProviderResolver. The implementation registers
- * itself via {@link java.util.ServiceLoader} mechanism.
+ * itself via the {@link java.util.ServiceLoader} mechanism.
  *
  * @author <a href="mailto:[email protected]">Mark Struberg</a>
  * @author <a href="mailto:[email protected]">Romain Manni-Bucau</a>
@@ -94,12 +94,12 @@ public static ConfigProviderResolver instance() {
                 if (instance != null) {
                     return instance;
                 }
-                
+
                 ClassLoader cl = AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
                     @Override
-                    public ClassLoader run()  {
+                    public ClassLoader run() {
                         return Thread.currentThread().getContextClassLoader();
-                    }                                  
+                    }
                 });
                 if (cl == null) {
                     cl = ConfigProviderResolver.class.getClassLoader();
@@ -108,7 +108,8 @@ public ClassLoader run()  {
                 ConfigProviderResolver newInstance = loadSpi(cl);
 
                 if (newInstance == null) {
-                    throw new IllegalStateException("No ConfigProviderResolver implementation found!");
+                    throw new IllegalStateException(
+                                    "No ConfigProviderResolver implementation found!");
                 }
 
                 instance = newInstance;
@@ -128,21 +129,22 @@ private static ConfigProviderResolver loadSpi(ClassLoader cl) {
         ConfigProviderResolver instance = loadSpi(cl.getParent());
 
         if (instance == null) {
-            ServiceLoader<ConfigProviderResolver> sl = ServiceLoader.load(ConfigProviderResolver.class, cl);
+            ServiceLoader<ConfigProviderResolver> sl = ServiceLoader.load(
+                            ConfigProviderResolver.class, cl);
             for (ConfigProviderResolver spi : sl) {
                 if (instance != null) {
-                    throw new IllegalStateException("Multiple ConfigResolverProvider implementations found: " + spi.getClass().getName()
-                            + " and " + instance.getClass().getName());
-                }
-                else {
+                    throw new IllegalStateException(
+                                    "Multiple ConfigResolverProvider implementations found: "
+                                                    + spi.getClass().getName() + " and "
+                                                    + instance.getClass().getName());
+                } else {
                     instance = spi;
                 }
             }
         }
         return instance;
     }
 
-
     /**
      * Set the instance. It is used by OSGi environment while service loader
      * pattern is not supported.

api/src/main/java/org/eclipse/microprofile/config/spi/ConfigSource.java

@@ -30,18 +30,18 @@
 import java.util.Map;
 
 /**
- * <p> Represent a config source, which provides properties. The config source includes: properties, xml, json files or datastore. <p>
+ * <p> Represent a config source, which provides properties. The config source can encapsulate: properties, xml, json files or datastore data. <p>
  * The default config sources:
  * <ol>
  * <li>System properties (ordinal=400)</li>
  * <li>Environment properties (ordinal=300)</li>
  * <li>/META-INF/microprofile-config.properties (ordinal=100)</li>
  * </ol>
  * 
- * <p>A ConfigSource will get picked up via the
- * {@link java.util.ServiceLoader} mechanism and must get registered via
+ * <p>ConfigSource will get picked up via the
+ * {@link java.util.ServiceLoader} mechanism and and can be registered via
  * META-INF/services/javax.config.spi.ConfigSource</p>
- * The other custom config source can be added programmatically via {@link org.eclipse.microprofile.config.ConfigProvider}.
+ * Other custom config source can be added programmatically via {@link org.eclipse.microprofile.config.ConfigProvider}.
  * @author <a href="mailto:[email protected]">Mark Struberg</a>
  * @author <a href="mailto:[email protected]">Gerhard Petracek</a>
  * @author <a href="mailto:[email protected]">Emily Jiang</a>

api/src/main/java/org/eclipse/microprofile/config/spi/ConfigSourceProvider.java

@@ -26,17 +26,16 @@
 
 package org.eclipse.microprofile.config.spi;
 
-
 /**
  * <p>Implement this interfaces to provide multiple ConfigSources.
- * This is e.g. needed if there are multiple property files of a given name.</p>
+ * This is needed if there are multiple property files of a given name.</p>
  *
- * <p>If a ConfigSource like JNDI only exists once, then there is no need
- * to implement it via the ConfigSourceProvider but should directly
- * expose a {@link ConfigSource}.</p>
+ * <p>If a single ConfigSource exists, then there is no need
+ * to register it using a custom implementation of ConfigSourceProvider, it can be 
+ * registered directly as a {@link ConfigSource}.</p>
  *
  * <p>A ConfigSourceProvider will get picked up via the
- * {@link java.util.ServiceLoader} mechanism and must get registered via
+ * {@link java.util.ServiceLoader} mechanism and can be registered via
  * META-INF/services/javax.config.spi.ConfigSourceProvider</p>
  *
  * @author <a href="mailto:[email protected]">Mark Struberg</a>

api/src/main/java/org/eclipse/microprofile/config/spi/Converter.java

@@ -32,7 +32,7 @@
  * <p>A Converter can specify a {@link javax.annotation.Priority}.
  * If no priority is explicitly assigned, the value of 100 is assumed.</p>
  *
- * <p>If multiple Converter get found the one with the highest priority will be used.</p>
+ * <p>If multiple Converters are found, the one with the highest priority will be used.</p>
  *
  * <p>The Converter for the following types are automatically enabled:</p>
  * <ul>