Documentation for system:properties and system:env

owner-site/site/docs/importing-properties.md

@@ -83,37 +83,47 @@ assertEquals("lime", cfg.bar());
 assertEquals("blackberry", cfg.baz());
 ```
 
-This is pretty handy if you want to reference system properties or environment 
-variables:
+This is pretty handy if you want to load properties provided by other mechanisms which not accessible through any of the supported URI schemes listed under [Loading Strategies](loading-strategies.md)
+
+For instance, a Java EE (a.k.a. Jakarta EE) servlet running on a servlet container might load properties during initialization from a resource accessible through its respective [ServletContext](https://javaee.github.io/javaee-spec/javadocs/javax/servlet/ServletContext.html):
 
 ```java
-interface SystemEnvProperties extends Config {
-    @Key("file.separator")
-    String fileSeparator();
+interface ServletContextProperties extends Config {
+    /** JDBC name of a data source used by the servlet */
+    @Key("ds.name")
+    String dsName();
 
-    @Key("java.home")
-    String javaHome();
+    void list(PrintStream out);
+}
 
-    @Key("HOME")
-    String home();
+...
 
-    @Key("USER")
-    String user();
+public class MyServlet extends HttpServlet {
 
-    void list(PrintStream out);
+    protected void init() {
+        ServletContextProperties cfg = ConfigFactory
+            .create(ServletContextProperties.class, 
+                    getServletConfig().getServletContext().getResourceAsStream("/WEB-INF/myServlet.properties"));
+    }
+</div>
 }
-
-SystemEnvProperties cfg = ConfigFactory
-    .create(SystemEnvProperties.class, 
-            System.getProperties(), 
-            System.getenv());
-
-assertEquals(File.separator, cfg.fileSeparator());
-assertEquals(System.getProperty("java.home"), cfg.javaHome());
-assertEquals(System.getenv().get("HOME"), cfg.home());
-assertEquals(System.getenv().get("USER"), cfg.user());
 ```
 
+<div class="note info">
+Note that this way of proceeding yields the responsibility of proper usage to the client,
+whose code shall never 'forget' to include the <tt>import</tt> parameter when calling the <tt>ConfigFactory.create()</tt> ).
+</div>
+
+Thus, if you want to refer to properties provided by any of the mechanisms directly supported
+by the `@Source` annotation, you should rather use them, as explained in [Loading strategies](/docs/loading-strategies/).
+In particular, to refer to system properties or environment variables,
+you can use (since version 1.0.10) `system:properties` or `system:env` (respectively).
+
+Other typical usage of importing properties might involve loading them from other sources directly
+provided by the execution environment, e.g. [servlet context](https://javaee.github.io/javaee-spec/javadocs/javax/servlet/ServletContext.html) attributes, [context or servlet initialization parameters](https://docs.oracle.com/cd/E19226-01/820-7627/bnaes/index.html), [JNDI](https://docs.oracle.com/javase/tutorial/jndi/index.html) application environment resources (i.e. entries under `java:comp/env/`), [Java preferences](https://docs.oracle.com/javase/8/docs/technotes/guides/preferences/index.html), or any other environment-dependent property sources. However, none of these sources direcly provide an API to access their contents as a `Map` object;
+hence the programmer would need in that case to implement first their own method to convert from lists of names
+plus individual values to `Map` object (therefore compatible with Owner API).
+</div>
 
 Interactions with loading strategies
 ------------------------------------

owner-site/site/docs/loading-strategies.md

@@ -58,7 +58,9 @@ the annotation `@LoadPolicy(LoadType.MERGE)`:
 @LoadPolicy(LoadType.MERGE)
 @Sources({ "file:~/.myapp.config", 
            "file:/etc/myapp.config", 
-           "classpath:foo/bar/baz.properties" })
+           "classpath:foo/bar/baz.properties",
+           "system:properties",
+           "system:env" })
 public interface ServerConfig extends Config {
     ...
 }
@@ -72,9 +74,13 @@ More in detail, this is what will happen:
     if the given property is found the associated value will be returned.
  2. Then it will try to load the given property from /etc/myapp.config;
     if the property is found the value associated will be returned.
- 3. As last resort it will try to load the given property from the classpath from the resource identified
+ 3. Then it will try to load the given property from the classpath from the resource identified
     by the path foo/bar/baz.properties; if the property is found, the associated value is returned.
- 4. If the given property is not found of any of the above cases, it will be returned the value specified by the
+ 4. Otherwise, it will try to load the given property from the <a  href="https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html">Java system properties</a>;
+ if such property is defined, the associated value is returned.
+ 5. As last resort, it will try to load the given property from the <a    href="https://docs.oracle.com/javase/tutorial/essential/environment/env.html">operating system's environment variables</a>;
+ if an environment variable with the same name is found, its value will be returned.    
+ 6. If the given property is not found of any of the above cases, it will be returned the value specified by the
     `@DefaultValue` if specified, otherwise null will be returned.
 
 So basically we produce a merge between the properties files where the first property files overrides latter ones.