Merge pull request #25382 from eclipse-ee4j/ondromih-env-vars-before-sys-props

Option to prefer env vars when resolving variables in JVM options

Author: OndroMih

docs/administration-guide/src/main/asciidoc/jvm.adoc

@@ -55,9 +55,6 @@ xref:reference-manual.adoc#create-jvm-options[`create-jvm-options`] subcommand.
 To create more than one JVM option, use a colon (:) to separate the
 options. If the JVM option itself contains a colon (:), use the
 backslash (\) to offset the colon delimiter.
-+
-Information about properties for the subcommand is included in this help
-page.
 3. To apply your changes, restart {productName}. See
 xref:domains.adoc#to-restart-a-domain[To Restart a Domain].
 
@@ -78,7 +75,7 @@ Command create-jvm-options executed successfully.
 
 See Also
 
-You can also view the full syntax and options of the subcommand by
+You can also view the full syntax and options of the subcommand in the xref:reference-manual.adoc#create-jvm-options[`create-jvm-options`] reference manual, or by
 typing `asadmin help create-jvm-options` at the command line.
 
 [[to-list-jvm-options]]

docs/reference-manual/src/main/asciidoc/create-jvm-options.adoc

@@ -61,8 +61,18 @@ are preceded by the dash character (`-`). For example:
 If the subcommand specifies an option that already exists, the command
 does not re-create the option.
 
+Variable references, e.g. `${variable}`, can be used anywhere in JVM options. In that case, they are resolved as follows:
 
-[NOTE]
+1. Profiler properties in Java Config
+2. System properties in JVM options in Java Config
+3. System properties in instance, cluster, or config that match the instance being started
+4. System properties in the JVM of the server launcher (note that they may be different from properties in the JVM of the server if it starts with a different JVM)
+5. `asenv` properties
+6. Environment variables
+
+If a property `org.glassfish.envPreferredToProperties` is defined as `true` (in any source except environment variables), then environment variables take precedence over other sources, instead of being the last resolved source. It's also possible to override options and system properties defined in JVM options with an environment variable that either has the same name, or same name if case is ignored and non-alphanumeric characters are replaced with the `_` character. For example, a property `-Dmy.name` can be defined by redefined by environment variables `my.name`, `my_name`, or `MY_NAME`.
+
+[CAUTION]
 ====
 Ensure that any option that you create is valid. The subcommand might
 allow you to create an invalid option, but such an invalid option can