XCOMMONS-3289: Allow overwritting xwiki.properties and xwiki.cfg properties via environment variable and Java system properties

* add documentation

Author: tmortagne

xwiki-commons-core/xwiki-commons-configuration/xwiki-commons-configuration-default/src/main/java/org/xwiki/configuration/internal/SystemEnvConfigurationSource.java

@@ -27,18 +27,23 @@
 import jakarta.inject.Singleton;
 
 import org.xwiki.component.annotation.Component;
+import org.xwiki.configuration.ConfigurationSource;
 
 /**
  * Environment variables based configuration source.
  * <p>
- * To support all systems, we cannot expect environment variable to allow anything else than [a-zA-Z_]+[a-zA-Z0-9_]* so
- * we apply the following encoding:
+ * Environment variable are expected to be prefixed with XCONF_ to be taken into account by this
+ * {@link ConfigurationSource}. Also, to support all systems, we cannot expect environment variable to allow anything
+ * else than [a-zA-Z_]+[a-zA-Z0-9_]* so we apply the following encoding:
  * <ul>
  * <li>., : and - (don’t hesitate if you think of something else that might be common in a configuration file key) are
  * converted to _</li>
  * <li>_ remains _</li>
  * <li>any other forbidden character is converted to _<UTF8, URL style, code></li>
  * </ul>
+ * <p>
+ * For example the {@link ConfigurationSource} property key "configuration.1Key@" will lead the the environment variable
+ * "XCONF_configuration__31Key_40".
  *
  * @version $Id$
  * @since 17.4.0RC1

xwiki-commons-core/xwiki-commons-configuration/xwiki-commons-configuration-default/src/test/java/org/xwiki/configuration/internal/SystemEnvConfigurationSourceTest.java

@@ -104,9 +104,9 @@ void getProperty()
 
         assertEquals("15", this.configuration.getProperty("key1:KEY2_key3.KEY4"));
 
-        this.configuration.getenv().put(SystemEnvConfigurationSource.PREFIX + "_31Key_40", "value");
+        this.configuration.getenv().put(SystemEnvConfigurationSource.PREFIX + "_31Key__40", "value");
 
-        assertEquals("value", this.configuration.getProperty("1Key@"));
+        assertEquals("value", this.configuration.getProperty("1Key.@"));
     }
 
     @Test