Repository: incubator-tamaya Updated Branches: refs/heads/master bdee2dd1e -> 0852f7fe5
[TAMAYA-303] Rewrote the JavaDoc für EnvironmentPropertySource. Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/0852f7fe Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/0852f7fe Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/0852f7fe Branch: refs/heads/master Commit: 0852f7fe5a991a7d128b8d7635e374b5ff529e4d Parents: bdee2dd Author: Oliver B. Fischer <[email protected]> Authored: Fri Sep 22 00:36:12 2017 +0200 Committer: Oliver B. Fischer <[email protected]> Committed: Fri Sep 22 00:36:12 2017 +0200 ---------------------------------------------------------------------- .../EnvironmentPropertySource.java | 68 ++++++++++++++++++-- 1 file changed, 63 insertions(+), 5 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/0852f7fe/code/core/src/main/java/org/apache/tamaya/core/propertysource/EnvironmentPropertySource.java ---------------------------------------------------------------------- diff --git a/code/core/src/main/java/org/apache/tamaya/core/propertysource/EnvironmentPropertySource.java b/code/core/src/main/java/org/apache/tamaya/core/propertysource/EnvironmentPropertySource.java index 85d1f28..6a0e6af 100644 --- a/code/core/src/main/java/org/apache/tamaya/core/propertysource/EnvironmentPropertySource.java +++ b/code/core/src/main/java/org/apache/tamaya/core/propertysource/EnvironmentPropertySource.java @@ -18,16 +18,74 @@ */ package org.apache.tamaya.core.propertysource; +import org.apache.tamaya.spi.PropertySource; import org.apache.tamaya.spi.PropertyValue; import java.util.*; /** - * This {@link org.apache.tamaya.spi.PropertySource} provides all properties which are set - * via - * {@code export myprop=myval} on UNIX Systems or - * {@code set myprop=myval} on Windows. You can disable this feature by setting {@code tamaya.envprops.disable} - * or {@code tamaya.defaults.disable}. + * <p>{@link PropertySource} to access environment variables via Tamaya + * which are set via {@code export VARIABLE=value} on UNIX systems or + * {@code set VARIABLE=value} on Windows systems.</p> + * + * <p>Using the {@linkplain EnvironmentPropertySource} without any + * additional configuration gives access to all existing environment + * variables available to the Java process Tamaya is running in.</p> + * + * <h1>Simple usage example</h1> + * + * <pre> + * $ export OPS_MODE=production + * $ export COLOR=false + * $ java -jar application.jar + * </pre> + * + * <p>To access {@code OPS_MODE} and {@code COLOR} with the following code + * fragment could be used:</p> + * + * <pre> + * PropertySource ps = new EnvironmentPropertySource(); + * PropertyValue opsMode = ps.get("OPS_MODE"); + * PropertyValue color = ps.get("COLOR"); + * </pre> + * + * <h1>Application specific environmet variables with prefix</h1> + * + * <p>Given the case where to instances of the same application are running on + * a single machine but need different values for the environment variable + * {@code CUSTOMER}. The {@linkplain EnvironmentPropertySource} allows you + * to prefix the environment variable with an application specific prefix + * and to access it by the non-prefixed variable name.</p> + * + * <pre> + * $ export CUSTOMER=none + * $ export a81.CUSTOMER=moon + * $ export b78.CUSTOMER=luna + * </pre> + * + * <p>Given an environment with these tree variables the application running + * for the customer called Moon could be started with the following command:</p> + * + * <pre> + * $ java -Dtamaya.envprops.prefix=a81 -jar application.jar + * </pre> + * + * <p>The application specific value can now be accessed from the code of the + * application like this:</p> + * + * <pre> + * PropertySource ps = new EnvironmentPropertySource(); + * PropertyValue pv = ps.get("CUSTOMER"); + * System.out.println(pv.getValue()); + * </pre> + * + * <p>The output of application would be {@code moon}.</p> + * + * <h1>Disabling the access to environment variables</h1> + * + * <p>The access to environment variables could be simply + * disabled by the setting the systemproperty {@code tamaya.envprops.disable} + * or {@code tamaya.defaults.disable} to {@code true}.</p> */ public class EnvironmentPropertySource extends BasePropertySource { private static final String TAMAYA_ENVPROPS_PREFIX = "tamaya.envprops.prefix";
