CDI API - Direct injection of config values

api/pom.xml

@@ -9,8 +9,8 @@
         <version>0.1-SNAPSHOT</version>
     </parent>
 
-    <groupId>org.eclipse.microprofile.config.api</groupId>
-    <artifactId>microprofile-config-api</artifactId>
+    <groupId>org.eclipse.microprofile.apis</groupId>
+    <artifactId>microprofile-config_1.0_api</artifactId>
     <version>1.0-SNAPSHOT</version>
 
 
@@ -23,6 +23,11 @@
             <scope>provided</scope>
             <optional>true</optional>
         </dependency>
+        <dependency>
+            <groupId>javax.enterprise</groupId>
+            <artifactId>cdi-api</artifactId>
+            <scope>provided</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -66,4 +71,4 @@
             </plugin>
         </plugins>
     </build>
-</project>
+</project>

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

@@ -50,8 +50,10 @@ public interface Config {
      * Return the resolved property value with the specified type for the
      * specified property name from the underlying {@link ConfigSource ConfigSources}.
      *
+     * 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.
-     * 
+     *
      * @param <T>
      *             the property type
      * @param propertyName
@@ -67,6 +69,8 @@ public interface Config {
      * Get an Optional raw string value associated with the given configuration
      * propertyName.
      *
+     * An empty value string is interpreted as not-existing configuration.
+     *
      * @param propertyName
      *             The configuration propertyName.
      * @return The resolved property value as a String-Optional, which will bypass converters.
@@ -84,7 +88,7 @@ public interface Config {
     Iterable<String> getPropertyNames();
 
     /**
-     * @return all currently registered {@link ConfigSource configsources}
+     * @return all currently registered {@link ConfigSource configsources} sorted with descending ordinal
      */
     Iterable<ConfigSource> getConfigSources();
 

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

@@ -20,8 +20,6 @@
 package org.eclipse.microprofile.config;
 
 import org.eclipse.microprofile.config.spi.ConfigProviderResolver;
-import org.eclipse.microprofile.config.spi.ConfigSource;
-import org.eclipse.microprofile.config.spi.Converter;
 
 /**
  * <p>
@@ -41,14 +39,14 @@
  * </p>
  *
  * <p>
- * A 'Configuration' consists of the information collected from the registered {@link ConfigSource ConfigSources}.
- * These {@link ConfigSource ConfigSources} get sorted according to
- * their <em>ordinal</em> defined via {@link ConfigSource#getOrdinal()}.
- * That way it is possible to overwrite configuration with lower importance from outside.
+ * 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.
  * </p>
  *
  * <p>
- * It is also possible to register custom {@link ConfigSource ConfigSources} to flexibly
+ * It is also possible to register custom {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} to flexibly
  * extend the configuration mechanism. An example would be to pick up
  * configuration values from a database table.</p>
  *
@@ -61,6 +59,8 @@
  *         &quot;myproject.some.remote.service.port&quot;, Integer.class);
  * </pre>
  *
+ * For more advanced use cases like e.g. registering a manually created {@link Config} please see
+ * {@link ConfigProviderResolver#registerConfig(Config, ClassLoader)} and {@link ConfigProviderResolver#getBuilder()}.
  *
  * @author <a href="mailto:[email protected]">Mark Struberg</a>
  * @author <a href="mailto:[email protected]">Romain Manni-Bucau</a>
@@ -73,7 +73,7 @@ private ConfigProvider() {
     }
 
     /**
-     * Provide a {@link Config} based on all {@link ConfigSource ConfigSources} of the
+     * Provide a {@link Config} based on all {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} of the
      * current Thread Context ClassLoader (TCCL)
      * The {@link Config} will be stored for future retrieval.
      * <p>
@@ -85,7 +85,7 @@ public static Config getConfig() {
     }
 
     /**
-     * Provide a {@link Config} based on all {@link ConfigSource ConfigSources} of the
+     * Provide a {@link Config} based on all {@link org.eclipse.microprofile.config.spi.ConfigSource ConfigSources} of the
      * specified ClassLoader
      *
      * <p>
@@ -96,93 +96,4 @@ public static Config getConfig(ClassLoader cl) {
         return INSTANCE.getConfig(cl);
     }
 
-    /**
-     * Create a fresh {@link ConfigBuilder} instance. This ConfigBuilder will
-     * initially contain no {@link ConfigSource} but with default {@link Converter Converters} and auto discovered
-     * {@link ConfigSource configsources} and {@link Converter converters}.
-     * Other undiscovered {@link ConfigSource} and {@link Converter Converters} will have to be added manually.
-     *
-     * The ConfigProvider will not manage the Config instance internally
-     */
-    public static ConfigBuilder getBuilder() {
-        return INSTANCE.getBuilder();
-    }
-
-    /**
-     * Register a given {@link Config} within the Application (or Module) identified by the given ClassLoader.
-     * If the ClassLoader is {@code null} then the current Application will be used.
-     *
-     * @param config
-     *          which should get registered
-     * @param classLoader
-     *          which identifies the Application or Module the given Config should get associated with.
-     *
-     * @throws IllegalStateException
-     *          if there is already a Config registered within the Application.
-     *          A user could explicitly use {@link #releaseConfig(Config)} for this case.
-     */
-    public static void setConfig(Config config, ClassLoader classLoader) {
-        INSTANCE.setConfig(config, classLoader);
-    }
-
-    /**
-     * A {@link Config} normally gets released if the Application it is associated with gets destroyed.
-     * Invoke this method if you like to destroy the Config prematurely.
-     *
-     * If the given Config is associated within an Application then it will be unregistered.
-     */
-    public static void releaseConfig(Config config) {
-        INSTANCE.releaseConfig(config);
-    }
-
-    /**
-     * Builder for manually creating an instance of a {@code Config}.
-     *
-     * @see ConfigProvider#getBuilder()
-     */
-    public interface ConfigBuilder {
-        /**
-         * Add the default config sources appearing on the builder's classpath
-         * including:
-         * <ol>
-         * <li>System properties</li>
-         * <li>Environment properties</li>
-         * <li>/META-INF/microprofile-config.properties</li>
-         * </ol>
-         *
-         * @return the ConfigBuilder with the default config sources
-         */
-        ConfigBuilder addDefaultSources();
-
-        /**
-         * Return the ConfigBuilder for a given classloader
-         *
-         * @param loader
-         * @return the ConfigureBuilder for the given classloader
-         */
-        ConfigBuilder forClassLoader(ClassLoader loader);
-
-        /**
-         * Add the specified {@link ConfigSource}.
-         *
-         * @param sources
-         * @return the ConfigBuilder with the configured sources
-         */
-        ConfigBuilder withSources(ConfigSource... sources);
-
-        /**
-         * Add the specified {@link Converter}
-         *
-         * @param converters
-         * @return the ConfigBuilder with the added converters
-         */
-        ConfigBuilder withConverters(Converter<?>... converters);
-
-        /**
-         * Build the {@link Config} object.
-         *
-         * @return the Config object
-         */
-        Config build();
-    }
 }

api/src/main/java/org/eclipse/microprofile/config/inject/ConfigProperty.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2016-2017 Payara Services Ltd. and others
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+package org.eclipse.microprofile.config.inject;
+
+import static java.lang.annotation.ElementType.TYPE;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.PARAMETER;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+import javax.enterprise.util.Nonbinding;
+import javax.inject.Qualifier;
+
+/**
+ * Binds the injection point with a configured value.
+ * Should annotate injection points of type {@code TYPE} or {@code ConfigValue<TYPE>}, 
+ * where {@code TYPE} can be {@code String} and all types which have appropriate converters. 
+ * <p>
+ * Example:
+ * <pre>
+ * <code>
+ *    {@literal @Inject}
+ *    {@literal @ConfigProperty("my.long.property")}
+ *    Long injectedLongValue;  
+ *            // injects value of my.long.property property 
+ * 
+ *   {@literal @Inject}
+ *   {@literal @ConfigProperty("my.long.property")}
+ *   {@literal ConfigValue<Long>} longConfigValue;  
+ *            // injects a ConfigValue for the value of my.long.property property to resolve the property dynamically
+ * </code>
+ * </pre>
+ * @author Ondrej Mihalyi
+ */
+@Qualifier
+@Retention(RUNTIME)
+@Target({METHOD, FIELD, PARAMETER, TYPE})
+public @interface ConfigProperty {
+    /**
+     * The kay of the config property used to look up the configuration value. 
+     * If it is not specified, it will be derived automatically as {@code <class_name>.<injetion_point_name>}, 
+     * where {@code injection_point_name} is either a field name or a property name in case of field/property injection, 
+     * {@code class_name} is the simple name of the class being injected to. 
+     * If one of the {@code class_name} or {@code injection_point_name} cannot be determined, the value has to be provided.
+     * 
+     * @return Name (key) of the config property to inject
+     */
+    @Nonbinding
+    String value() default "";
+}

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

@@ -0,0 +1,76 @@
+/*
+ *******************************************************************************
+ * Copyright (c) 2016-2017 Mark Struberg and others
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ *******************************************************************************/
+package org.eclipse.microprofile.config.spi;
+
+import org.eclipse.microprofile.config.Config;
+
+/**
+ * Builder for manually creating an instance of a {@code Config}.
+ *
+ * @see ConfigProviderResolver#getBuilder()
+ *
+ * @author <a href="mailto:[email protected]">Mark Struberg</a>
+ * @author <a href="mailto:[email protected]">Romain Manni-Bucau</a>
+ * @author <a href="mailto:[email protected]">Emily Jiang</a>
+
+ */
+public interface ConfigBuilder {
+    /**
+     * Add the default config sources appearing on the builder's classpath
+     * including:
+     * <ol>
+     * <li>System properties</li>
+     * <li>Environment properties</li>
+     * <li>/META-INF/microprofile-config.properties</li>
+     * </ol>
+     *
+     * @return the ConfigBuilder with the default config sources
+     */
+    ConfigBuilder addDefaultSources();
+
+    /**
+     * Return the ConfigBuilder for a given classloader
+     *
+     * @param loader
+     * @return the ConfigureBuilder for the given classloader
+     */
+    ConfigBuilder forClassLoader(ClassLoader loader);
+
+    /**
+     * Add the specified {@link ConfigSource}.
+     *
+     * @param sources
+     * @return the ConfigBuilder with the configured sources
+     */
+    ConfigBuilder withSources(ConfigSource... sources);
+
+    /**
+     * Add the specified {@link Converter}
+     *
+     * @param converters
+     * @return the ConfigBuilder with the added converters
+     */
+    ConfigBuilder withConverters(Converter<?>... converters);
+
+    /**
+     * Build the {@link Config} object.
+     *
+     * @return the Config object
+     */
+    Config build();
+}