Summary

Align behavior and documentation for --compress option, its short version -c and the --compress plugin of jlink.

Problem

Current jlink documentation instructs users to choose one of the deprecated values ({0|1|2}) for -c or --compress option. Same instructions are provided for --compress plugin. The documentation should inform the users to utilize the newer compression levels of zip-{0-9}, aligned with those of jmod since JDK 21. However, if an user runs jlink with -c=1 or -c 1, the tool will fail to run. A similar error in execution occurs if someone uses the new compression levels (``) , for example running with -c=zip-1 or -c zip-1 would also result in error.

Solution

The tool has a consistent behavior for its compress option, its short version and the plugin:

• When a user provides -c {0|1|2} to jlink, the tool should process it as when receiving --compress={0|1|2}. Furthermore, as these values are now deprecated, a warning should be issued to the end user as well.
• When a user provides -c zip-{0-9} to jlink, then the tool should process it as when receiving --compress=zip-{0-9}.
• Providing a value for -c is mandatory, as is in the case of --compress.
• When no compression level is given, meaning the jlink command does not contain either -c or --compress with a value, the default level selected is zip-6.
• The --compress option description reflects above behavior and warns that previous compression levels are deprecated and will be removed in a future release.
• The --plugin option description reflects the implementation behavior and warns that previous compression levels are deprecated and will be removed in a future release.

Finally, the jlink man page documents the behavior of the compress option, its short version and the plugin.

Some implementation choices:

• While the current jlink man page states that the tool supports -c={0|1|2}, I preferred to follow the way javac supports the shortened options: if the option begins with a single dash (-), the argument should follow the option name, separated by whitespace.
• While -c 0 and --compress=0 produce the same compression level as of zip-0, I preferred not to tie the new compression level to the old value for the option. I believe that this approach would make it easier/cleaner to remove the code for the deprecated values (when their time comes).
• While -c 2 and --compress=2 produce the same compression level as of zip-6, I preferred not to tie the new compression level to the old value for the option. I believe that this approach would make it easier/cleaner to remove the code for the deprecated values (when their time comes).

Specification

The jlink tool processes -c {0|1|2} as it would do for --compress={0|1|2}; the same rationale applies when a user provides compression levels like zip-{0-9}. Any other values are interpreted as incorrect, will stop the tool from running further, and show an error as output. The behavior of jlink -c aligns with jlink --compress: if an end user provides -c or --compress without an argument, an error is thrown and shown in the output to guide improvement of the command.

The following text has been adapted to reflect the usage of zip-{0-9} values for jlink --help:

      --compress <compress>             Compress all resources in the output image:
                                        Accepted values are:
                                        zip-{0-9}, where zip-0 provides no compression,
                                        and zip-9 provides the best compression.
                                        Default is zip-6.
                                        Deprecated values to be removed in a future release:
                                        0:  No compression. Use zip-0 instead.
                                        1:  Constant String Sharing
                                        2:  ZIP. Use zip-6 instead.

Similarly, the output of jlink --list-plugins now looks as follows:

  --compress <compress>     Compression to use in compressing resources:
                            Accepted values are:
                            zip-{0-9}, where zip-0 provides no compression,
                            and zip-9 provides the best compression.
                            Default is zip-6.