Summary

Support expansion of environment variables in jpackage app launcher initialization parameters.

Problem

Initialization parameters for an application can depend on the properties, the exact values of which are unknown when building the application installer. The values of these properties are known at runtime. Currently, jpackage app launcher supports three such properties:

• APPDIR - path to the directory with the application's configuration data;
• BINDIR - path to directory with application launchers;
• ROOTDIR - path to the root application directory.

Suppose user runs jpackage with "--java-options -Dinit-file=$APPDIR/init.cfg" command line. In that case, the jpackage app launcher will set the "init-file" system property to the path of the "init.cfg" file by replacing $APPDIR token with the path to the application's configuration data.

The set of expandable tokens jpackage recognizes is limited. It would be good if it could handle environment variables similarly. E.g., it would be good if for "--java-options -Dinit-file=$HOME/init.cfg" command line, jackage app launcher would replace $HOME substring with value of HOME environment variable.

Solution

Make a jackage app launcher to handle environment variables similarly to how it handles $APPDIR, $BINDIR, and $ROOTDIR tokens.

Specification

In addition to the $APPDIR, $BINDIR, and $ROOTDIR tokens, the jpackage app launcher will recognize $ENV_VAR_NAME and ${ENV_VAR_NAME} patterns.

If $ENV_VAR_NAME syntax is used, the variable name will stop at the first character outside of [A-Za-z_][A-Za-z0-9_]* character range.

If ${ENV_VAR_NAME} syntax is used, the variable name will stop at the first } character after ${ substring.

E.g.:

<table> <tr> <th>String</th> <th>Variables</th> <th>Variable Values</th> <th>Expanded String</th> </tr> <tr> <td>Welcome $USER!</td> <td>USER</td> <td>USER=John</td> <td>Welcome John!</td> </tr> <tr> <td>Welcome $USER2!</td> <td>USER2</td> <td>USER2=John</td> <td>Welcome John!</td> </tr> <tr> <td>Welcome ${USER}2!</td> <td>USER</td> <td>USER=John</td> <td>Welcome John2!</td> </tr> <tr> <td>Welcome $USER-2!</td> <td>USER</td> <td>USER=John</td> <td>Welcome John-2!</td> </tr> </table>

Unset environment variables will not be expanded:

<table> <tr> <th>String</th> <th>Variables</th> <th>Variable Values</th> <th>Expanded String</th> </tr> <tr> <td>Welcome $FOO!</td> <td>FOO</td> <td>not set</td> <td>Welcome $FOO!</td> </tr> </table>

On Windows, names of environment variables are case insensitive, i.e., FOO and foo refer to the same environment variable. On Unix, names of environment variables are case sensitive, i.e., FOO and foo refer to different environment variables. Variable expansion will align with platform specifics:

<table> <tr> <th>String</th> <th>Variables</th> <th>Variable Values</th> <th>Expanded String on Unix</th> <th>Expanded String on Windows</th> </tr> <tr> <td>$USER speaks $LANG</td> <td>USER, LANG</td> <td>USER=Lisa, lang=French</td> <td>Lisa speaks $LANG</td> <td>Lisa speaks French</td> </tr> </table>

\$ substring will prevent variable expansion:

<table> <tr> <th>String</th> <th>Variables</th> <th>Variable Values</th> <th>Expanded String</th> </tr> <tr> <td>Hello \$A! Bye $B</td> <td>B</td> <td>B=John</td> <td>Hello $A! Bye John</td> </tr> <tr> <td>Hello \${A}! Bye $B</td> <td>B</td> <td>B=John</td> <td>Hello ${A}! Bye John</td> </tr> </table>

\\ substring will escape \ character:

<table> <tr> <th>String</th> <th>Variables</th> <th>Variable Values</th> <th>Expanded String</th> </tr> <tr> <td>Hello \\$A! Bye $B</td> <td>A, B</td> <td>A=Ana, B=John</td> <td>Hello \$A! Bye John</td> </tr> </table>

If \ character is not followed by another \ character or $ character, it will be interpreted as a regular character:

<table> <tr> <th>String</th> <th>Expanded String</th> </tr> <tr> <td>a\b\c</td> <td>a\b\c</td> </tr> </table>

Characters between ${ and } substrings will be interpreted as regular characters:

<table> <tr> <th>String</th> <th>Variables</th> </tr> <tr> <td>Hello ${A$B}!</td> <td>A$B</td> </tr> <tr> <td>Hello ${A\\${B}}!</td> <td>A\\${B</td> </tr> </table>

Expansion will be non-recursive:

<table> <tr> <th>String</th> <th>Variables</th> <th>Variable Values</th> <th>Expanded String</th> <th>Notes</th> </tr> <tr> <td>Hello $A!</td> <td>A</td> <td>A=${B}, B=John</td> <td>Hello ${B}!</td> <td>Value of variable "A" is replaced verbatim</td> </tr> </table>

If APPDIR, BINDIR, and ROOTDIR environment variables are set, their values will be ignored and substituted by the values calculated by jpackage app launcher. The names of these environment variables are case-insensitive on Windows and case-sensitive on Unix.

jpackage help file will be updated. Section referencing --arguments and --java-options options will be changed from

--arguments arguments

    Command line arguments to pass to the main class if no command
    line arguments are given to the launcher

    This option can be used multiple times.

--java-options options

    Options to pass to the Java runtime

    This option can be used multiple times.

to

--arguments arguments

    Command line arguments to pass to the main class if no command
    line arguments are given to the launcher

    This option can be used multiple times.

    Value can contain substrings that will be expanded at runtime.
    Two types of such substrings are supported: environment variables
    and "APPDIR", "BINDIR", and "ROOTDIR" tokens.

    An expandable substring should be enclosed between the dollar
    sign character ($) and the first following non-alphanumeric
    character. Alternatively, it can be enclosed between "${" and "}"
    substrings.

    Expandable substrings are case-sensitive on Unix and
    case-insensitive on Windows. No string expansion occurs if the
    referenced environment variable is undefined.

    Environment variables with names "APPDIR", "BINDIR", and "ROOTDIR"
    will be ignored, and these expandable substrings will be
    replaced by values calculated by the app launcher.

    Prefix the dollar sign character with the backslash character (\)
    to prevent substring expansion.

--java-options options

    Options to pass to the Java runtime

    This option can be used multiple times.

    Value can contain substrings that will be substituted at runtime, 
    such as for the --arguments option.