Implements getEnvironmentProperty to allow environment variable configuration

This commit add unit test and documentation regarding the improvement

Thanks Eugen for the review

Author: gilPts

docs/asciidoc/developer-manual.adoc

@@ -289,6 +289,7 @@ For a core configuration guide check
 https://cwiki.apache.org/confluence/display/OFBIZ/Framework+Configuration+Guide[the OFBiz configuration Guide]
  (some points are not up to date).
 
+include::../../framework/base/src/docs/asciidoc/configuration.adoc[leveloffset=+2]
 
 include::../../framework/base/src/docs/asciidoc/email.adoc[leveloffset=+2]
 

framework/base/src/docs/asciidoc/_include/env-config.adoc

@@ -0,0 +1,41 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you 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.
+////
+= Configuration by environment variable
+
+https://issues.apache.org/jira/browse/OFBIZ-9498[OFBIZ-9498] introduce a new way to configure an OFBiz instance at
+launch using environment variable.
+
+This is a first intermediate step of the task, that allow configuration without modifying
+source code of a distributed OFBiz artefact.
+
+Currently, some configurations are designed to be set through environment variable :
+
+* framework/entity/config/entityengine.xml for database access credentials
+** jdbc-uri="${env:OFB_POSTGRES_DB:jdbc:postgresql://127.0.0.1/ofbiz}"
+** jdbc-username="${env:OFB_POSTGRES_USER:ofbiz}"
+** jdbc-password="${env:OFB_POSTGRES_PASS:ofbiz}"
+
+* framework/common/config/general.properties
+** unique.instanceId=${env:OFB_INSTANCE_ID:ofbiz1}
+
+Others could be designed using the same notation `${env:ENV_NAME:DEFAULT_VALUE}`, such as :
+
+* any property in the `*.properties` files
+* In `serviceengine.xml`, for new specific service engine, to allow api access credential configuration by the Ops.
+

framework/base/src/docs/asciidoc/configuration.adoc

@@ -0,0 +1,21 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you 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.
+////
+= Configuration System
+
+include::_include/env-config.adoc[leveloffset=+2]

framework/base/src/main/java/org/apache/ofbiz/base/util/UtilProperties.java

@@ -991,10 +991,11 @@ public static Properties xmlToProperties(InputStream in, Locale locale, Properti
     /**
      * Resolve a property to check if it contains an environment variable
      * represented by ${env:ENV_VARIABLE:DEFAULT_VALUE}
-     * @param value
-     * @return
+     * @param env : map that contains available env variables
+     * @param value : the property to resolve
+     * @return resolved value
      */
-    public static String getEnvironmentProperty(String value) {
+    public static String getEnvironmentProperty(Map<String, String> env, String value) {
         if (value != null) {
             if (value.startsWith("${env:") && value.endsWith("}")) {
                 String envNameWithDefault = value.substring(6, value.length() - 1);
@@ -1004,7 +1005,7 @@ public static String getEnvironmentProperty(String value) {
                     environmentName = envNameWithDefault.substring(0, envNameWithDefault.indexOf(":"));
                     defaultValue = envNameWithDefault.substring(envNameWithDefault.indexOf(":") + 1);
                 }
-                String environmentValue = System.getenv(environmentName);
+                String environmentValue = env.get(environmentName);
                 if (environmentValue != null) {
                     return environmentValue;
                 }
@@ -1017,6 +1018,16 @@ public static String getEnvironmentProperty(String value) {
         return value;
     }
 
+    /**
+     * Resolve a property to check if it contains an environment variable
+     * represented by ${env:ENV_VARIABLE:DEFAULT_VALUE}
+     * @param value : the property to resolve
+     * @return resolved value
+     */
+    public static String getEnvironmentProperty(String value) {
+        return getEnvironmentProperty(System.getenv(), value);
+    }
+
     /** Custom ResourceBundle class. This class extends ResourceBundle
      * to add custom bundle caching code and support for the OFBiz custom XML
      * properties file format.

framework/base/src/test/java/org/apache/ofbiz/base/util/UtilPropertiesTests.java

@@ -26,9 +26,12 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.nio.charset.Charset;
+import java.util.HashMap;
 import java.util.Locale;
+import java.util.Map;
 import java.util.Properties;
 
+import com.google.common.collect.ImmutableMap;
 import org.junit.Test;
 
 public class UtilPropertiesTests {
@@ -78,4 +81,25 @@ private Properties xmlToProperties(String separator) throws IOException {
             return UtilProperties.xmlToProperties(in, locale, null);
         }
     }
+
+    /**
+     * Environment Variable property retrieval
+     * Test that default value is retrieved if no variable set.
+     */
+    @Test
+    public void testEnvironmentPropertyDefaultValue() {
+        String value = UtilProperties.getEnvironmentProperty(new HashMap<>(), "${env:ENV_VARIABLE:DEFAULT_VALUE}");
+        assertEquals("DEFAULT_VALUE", value);
+    }
+
+    /**
+     * Environment Variable property retrieval
+     * Test that defined value is retrieved if env variable set.
+     */
+    @Test
+    public void testEnvironmentPropertyMatch() {
+        Map<String, String> env = ImmutableMap.of("ENV_VARIABLE", "SET_VALUE");
+        String value = UtilProperties.getEnvironmentProperty(env, "${env:ENV_VARIABLE:DEFAULT_VALUE}");
+        assertEquals("SET_VALUE", value);
+    }
 }