Java Options with windows-special-character in Windows Batch Scripts (.cmd or .bat)

How does a batch script work?

When you run a batch script, the Windows Command Prompt reads and executes the commands line by line. The Command Prompt opens the .bat or .cmd file and reads it line by line.

Each line is treated as a command or instruction. These scripts are used to automate tasks, run programs, or perform system operations.

What is evaluation and interpretation?

Evaluating Variables

Batch scripts use variables to store and manipulate data. Variables are defined using the set command.

set NAME=John
echo Hello, %NAME%!

%NAME% is replaced with the value John when the script runs.

Interpreting Special Characters

Some characters have special meanings in batch scripts.

Some characters have special meanings in batch scripts. 
For example:

1) | (pipe): Redirects the output of one command to another.

2) > (greater than): Redirects output to a file.

3) & (ampersand): Combines multiple commands on one line.

4) ^ (caret): Escapes special characters so they are treated as literal text.
example:

Example: 
    - echo This is a pipe symbol: ^|
The ^ tells the script to treat | as a literal character, not as a special operator.

Commonly encountered issue

Usage of -Djava.protocol.handler.pkgs, this property specifies a list of packages that Java should search for custom protocol handlers. These handlers allow Java to support custom URL protocols (e.g., http, ftp, or custom protocols). Many products in FMW extend the use of this property by providing multiple packages separated by the pipe '|' character.

For example:

-Djava.protocol.handler.pkgs=com.example.pkg1|com.example.pkg2

When this property is used in Windows batch scripts, the pipe '|' character creates confusion for the Command Prompt. The Command Prompt interprets the pipe as a special character for command chaining (e.g., redirecting output from one command to another), rather than treating it as part of the Java property value(separator).

set JAVA_OPTIONS=-Djava.protocol.handler.pkgs=pqr.net.protocol|abc.net

This assignment is correct, but there is a problem when the value contains characters that should not be treated as special characters (like the pipe |). For example, if JAVA_OPTIONS contains a pipe (|), it will cause an error when the variable is used later in the script.

The error will say something like:
'abc.net' is not recognized as an internal or external command. This happens because the Command Prompt interprets the pipe (|) as a redirection character instead of treating it as part of the value.

Resolution

To avoid issues, we need to escape the special character (using ^) so that the Windows Command Prompt does not misinterpret it. This ensures that the value is passed correctly to the Java command during execution, where Java will treat the pipe (|) as a separator and not as a special character.

To achieve this:

Use the Windows escape character ^ to prevent the Command Prompt from interpreting the pipe '|' as a special character.

This ensures that echo statements or other commands do not misinterpret the content and treat the string after the pipe '|' as a batch command.

If the assignment is unquoted, partially quoted, or fully unquoted, the command prompt will interpret any special characters (like |, &, >, etc.) and cause issues. Escaping the special character avoids this problem.

The recommended way to handle this is to ensure the Windows command prompt treats the entire assignment (key and value) as a single string. This can be achieved by enclosing the assignment in double quotes. By doing this, the first unquoted assignment will only occur when the value is passed to the Java process. At that point, the escape character '^' will be removed, and the property will be set as expected.

set "JAVA_OPTIONS=-Djava.protocol.handler.pkgs=pqr.net.protocol^|abc.net"