Summary

Add an option to the jar tool to allow extracting the contents of the jar file to a specific directory.

Problem

The JDK ships with the jar tool which can be used to extract the contents of a jar file. In its current form, the jar tool is capable of extracting the contents only into the current working directory. External tools like unzip, tar and such allow users to optionally specify a directory to which the user can extract the archive. Enhancing the jar tool to optionally allow specifying a destination directory during extraction will make the usage of the command easier and users won't have to keep switching between directories to extract the jar to the right directory.

Solution

An optional -C option or --dir option will be allowed to be used with the -x main operation. These options will take a path on the filesystem to which the jar will be extracted. Users can either use -C or --dir option (but not both together) when specifying the destination directory.

A mailing list discussion going over the possibilities of this and other alternate option names can be found here https://mail.openjdk.java.net/pipermail/core-libs-dev/2021-February/074730.html and (continued into next month) here https://mail.openjdk.java.net/pipermail/core-libs-dev/2021-March/074850.html

Specification

Optional -C and --dir options are added to the -x main operation of the jar tool. The value for these options is expected to be a file path which is expected to be a directory to which the jar will be extracted. When neither -C nor --dir are used, the extract operation of the jar tool will continue to behave like it did before this enhancement and will extract the jar into the current working directory.

If the directory (hierarchy) passed as a value to the -C or --dir option isn't present on the filesystem, then the jar tool, during the extraction of the jar, will create those directories before extracting the jar into it.

Users are allowed to specify either absolute or relative paths as a value to these options.

These new options will be allowed to be used in the legacy compatibility mode where multiple options can be clubbed together using a single hyphen character. Specifically, a command like:

jar -xvf somejar.jar -C /tmp/foo/

will work fine and the jar will be extracted into /tmp/foo directory.

This enhancement will also introduce a new log message which prints the directory into which the jar will be extracted. This log message will only be printed when verbose option (-v) is used during the jar extraction.

It's an error to use -C or --dir more than once with the -x main operation of the jar tool. It's also an error to use both -C and --dir in the same command with the -x main operation. The tool will throw an error when it encounters such a situation.

The -P option, which was introduced in the jar tool several releases back for backward compatibility, and which preserves leading slashes and any dot-dot ".." characters in the jar entry names will not be allowed to be used with the -C or --dir option. An error will be thrown by the jar tool if -P is used together with either -C or --dir option.

Some usage examples of this new -C/--dir option follow:

jar -x -f somejar.jar -C /tmp/foo/bar/

This command extracts the somejar.jar file to the /tmp/foo/bar/ directory, creating the directory if necessary.

jar -x -f somejar.jar --dir /tmp/foo/bar/

Same as above, except uses the long form --dir option.

jar -x -f somejar.jar -C /tmp/foo/bar/ f1.txt d1/f2.txt

Assuming somejar.jar contains f1.txt (at root of the jar), d1/f2.txt and other files, then the above command extracts only f1.txt and d1/f2.txt into the /tmp/foo/bar/ directory.

jar --help has been updated to update the -C option description and introduce --dir option in the help text:

Operation modifiers valid in any mode:

  -C DIR                     Change to the specified directory and include the
                             following file. When used in extract mode, extracts
                             the jar to the specified directory
...

Operation modifiers valid only in extract mode:

  --dir                    Directory into which the jar will be extracted

man page updates for jar tool follows:

        diff --git a/src/jdk.jartool/share/man/jar.1 b/src/jdk.jartool/share/man/jar.1
index 2d983eb561e3b..865925cd07518 100644
--- a/src/jdk.jartool/share/man/jar.1
+++ b/src/jdk.jartool/share/man/jar.1
@@ -1,4 +1,4 @@
-.\" Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
+.\" Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
 .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 .\"
 .\" This code is free software; you can redistribute it and/or modify it
@@ -127,13 +127,19 @@ You can use the following options to customize the actions of any
 operation mode included in the \f[V]jar\f[R] command.
 .TP
 \f[V]-C\f[R] \f[I]DIR\f[R]
-Changes the specified directory and includes the \f[I]files\f[R]
-specified at the end of the command line.
+When used with the create operation mode, changes the specified
+directory and includes the \f[I]files\f[R] specified at the end of the
+command line.
 .RS
 .PP
 \f[V]jar\f[R] [\f[I]OPTION\f[R] ...]
 [ [\f[V]--release\f[R] \f[I]VERSION\f[R]] [\f[V]-C\f[R] \f[I]dir\f[R]]
 \f[I]files\f[R]]
+.PP
+When used with the extract operation mode, specifies the destination
+directory where the JAR file will be extracted.
+Unlike with the create operation mode, this option can be specified only
+once with the extract operation mode.
 .RE
 .TP
 \f[V]-f\f[R] \f[I]FILE\f[R] or \f[V]--file=\f[R]\f[I]FILE\f[R]
@@ -202,6 +208,10 @@ Stores without using ZIP compression.
 The timestamp in ISO-8601 extended offset date-time with optional
 time-zone format, to use for the timestamp of the entries, e.g.
 \[dq]2022-02-12T12:30:00-05:00\[dq].
+.SH OPERATION MODIFIERS VALID ONLY IN EXTRACT MODE
+.TP
+\f[V]--dir\f[R] \f[I]DIR\f[R]
+Directory into which the JAR file will be extracted.
 .SH OTHER OPTIONS
 .PP
 The following options are recognized by the \f[V]jar\f[R] command and
@@ -342,3 +352,17 @@ file that lists the files to include in the JAR file and pass it to the
 If one or more entries in the arg file cannot be found then the jar
 command fails without creating the JAR file.
 .RE
+.IP \[bu] 2
+Extract the JAR file \f[V]foo.jar\f[R] to \f[V]/tmp/bar/\f[R] directory:
+.RS 2
+.RS
+.PP
+\f[V]jar -xf foo.jar -C /tmp/bar/\f[R]
+.RE
+.PP
+Alternatively, you can also do:
+.RS
+.PP
+\f[V]jar --extract --file foo.jar --dir /tmp/bar/\f[R]
+.RE
+.RE