Merge branch 'master' into #268

.github/workflows/build.yml

@@ -34,7 +34,7 @@ jobs:
           java-version: ${{matrix.java}}
 
       - name: build with maven
-        run: mvn -B verify --file pom.xml
+        run: mvn -B formatter:validate verify --file pom.xml
 
   quality:
     needs: [build]

.github/workflows/release.yml

@@ -12,7 +12,7 @@ jobs:
     name: release
     if: ${{github.event.pull_request.merged == true}}
     env:
-      GITHUB_TOKEN: ${{secrets.GITHUB_RELEASE_TOKEN}}
+      GITHUB_TOKEN: ${{secrets.RELEASE_TOKEN}}
 
     steps:
       - uses: radcortez/project-metadata-action@master
@@ -24,7 +24,7 @@ jobs:
 
       - uses: actions/checkout@v2
         with:
-          token: ${{secrets.GITHUB_RELEASE_TOKEN}}
+          token: ${{secrets.RELEASE_TOKEN}}
 
       - uses: actions/[email protected]
         with:

README.adoc

@@ -1,7 +1,9 @@
 :microprofile-config: https://github.com/eclipse/microprofile-config/
+:ci: https://github.com/smallrye/smallrye-config/actions?query=workflow%3A%22SmallRye+Build%22
+:sonar: https://sonarcloud.io/dashboard?id=smallrye_smallrye-config
 
-image:https://github.com/smallrye/smallrye-config/workflows/SmallRye%20Build/badge.svg?branch=master[link="https://github.com/smallrye/smallrye-config/actions?query=workflow%3A%22SmallRye+Build%22"]
-image:https://sonarcloud.io/api/project_badges/measure?project=smallrye_smallrye-config&metric=alert_status["Quality Gate Status", link="https://sonarcloud.io/dashboard?id=smallrye_smallrye-config"]
+image:https://github.com/smallrye/smallrye-config/workflows/SmallRye%20Build/badge.svg?branch=master[link={ci}]
+image:https://sonarcloud.io/api/project_badges/measure?project=smallrye_smallrye-config&metric=alert_status["Quality Gate Status", link={sonar}]
 image:https://img.shields.io/github/license/smallrye/smallrye-config.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"]
 
 = SmallRye Config
@@ -10,21 +12,31 @@ SmallRye Config is an implementation of {microprofile-config}[Eclipse MicroProfi
 
 == Instructions
 
-Compile and install this project:
+Compile and test the project:
 
 [source,bash]
 ----
-mvn clean install
+mvn verify
+----
+
+Generate the documentation (from the doc folder):
+
+[source,bash]
+----
+antora generate antora-playbook.yml
 ----
 
 === Project structure
 
+* link:common[] - A set of reusable components to extend SmallRye Config
+* link:doc[] - Project documentation.
 * link:implementation[] - Implementation of the Eclipse MicroProfile Config API.
-* link:testsuite[] - Test suite to run the implementation against the Eclipse MicroProfile Config TCK.
-* link:docs[] - Project documentation.
 * link:sources[] - Implementation of different Eclipse MicroProfile ConfigSources
+* link:testsuite[] - Test suite to run the implementation against the Eclipse MicroProfile Config TCK.
+* link:utils[] - A set of additional extensions to enhance MicroProfile Config
 
 === Links
 
 * http://github.com/smallrye/smallrye-config/[Project Homepage]
 * {microprofile-config}[Eclipse MicroProfile Config]
+* https://smallrye.io/docs/smallrye-config/index.html[Documentation]

doc/antora.yml

@@ -1,5 +1,5 @@
 name: smallrye-config
 title: SmallRye Config
-version: 1.7.1
+version: master
 nav:
   - modules/ROOT/nav.adoc

doc/modules/ROOT/nav.adoc

@@ -1,4 +1,6 @@
 * xref:index.adoc[Index]
 * Extensions
 ** xref:config-sources/config-sources.adoc[Config Sources]
+** xref:converters/converters.adoc[Converters]
 ** xref:interceptors/interceptors.adoc[Interceptors]
+** xref:cdi/cdi.adoc[CDI]

doc/modules/ROOT/pages/cdi/cdi.adoc

@@ -0,0 +1,15 @@
+:doctype: book
+include::../attributes.adoc[]
+
+[[cdi-extensions]]
+
+= CDI Extensions
+
+SmallRye Config provides a set of additional extensions to enhance MicroProfile Config and CDI integration.
+
+* <<config-source-injection>>
+* <<config-events>>
+
+include::config-source-injection.adoc[]
+
+include::config-events.adoc[]

doc/modules/ROOT/pages/cdi/config-events.adoc

@@ -0,0 +1,158 @@
+[[config-events]]
+== Config Events
+
+The Config Events extension allows you to fire change events on Config Sources.
+
+=== Usage
+
+To use the Config Events, add the following to your Maven `pom.xml`:
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+    <groupId>io.smallrye.config</groupId>
+    <artifactId>smallrye-config-events</artifactId>
+    <version>{version}</version>
+</dependency>
+----
+
+=== Events
+
+The CDI Event is a `ChangeEvent` and contains the following fields:
+
+* String key
+* Optional<String> oldValue
+* String newValue
+* Type type
+* String fromSource
+
+The `ChangeEvent` can be of any of the following types:
+
+* NEW - When you create a new key and value (i.e. the key does not exist anywhere in any config source)
+* UPDATE - When you update a value of an existing key (i.e. the key and value exist somewhere in a config source)
+* REMOVE - When you remove the value from the source (and that changed the overall config)
+
+==== Observing Events
+
+You can listen to all or some of these events, filtering by `type` and/or `key` and/or `source`, example:
+
+[source,java]
+----
+// Getting all config event
+public void all(@Observes ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "ALL: Received a config change event: {0}", changeEvent);
+}
+
+// Get only new values
+public void newValue(@Observes @TypeFilter(Type.NEW) ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "NEW: Received a config change event: {0}", changeEvent);
+}
+
+// Get only override values
+public void overrideValue(@Observes @TypeFilter(Type.UPDATE) ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "UPDATE: Received a config change event: {0}", changeEvent);
+}
+
+// Get only revert values
+public void revertValue(@Observes @TypeFilter(Type.REMOVE) ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "REMOVE: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config event when key is some.key
+public void allForKey(@Observes @KeyFilter("some.key") ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "ALL for key [some.key]: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config event when key is some.key for new events
+public void newForKey(@Observes @TypeFilter(Type.NEW) @KeyFilter("some.key") ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "NEW for key [some.key]: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config event when key is some.key for override events
+public void overrideForKey(@Observes @TypeFilter(Type.UPDATE) @KeyFilter("some.key") ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "UPDATE for key [some.key]: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config event when key is some.key for revert events
+public void revertForKey(@Observes @TypeFilter(Type.REMOVE) @KeyFilter("some.key") ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "REMOVE for key [some.key]: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config events for a certain source
+public void allForSource(@Observes @SourceFilter("MemoryConfigSource") ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "ALL for source [MemoryConfigSource]: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config events for a certain source
+public void allForSourceAndKey(@Observes @SourceFilter("MemoryConfigSource") @KeyFilter("some.key")  ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "ALL for source [MemoryConfigSource] and for key [some.key]: Received a config change event: {0}", changeEvent);
+}
+
+// Getting all config events for a certain source
+public void overrideForSourceAndKey(@Observes @TypeFilter(Type.UPDATE) @SourceFilter("MemoryConfigSource") @KeyFilter("some.key")  ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "UPDATE for source [MemoryConfigSource] and for key [some.key]: Received a config change event: {0}", changeEvent);
+}
+----
+
+Note: You can filter by including the `@TypeFilter` and/or the `@KeyFilter` and/or the `@SourceFilter`.
+
+
+==== Pattern matching on field.
+
+You might want to listen for fields that match a certain regex.
+
+Example, listen to all keys that starts with `some.`:
+
+[source,java]
+----
+@RegexFilter("^some\\..+")
+public void allForPatternMatchOnKey(@Observes ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "Pattern match on key: Received a config change event: {0}", changeEvent);
+}
+----
+
+By default, it will match on `key`, however you also listen on another field, for example, listen to all `oldValue`
+that starts with `some.`:
+
+[source,java]
+----
+@RegexFilter(onField = Field.oldValue, value = "^some\\..+")
+public void allForPatternMatchOnOldValue(@Observes ChangeEvent changeEvent){
+    log.log(Level.SEVERE, "Pattern match on old value: Received a config change event: {0}", changeEvent);
+}
+----
+
+You can Match on the following fields of the `ChangeEvent` object:
+
+* key
+* oldValue
+* newValue
+* fromSource
+
+=== Implementing Events in a ConfigSource
+
+The `ChangeEventNotifier` allows you to detect changes and fire the appropriate events.
+
+To use it in your own source:
+
+* Get a snapshot of the properties before the change.
+* Get a snapshot of the properties after the change.
+* Call `detectChangesAndFire` method:
+
+Example:
+
+[source,java]
+----
+Map<String,String> before = new HashMap<>(configSource.getProperties());
+memoryConfigSource.getProperties().remove(key);
+Map<String,String> after = new HashMap<>(configSource.getProperties());
+ChangeEventNotifier.getInstance().detectChangesAndFire(before, after,configSource.getName());
+----
+
+or if you know the change and do not need detection:
+
+[source,java]
+----
+configSource.getProperties().remove(key);
+ChangeEventNotifier.getInstance().fire(new ChangeEvent(Type.REMOVE,key,getOptionalOldValue(oldValue),null,configSource.getName()));
+----

doc/modules/ROOT/pages/cdi/config-source-injection.adoc

@@ -0,0 +1,43 @@
+[[config-source-injection]]
+== Config Source Injection
+
+The Config Source Injection extension allows you to use CDI injection to inject a ConfigSource by name in your CDI
+aware beans, or by looking it up programatically in the CDI `BeanManager`.
+
+=== Usage
+
+To use the Config Source Injection, add the following to your Maven `pom.xml`:
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+    <groupId>io.smallrye.config</groupId>
+    <artifactId>smallrye-config-source-injection</artifactId>
+    <version>{version}</version>
+</dependency>
+----
+
+==== Injecting Sources
+
+You can inject a `ConfigSource` by referencing it by name:
+
+[source,java]
+----
+@Inject
+@Name("MemoryConfigSource")
+private ConfigSource memoryConfigSource;
+
+@Inject
+@Name("SysPropConfigSource")
+private ConfigSource systemPropertiesConfigSource;
+----
+
+You can also get a Map of all config sources. The map key holds the `ConfigSource` name and the map value the
+`ConfigSource`:
+
+[source,java]
+----
+@Inject
+@ConfigSourceMap
+private Map<String,ConfigSource> configSourceMap;
+----

doc/modules/ROOT/pages/converters/converters.adoc

@@ -0,0 +1,12 @@
+:doctype: book
+include::../attributes.adoc[]
+
+[[converters]]
+
+= Converters
+
+SmallRye Config provides a set of additional Converters.
+
+* <<json-converter>>
+
+include::json-converter.adoc[]