Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8173970: jar tool should have a way to extract to a directory #2752

Open
wants to merge 10 commits into
base: master
Choose a base branch
from

Conversation

@jaikiran
Copy link
Member

@jaikiran jaikiran commented Feb 26, 2021

Can I please get a review for this patch which proposes to implement the enhancement request noted in https://bugs.openjdk.java.net/browse/JDK-8173970?

The commit in this PR introduces the -o and --output-dir option to the jar command. The option takes a path to a destination directory as a value and extracts the contents of the jar into that directory. This is an optional option and the changes in the commit continue to maintain backward compatibility where the jar is extracted into current directory, if no -o or --output-dir option has been specified.

As far as I know, there hasn't been any discussion on what the name of this new option should be. I was initially thinking of using -d but that is currently used by the jar command for a different purpose. So I decided to use -o and --output-dir. This is of course open for change depending on any suggestions in this PR.

The commit in this PR also updates the jar.properties file which contains the English version of the jar command's --help output. However, no changes have been done to the internationalization files corresponding to this one (for example: jar_de.properties), because I don't know what process needs to be followed to have those files updated (if at all they need to be updated).

The commit also includes a jtreg testcase which verifies the usage of this new option.


Progress

  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue
  • Change must be properly reviewed

Integration blocker

 ⚠️ The change requires a CSR request to be approved.

Issue

  • JDK-8173970: jar tool should have a way to extract to a directory

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/2752/head:pull/2752
$ git checkout pull/2752

Update a local copy of the PR:
$ git checkout pull/2752
$ git pull https://git.openjdk.java.net/jdk pull/2752/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 2752

View PR using the GUI difftool:
$ git pr show -t 2752

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/2752.diff

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Feb 26, 2021

👋 Welcome back jpai! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

@openjdk openjdk bot added the rfr label Feb 26, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Feb 26, 2021

@jaikiran The following labels will be automatically applied to this pull request:

  • compiler
  • core-libs

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 26, 2021

@jonathan-gibbons
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons commented Feb 26, 2021

/csr

@openjdk openjdk bot added the csr label Feb 26, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Feb 26, 2021

@jonathan-gibbons has indicated that a compatibility and specification (CSR) request is needed for this pull request.
@jaikiran please create a CSR request and add link to it in JDK-8173970. This pull request cannot be integrated until the CSR request is approved.

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 26, 2021

Mailing list message from Lance Andersen on compiler-dev:

Hi Jaikiran,

Thank you for the proposed patch.

Assuming there is consensus to add support for this enhancement, I think we need to discuss what is the correct option.

The jar tool borrows -C from tar for creating/updating a jar and the -C option is also a valid option when extracting files from a tar file.

Perhaps keeping symmetry with tar and extend support for -C when extracting a jar file would be a better way forward. Let?s give time for additional input.

I believe this would also warrant a CSR to be created as well as updates to the jar man page.

Best
Lance

p.s. I think it would be useful in the future to start the discussion on core-libs-dev prior to creating a PR (or leave it as a draft PR) for a feature request.

On Feb 26, 2021, at 12:08 PM, Jaikiran Pai <jpai at openjdk.java.net<mailto:jpai at openjdk.java.net>> wrote:

Can I please get a review for this patch which proposes to implement the enhancement request noted in https://bugs.openjdk.java.net/browse/JDK-8173970?

The commit in this PR introduces the `-o` and `--output-dir` option to the `jar` command. The option takes a path to a destination directory as a value and extracts the contents of the jar into that directory. This is an optional option and the changes in the commit continue to maintain backward compatibility where the jar is extracted into current directory, if no `-o` or `--output-dir` option has been specified.

As far as I know, there hasn't been any discussion on what the name of this new option should be. I was initially thinking of using `-d` but that is currently used by the `jar` command for a different purpose. So I decided to use `-o` and `--output-dir`. This is of course open for change depending on any suggestions in this PR.

The commit in this PR also updates the `jar.properties` file which contains the English version of the jar command's `--help` output. However, no changes have been done to the internationalization files corresponding to this one (for example: `jar_de.properties`), because I don't know what process needs to be followed to have those files updated (if at all they need to be updated).

The commit also includes a jtreg testcase which verifies the usage of this new option.

-------------

Commit messages:
- 8173970: jar tool should have a way to extract to a directory

Changes: https://git.openjdk.java.net/jdk/pull/2752/files
Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=2752&range=00
Issue: https://bugs.openjdk.java.net/browse/JDK-8173970
Stats: 268 lines in 4 files changed: 262 ins; 0 del; 6 mod
Patch: https://git.openjdk.java.net/jdk/pull/2752.diff
Fetch: git fetch https://git.openjdk.java.net/jdk pull/2752/head:pull/2752

PR: https://git.openjdk.java.net/jdk/pull/2752

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210226/b62c547e/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: oracle_sig_logo.gif
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210226/b62c547e/oracle_sig_logo.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 27, 2021

Mailing list message from Jaikiran Pai on compiler-dev:

Hello Lance,

On 27/02/21 1:17 am, Lance Andersen wrote:

p.s. I think it would be useful in the future to start the discussion
on core-libs-dev prior to creating a PR (or leave it as a draft PR)
for a feature request.

Thank you for that input, I'll keep that in mind for any similar work in
future.

-Jaikiran

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 27, 2021

Mailing list message from Jaikiran Pai on compiler-dev:

On 27/02/21 1:17 am, Lance Andersen wrote:

I believe this would also warrant a CSR to be created as well as
updates to the jar man page.

I haven't created a CSR before, so I will need some guidance on that
part. Is it usually created after all the implementation details have
been decided upon or should it be created now?

-Jaikiran

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 27, 2021

Mailing list message from Alan Bateman on compiler-dev:

On 26/02/2021 19:47, Lance Andersen wrote:

Hi Jaikiran,

Thank you for the proposed patch.

Assuming there is consensus to add support for this enhancement, I think we need to discuss what is the correct option.

The jar tool borrows -C from tar for creating/updating a jar and the -C option is also a valid option when extracting files from a tar file.

Perhaps keeping symmetry with tar and extend support for -C when extracting a jar file would be a better way forward. Let?s give time for additional input.

I believe this would also warrant a CSR to be created as well as updates to the jar man page.

Best
Lance

p.s. I think it would be useful in the future to start the discussion on core-libs-dev prior to creating a PR (or leave it as a draft PR) for a feature request.

I created JDK-8173970 a few years ago so happy it it getting some attention.

Yes, the option name will need to be agreed. It would be useful to
enumerate the options that the other tools are using to specify the
location where to extract. If you see JBS issues mentioning tar -C not
supporting chdir when extracting then it might be Solaris tar, which
isn't the same as GNU tar which has different options. It might be
better to look at more main stream tools, like unzip although jar -d is
already taken. It would be nice if there were some consistency with
other tools in the JDK that doing extracting (The jmod and jimage
extract commands use use --dir for example).

There are other discussion points around the behavior when the target
directory exists or does not exist, to ensure there is some consistency
with main stream tools.

Yes, a CSR will be needed.

-Alan

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 27, 2021

Mailing list message from Lance Andersen on compiler-dev:

HI Jaikiran,

I am more than happy to work with you through the CSR process

Lets get the discussion going regarding possible option names on core-libs-dev and then we can move forward :-)

Have a great weekend

On Feb 26, 2021, at 9:03 PM, Jaikiran Pai <jai.forums2013 at gmail.com<mailto:jai.forums2013 at gmail.com>> wrote:

On 27/02/21 1:17 am, Lance Andersen wrote:

I believe this would also warrant a CSR to be created as well as updates to the jar man page.

I haven't created a CSR before, so I will need some guidance on that part. Is it usually created after all the implementation details have been decided upon or should it be created now?

-Jaikiran

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210227/4d92f052/attachment.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: oracle_sig_logo.gif
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210227/4d92f052/oracle_sig_logo.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 28, 2021

Mailing list message from Jaikiran Pai on compiler-dev:

Hello Alan,

On 27/02/21 2:23 pm, Alan Bateman wrote:

Yes, the option name will need to be agreed. It would be useful to
enumerate the options that the other tools are using to specify the
location where to extract. If you see JBS issues mentioning tar -C not
supporting chdir when extracting then it might be Solaris tar, which
isn't the same as GNU tar which has different options. It might be
better to look at more main stream tools, like unzip although jar -d
is already taken. It would be nice if there were some consistency with
other tools in the JDK that doing extracting (The jmod and jimage
extract commands use use --dir for example).

I had a look at both tar and unzip commands on MacOS and Linux (CentOS)
setup that I had access to.

--------------
tar on MacOS:
--------------

tar --version
bsdtar 3.3.2 - libarchive 3.3.2 zlib/1.2.11 liblzma/5.0.5 bz2lib/1.0.6

The version of this tool has:

-C directory, --cd directory, --directory directory
???????????? In c and r mode, this changes the directory before adding
the following files.
???????????? In x mode, change directories after opening the archive
but before extracting
???????????? entries from the archive.

A command like "tar -xzf foo.tar.gz -C /tmp/bar/" works fine and
extracts the foo.tar.gz from current directory to a target directory
/tmp/bar/

--------------
tar on CentOS:
--------------

tar --version
tar (GNU tar) 1.26

This version of the tool has:

Common options:
?????? -C, --directory=DIR
????????????? change to directory DIR

Although the wording isn't clear that, when used with -x, it extracts to
the directory specified in -C, it does indeed behave that way.

Specifically, a command like "tar -xzf foo.tar.gz -C /tmp/bar/" works
fine and extracts the foo.tar.gz from current directory to a target
directory /tmp/bar/

-------------------------------
unzip on both MacOS and CentOS:
-------------------------------

unzip -v
UnZip 6.00 of 20 April 2009, by Info-ZIP.? Maintained by C. Spieler.

This version of the tool has:

[-d exdir]
????????????? An optional directory to which to extract files.? By
default, all files and sub-
????????????? directories are recreated in the current directory; the
-d option allows extrac-
????????????? tion in an arbitrary directory (always assuming one has
permission to? write? to
????????????? the? directory).? This option need not appear at the end
of the command line; it
????????????? is also accepted before the zipfile specification (with?
the? normal? options),
????????????? immediately? after? the zipfile specification, or between
the file(s) and the -x
????????????? option.? The option and directory may be concatenated
without? any? white? space
????????????? between? them,? but? note? that? this may cause normal
shell behavior to be sup-
????????????? pressed.? In particular, ``-d ~'' (tilde) is expanded by
Unix C shells into? the
????????????? name of the user's home directory, but ``-d~'' is treated
as a literal subdirec-
????????????? tory ``~'' of the current directory.

unzip foo.zip -d /tmp/bar/ works fine and extracts the foo.zip from
current directory to /tmp/bar/

---------------
jimage and jmod
---------------

The jimage and jmod as you note use the --dir option for extracting to
that specified directory.

Those were the tools I looked at. I think using the -d option with -x
for the jar command is ruled out since it already is used for a
different purpose, although for a different "main" operation of the jar
command.

As for using --dir for this new feature, I don't think it alone will be
enough. Specifically, I couldn't find a "short form" option for the
--dir option in the jimage or jmod commands. For the jar extract feature
that we are discussing here, I think having a short form option (in
addition to the longer form) is necessary to have it match the usage
expectations of similar other options that the jar command exposes. So
even if we do choose --dir as the long form option, we would still need
a short form for it and since -d is already taken for something else, we
would still need to come up with a different one. The short form of this
option could be -C (see below).

I think reusing the -C option, for this new feature, perhaps is a good
thing. The -C is currently used by the update and create "main"
operation of the jar command and the man page for this option states:

-C dir
????????????? When creating (c) or updating (u) a JAR file, this option
temporarily changes
????????????? the directory while processing files specified by the
file operands. Its
????????????? operation is intended to be similar to the -C option of
the UNIX tar utility.For
????????????? example, the following command changes to the classes
directory and adds the
????????????? Bar.class file from that directory to my.jar:

????????????? jar uf my.jar -C classes Bar.class
....

Using the -C option would indeed align it with the tar command. For the
"long form" of this option, the tar command (both on MacOS and CentOS)
uses --directory. For this jar extract feature though, we could perhaps
just use --dir to have it align with the jimage and the jmod tools.

So I think the combination of -C (short form) and --dir (long form)
would perhaps be suitable for this feature.

There are other discussion points around the behavior when the target
directory exists or does not exist, to ensure there is some
consistency with main stream tools.

I'm guessing you mean the behaviour of creating a directory (or a
hierarchy of directories) if the target directory is not present? My
testing with the tar tool (both on MacOS and CentOS) shows that if the
specified target directory doesn't exist, then the extract fails. The
tar extract command doesn't create the target directory during extract.
On the other hand, the unzip tool, does create the directory if it
doesn't exist. However, interestingly, the unzip tool creates only one
level of that directory if it doesn't exist. Specifically, if you specify:

unzip foo.zip -d /tmp/blah/

and if "blah/" isn't a directory inside /tmp/ directory, then it creates
the "blah/" directory inside /tmp/ and then extracts the contents of the
zip into it.

However,

unzip foo.zip -d /tmp/blah/hello/

and if "blah/" isn't a directory inside /tmp/ directory, then this
command fails with an error and it doesn't create the hierarchy of the
target directories.

Coming to the jimage and the jmod commands, both these commands create
the entire directory hierarchy if the target directory specified during
extract, using --dir, doesn't exist. So a command like:

jimage extract --dir /tmp/blah/foo/bar/ jdkmodules

will create the blah/foo/bar/ directory hierarchy if blah doesn't exist
in /tmp/, while extracting the "jdkmodules" image.

From the user point of view, I think this behaviour of creating the
directories if the target directory doesn't exist, is probably the most
intuitive and useful and if we did decide to use this approach for this
new option for jar extract command, then it would align with what we
already do in jimage and jmod commands.

One another minor detail, while we are at this, is that, IMO we should
let the jar extract command to continue to behave the way it currently
does when it comes to overwriting existing files. If the jar being
extracted contains a file by the same name, in the target directory
(hierarchy) then it should continue to overwrite that file. In other
words, I don't think we should change the way the jar extract command
currently behaves where it overwrites existing files when extracting.

-Jaikiran

@mlbridge
Copy link

@mlbridge mlbridge bot commented Feb 28, 2021

Mailing list message from Lance Andersen on compiler-dev:

Hi Jaikiran,

Thank you for this. I went through this myself yesterday in addition to what you have below here are a few more:

7zip: -o
Info-zip: -d (MacOS version of zip)
Bandzip: -o:{dir}
jpackage: -d ?dest
jlink ?output

Thinking about this some more, I might suggest supporting

-C
?dir
?directory

Best
Lance

On Feb 27, 2021, at 11:19 PM, Jaikiran Pai <jai.forums2013 at gmail.com<mailto:jai.forums2013 at gmail.com>> wrote:

Hello Alan,

On 27/02/21 2:23 pm, Alan Bateman wrote:

Yes, the option name will need to be agreed. It would be useful to enumerate the options that the other tools are using to specify the location where to extract. If you see JBS issues mentioning tar -C not supporting chdir when extracting then it might be Solaris tar, which isn't the same as GNU tar which has different options. It might be better to look at more main stream tools, like unzip although jar -d is already taken. It would be nice if there were some consistency with other tools in the JDK that doing extracting (The jmod and jimage extract commands use use --dir for example).

I had a look at both tar and unzip commands on MacOS and Linux (CentOS) setup that I had access to.

--------------
tar on MacOS:
--------------

tar --version
bsdtar 3.3.2 - libarchive 3.3.2 zlib/1.2.11 liblzma/5.0.5 bz2lib/1.0.6

The version of this tool has:

-C directory, --cd directory, --directory directory
In c and r mode, this changes the directory before adding the following files.
In x mode, change directories after opening the archive but before extracting
entries from the archive.

A command like "tar -xzf foo.tar.gz -C /tmp/bar/" works fine and extracts the foo.tar.gz from current directory to a target directory /tmp/bar/

--------------
tar on CentOS:
--------------

tar --version
tar (GNU tar) 1.26

This version of the tool has:

Common options:
-C, --directory=DIR
change to directory DIR

Although the wording isn't clear that, when used with -x, it extracts to the directory specified in -C, it does indeed behave that way.

Specifically, a command like "tar -xzf foo.tar.gz -C /tmp/bar/" works fine and extracts the foo.tar.gz from current directory to a target directory /tmp/bar/

-------------------------------
unzip on both MacOS and CentOS:
-------------------------------

unzip -v
UnZip 6.00 of 20 April 2009, by Info-ZIP. Maintained by C. Spieler.

This version of the tool has:

[-d exdir]
An optional directory to which to extract files. By default, all files and sub-
directories are recreated in the current directory; the -d option allows extrac-
tion in an arbitrary directory (always assuming one has permission to write to
the directory). This option need not appear at the end of the command line; it
is also accepted before the zipfile specification (with the normal options),
immediately after the zipfile specification, or between the file(s) and the -x
option. The option and directory may be concatenated without any white space
between them, but note that this may cause normal shell behavior to be sup-
pressed. In particular, ``-d ~'' (tilde) is expanded by Unix C shells into the
name of the user's home directory, but ``-d~'' is treated as a literal subdirec-
tory ``~'' of the current directory.

unzip foo.zip -d /tmp/bar/ works fine and extracts the foo.zip from current directory to /tmp/bar/

---------------
jimage and jmod
---------------

The jimage and jmod as you note use the --dir option for extracting to that specified directory.

Those were the tools I looked at. I think using the -d option with -x for the jar command is ruled out since it already is used for a different purpose, although for a different "main" operation of the jar command.

As for using --dir for this new feature, I don't think it alone will be enough. Specifically, I couldn't find a "short form" option for the --dir option in the jimage or jmod commands. For the jar extract feature that we are discussing here, I think having a short form option (in addition to the longer form) is necessary to have it match the usage expectations of similar other options that the jar command exposes. So even if we do choose --dir as the long form option, we would still need a short form for it and since -d is already taken for something else, we would still need to come up with a different one. The short form of this option could be -C (see below).

I think reusing the -C option, for this new feature, perhaps is a good thing. The -C is currently used by the update and create "main" operation of the jar command and the man page for this option states:

-C dir
When creating (c) or updating (u) a JAR file, this option temporarily changes
the directory while processing files specified by the file operands. Its
operation is intended to be similar to the -C option of the UNIX tar utility.For
example, the following command changes to the classes directory and adds the
Bar.class file from that directory to my.jar:

jar uf my.jar -C classes Bar.class
....

Using the -C option would indeed align it with the tar command. For the "long form" of this option, the tar command (both on MacOS and CentOS) uses --directory. For this jar extract feature though, we could perhaps just use --dir to have it align with the jimage and the jmod tools.

So I think the combination of -C (short form) and --dir (long form) would perhaps be suitable for this feature.

There are other discussion points around the behavior when the target directory exists or does not exist, to ensure there is some consistency with main stream tools.

I'm guessing you mean the behaviour of creating a directory (or a hierarchy of directories) if the target directory is not present? My testing with the tar tool (both on MacOS and CentOS) shows that if the specified target directory doesn't exist, then the extract fails. The tar extract command doesn't create the target directory during extract. On the other hand, the unzip tool, does create the directory if it doesn't exist. However, interestingly, the unzip tool creates only one level of that directory if it doesn't exist. Specifically, if you specify:

unzip foo.zip -d /tmp/blah/

and if "blah/" isn't a directory inside /tmp/ directory, then it creates the "blah/" directory inside /tmp/ and then extracts the contents of the zip into it.

However,

unzip foo.zip -d /tmp/blah/hello/

and if "blah/" isn't a directory inside /tmp/ directory, then this command fails with an error and it doesn't create the hierarchy of the target directories.

Coming to the jimage and the jmod commands, both these commands create the entire directory hierarchy if the target directory specified during extract, using --dir, doesn't exist. So a command like:

jimage extract --dir /tmp/blah/foo/bar/ jdkmodules

will create the blah/foo/bar/ directory hierarchy if blah doesn't exist in /tmp/, while extracting the "jdkmodules" image.From the user point of view, I think this behaviour of creating the directories if the target directory doesn't exist, is probably the most intuitive and useful and if we did decide to use this approach for this new option for jar extract command, then it would align with what we already do in jimage and jmod commands.

One another minor detail, while we are at this, is that, IMO we should let the jar extract command to continue to behave the way it currently does when it comes to overwriting existing files. If the jar being extracted contains a file by the same name, in the target directory (hierarchy) then it should continue to overwrite that file. In other words, I don't think we should change the way the jar extract command currently behaves where it overwrites existing files when extracting.

-Jaikiran

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210228/e4694d74/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: oracle_sig_logo.gif
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210228/e4694d74/oracle_sig_logo-0001.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 3, 2021

Mailing list message from Jaikiran Pai on compiler-dev:

Thank you Lance. So I think there's some level of agreement on using -C
and --dir (or --directory) for the option names.

Anymore opinion on the directory creation semantics and any other
aspects to consider?

-Jaikiran

On 28/02/21 5:38 pm, Lance Andersen wrote:

Hi Jaikiran,

Thank you for this. ?I went through this myself yesterday in addition
to what you have below here are a few more:

7zip: ? ? ? -o
Info-zip: ?-d ?(MacOS version of zip)
Bandzip: -o:{dir}
jpackage: -d ?dest
jlink ?output

Thinking about this some more, I might suggest supporting

-C
?dir
?directory

Best
Lance

On Feb 27, 2021, at 11:19 PM, Jaikiran Pai <jai.forums2013 at gmail.com
<mailto:jai.forums2013 at gmail.com>> wrote:

Hello Alan,

On 27/02/21 2:23 pm, Alan Bateman wrote:

Yes, the option name will need to be agreed. It would be useful to
enumerate the options that the other tools are using to specify the
location where to extract. If you see JBS issues mentioning tar -C
not supporting chdir when extracting then it might be Solaris tar,
which isn't the same as GNU tar which has different options. It
might be better to look at more main stream tools, like unzip
although jar -d is already taken. It would be nice if there were
some consistency with other tools in the JDK that doing extracting
(The jmod and jimage extract commands use use --dir for example).

I had a look at both tar and unzip commands on MacOS and Linux
(CentOS) setup that I had access to.

--------------
tar on MacOS:
--------------

tar --version
bsdtar 3.3.2 - libarchive 3.3.2 zlib/1.2.11 liblzma/5.0.5 bz2lib/1.0.6

The version of this tool has:

-C directory, --cd directory, --directory directory
???????????? In c and r mode, this changes the directory before
adding the following files.
???????????? In x mode, change directories after opening the archive
but before extracting
???????????? entries from the archive.

A command like "tar -xzf foo.tar.gz -C /tmp/bar/" works fine and
extracts the foo.tar.gz from current directory to a target directory
/tmp/bar/

--------------
tar on CentOS:
--------------

tar --version
tar (GNU tar) 1.26

This version of the tool has:

Common options:
?????? -C, --directory=DIR
????????????? change to directory DIR

Although the wording isn't clear that, when used with -x, it extracts
to the directory specified in -C, it does indeed behave that way.

Specifically, a command like "tar -xzf foo.tar.gz -C /tmp/bar/" works
fine and extracts the foo.tar.gz from current directory to a target
directory /tmp/bar/

-------------------------------
unzip on both MacOS and CentOS:
-------------------------------

unzip -v
UnZip 6.00 of 20 April 2009, by Info-ZIP.? Maintained by C. Spieler.

This version of the tool has:

[-d exdir]
????????????? An optional directory to which to extract files.? By
default, all files and sub-
????????????? directories are recreated in the current directory; the
-d option allows extrac-
????????????? tion in an arbitrary directory (always assuming one has
permission to? write? to
????????????? the? directory).? This option need not appear at the
end of the command line; it
????????????? is also accepted before the zipfile specification
(with? the? normal? options),
????????????? immediately? after? the zipfile specification, or
between the file(s) and the -x
????????????? option.? The option and directory may be concatenated
without? any? white? space
????????????? between? them,? but? note? that? this may cause normal
shell behavior to be sup-
????????????? pressed.? In particular, ``-d ~'' (tilde) is expanded
by Unix C shells into? the
????????????? name of the user's home directory, but ``-d~'' is
treated as a literal subdirec-
????????????? tory ``~'' of the current directory.

unzip foo.zip -d /tmp/bar/ works fine and extracts the foo.zip from
current directory to /tmp/bar/

---------------
jimage and jmod
---------------

The jimage and jmod as you note use the --dir option for extracting
to that specified directory.

Those were the tools I looked at. I think using the -d option with -x
for the jar command is ruled out since it already is used for a
different purpose, although for a different "main" operation of the
jar command.

As for using --dir for this new feature, I don't think it alone will
be enough. Specifically, I couldn't find a "short form" option for
the --dir option in the jimage or jmod commands. For the jar extract
feature that we are discussing here, I think having a short form
option (in addition to the longer form) is necessary to have it match
the usage expectations of similar other options that the jar command
exposes. So even if we do choose --dir as the long form option, we
would still need a short form for it and since -d is already taken
for something else, we would still need to come up with a different
one. The short form of this option could be -C (see below).

I think reusing the -C option, for this new feature, perhaps is a
good thing. The -C is currently used by the update and create "main"
operation of the jar command and the man page for this option states:

-C dir
????????????? When creating (c) or updating (u) a JAR file, this
option temporarily changes
????????????? the directory while processing files specified by the
file operands. Its
????????????? operation is intended to be similar to the -C option of
the UNIX tar utility.For
????????????? example, the following command changes to the classes
directory and adds the
????????????? Bar.class file from that directory to my.jar:

????????????? jar uf my.jar -C classes Bar.class
....

Using the -C option would indeed align it with the tar command. For
the "long form" of this option, the tar command (both on MacOS and
CentOS) uses --directory. For this jar extract feature though, we
could perhaps just use --dir to have it align with the jimage and the
jmod tools.

So I think the combination of -C (short form) and --dir (long form)
would perhaps be suitable for this feature.

There are other discussion points around the behavior when the
target directory exists or does not exist, to ensure there is some
consistency with main stream tools.

I'm guessing you mean the behaviour of creating a directory (or a
hierarchy of directories) if the target directory is not present? My
testing with the tar tool (both on MacOS and CentOS) shows that if
the specified target directory doesn't exist, then the extract fails.
The tar extract command doesn't create the target directory during
extract. On the other hand, the unzip tool, does create the directory
if it doesn't exist. However, interestingly, the unzip tool creates
only one level of that directory if it doesn't exist. Specifically,
if you specify:

unzip foo.zip -d /tmp/blah/

and if "blah/" isn't a directory inside /tmp/ directory, then it
creates the "blah/" directory inside /tmp/ and then extracts the
contents of the zip into it.

However,

unzip foo.zip -d /tmp/blah/hello/

and if "blah/" isn't a directory inside /tmp/ directory, then this
command fails with an error and it doesn't create the hierarchy of
the target directories.

Coming to the jimage and the jmod commands, both these commands
create the entire directory hierarchy if the target directory
specified during extract, using --dir, doesn't exist. So a command like:

jimage extract --dir /tmp/blah/foo/bar/ jdkmodules

will create the blah/foo/bar/ directory hierarchy if blah doesn't
exist in /tmp/, while extracting the "jdkmodules" image.

From the user point of view, I think this behaviour of creating the
directories if the target directory doesn't exist, is probably the
most intuitive and useful and if we did decide to use this approach
for this new option for jar extract command, then it would align with
what we already do in jimage and jmod commands.

One another minor detail, while we are at this, is that, IMO we
should let the jar extract command to continue to behave the way it
currently does when it comes to overwriting existing files. If the
jar being extracted contains a file by the same name, in the target
directory (hierarchy) then it should continue to overwrite that file.
In other words, I don't think we should change the way the jar
extract command currently behaves where it overwrites existing files
when extracting.

-Jaikiran

Lance Andersen| Principal?Member of Technical Staff?| +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210303/64f0359a/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: not available
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210303/64f0359a/oracle_sig_logo-0001.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 3, 2021

Mailing list message from Lance Andersen on compiler-dev:

Hi Jaikiran,

It should not be too difficult to support the options listed below via GNUStyleOptions.

Some other things needed to be defined and agreed upon in order to move forward

* The behavior if the path does not exist
* If the option is specified more than once on the command line
* Clarify the behavior if any of the files exist in the specified target directory.

Once you have a chance to consider the above, please send your proposal back to the alias to continue the discussion

Best
Lance

On Mar 3, 2021, at 5:14 AM, Jaikiran Pai <jai.forums2013 at gmail.com<mailto:jai.forums2013 at gmail.com>> wrote:

Thank you Lance. So I think there's some level of agreement on using -C and --dir (or --directory) for the option names.

Anymore opinion on the directory creation semantics and any other aspects to consider?

-Jaikiran

On 28/02/21 5:38 pm, Lance Andersen wrote:
Hi Jaikiran,

Thank you for this. I went through this myself yesterday in addition to what you have below here are a few more:

7zip: -o
Info-zip: -d (MacOS version of zip)
Bandzip: -o:{dir}
jpackage: -d ?dest
jlink ?output

Thinking about this some more, I might suggest supporting

-C
?dir
?directory

Best
Lance

On Feb 27, 2021, at 11:19 PM, Jaikiran Pai <jai.forums2013 at gmail.com<mailto:jai.forums2013 at gmail.com>> wrote:

Hello Alan,

On 27/02/21 2:23 pm, Alan Bateman wrote:

Yes, the option name will need to be agreed. It would be useful to enumerate the options that the other tools are using to specify the location where to extract. If you see JBS issues mentioning tar -C not supporting chdir when extracting then it might be Solaris tar, which isn't the same as GNU tar which has different options. It might be better to look at more main stream tools, like unzip although jar -d is already taken. It would be nice if there were some consistency with other tools in the JDK that doing extracting (The jmod and jimage extract commands use use --dir for example).

I had a look at both tar and unzip commands on MacOS and Linux (CentOS) setup that I had access to.

--------------
tar on MacOS:
--------------

tar --version
bsdtar 3.3.2 - libarchive 3.3.2 zlib/1.2.11 liblzma/5.0.5 bz2lib/1.0.6

The version of this tool has:

-C directory, --cd directory, --directory directory
In c and r mode, this changes the directory before adding the following files.
In x mode, change directories after opening the archive but before extracting
entries from the archive.

A command like "tar -xzf foo.tar.gz -C /tmp/bar/" works fine and extracts the foo.tar.gz from current directory to a target directory /tmp/bar/

--------------
tar on CentOS:
--------------

tar --version
tar (GNU tar) 1.26

This version of the tool has:

Common options:
-C, --directory=DIR
change to directory DIR

Although the wording isn't clear that, when used with -x, it extracts to the directory specified in -C, it does indeed behave that way.

Specifically, a command like "tar -xzf foo.tar.gz -C /tmp/bar/" works fine and extracts the foo.tar.gz from current directory to a target directory /tmp/bar/

-------------------------------
unzip on both MacOS and CentOS:
-------------------------------

unzip -v
UnZip 6.00 of 20 April 2009, by Info-ZIP. Maintained by C. Spieler.

This version of the tool has:

[-d exdir]
An optional directory to which to extract files. By default, all files and sub-
directories are recreated in the current directory; the -d option allows extrac-
tion in an arbitrary directory (always assuming one has permission to write to
the directory). This option need not appear at the end of the command line; it
is also accepted before the zipfile specification (with the normal options),
immediately after the zipfile specification, or between the file(s) and the -x
option. The option and directory may be concatenated without any white space
between them, but note that this may cause normal shell behavior to be sup-
pressed. In particular, ``-d ~'' (tilde) is expanded by Unix C shells into the
name of the user's home directory, but ``-d~'' is treated as a literal subdirec-
tory ``~'' of the current directory.

unzip foo.zip -d /tmp/bar/ works fine and extracts the foo.zip from current directory to /tmp/bar/

---------------
jimage and jmod
---------------

The jimage and jmod as you note use the --dir option for extracting to that specified directory.

Those were the tools I looked at. I think using the -d option with -x for the jar command is ruled out since it already is used for a different purpose, although for a different "main" operation of the jar command.

As for using --dir for this new feature, I don't think it alone will be enough. Specifically, I couldn't find a "short form" option for the --dir option in the jimage or jmod commands. For the jar extract feature that we are discussing here, I think having a short form option (in addition to the longer form) is necessary to have it match the usage expectations of similar other options that the jar command exposes. So even if we do choose --dir as the long form option, we would still need a short form for it and since -d is already taken for something else, we would still need to come up with a different one. The short form of this option could be -C (see below).

I think reusing the -C option, for this new feature, perhaps is a good thing. The -C is currently used by the update and create "main" operation of the jar command and the man page for this option states:

-C dir
When creating (c) or updating (u) a JAR file, this option temporarily changes
the directory while processing files specified by the file operands. Its
operation is intended to be similar to the -C option of the UNIX tar utility.For
example, the following command changes to the classes directory and adds the
Bar.class file from that directory to my.jar:

jar uf my.jar -C classes Bar.class
....

Using the -C option would indeed align it with the tar command. For the "long form" of this option, the tar command (both on MacOS and CentOS) uses --directory. For this jar extract feature though, we could perhaps just use --dir to have it align with the jimage and the jmod tools.

So I think the combination of -C (short form) and --dir (long form) would perhaps be suitable for this feature.

There are other discussion points around the behavior when the target directory exists or does not exist, to ensure there is some consistency with main stream tools.

I'm guessing you mean the behaviour of creating a directory (or a hierarchy of directories) if the target directory is not present? My testing with the tar tool (both on MacOS and CentOS) shows that if the specified target directory doesn't exist, then the extract fails. The tar extract command doesn't create the target directory during extract. On the other hand, the unzip tool, does create the directory if it doesn't exist. However, interestingly, the unzip tool creates only one level of that directory if it doesn't exist. Specifically, if you specify:

unzip foo.zip -d /tmp/blah/

and if "blah/" isn't a directory inside /tmp/ directory, then it creates the "blah/" directory inside /tmp/ and then extracts the contents of the zip into it.

However,

unzip foo.zip -d /tmp/blah/hello/

and if "blah/" isn't a directory inside /tmp/ directory, then this command fails with an error and it doesn't create the hierarchy of the target directories.

Coming to the jimage and the jmod commands, both these commands create the entire directory hierarchy if the target directory specified during extract, using --dir, doesn't exist. So a command like:

jimage extract --dir /tmp/blah/foo/bar/ jdkmodules

will create the blah/foo/bar/ directory hierarchy if blah doesn't exist in /tmp/, while extracting the "jdkmodules" image.From the user point of view, I think this behaviour of creating the directories if the target directory doesn't exist, is probably the most intuitive and useful and if we did decide to use this approach for this new option for jar extract command, then it would align with what we already do in jimage and jmod commands.

One another minor detail, while we are at this, is that, IMO we should let the jar extract command to continue to behave the way it currently does when it comes to overwriting existing files. If the jar being extracted contains a file by the same name, in the target directory (hierarchy) then it should continue to overwrite that file. In other words, I don't think we should change the way the jar extract command currently behaves where it overwrites existing files when extracting.

-Jaikiran

<oracle_sig_logo.gif>

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210303/ee33848d/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: oracle_sig_logo.gif
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210303/ee33848d/oracle_sig_logo-0001.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 4, 2021

Mailing list message from Jaikiran Pai on compiler-dev:

Hello Lance,

On 03/03/21 9:14 pm, Lance Andersen wrote:

Some other things needed to be defined and agreed upon in order to
move forward

* The behavior if the path does not exist
* If the option is specified more than once on the command line
* Clarify the behavior if any of the files exist in the specified
target directory.

One of my previous reply included the details of how I think it should
behave for 2 of the above cases. I'll paste that here again for easier
visibility. As for how it should behave if the option is specified more
than once, I'll spend some time today to see how the jar tool currently
behaves for some of the other options in this aspect and send back my
response. Thank you for your help so far. Pasting below my proposal from
a previous reply for the other 2 cases:

There are other discussion points around the behavior when the target
directory exists or does not exist, to ensure there is some
consistency with main stream tools.

I'm guessing you mean the behaviour of creating a directory (or a
hierarchy of directories) if the target directory is not present? My
testing with the tar tool (both on MacOS and CentOS) shows that if the
specified target directory doesn't exist, then the extract fails. The
tar extract command doesn't create the target directory during extract.
On the other hand, the unzip tool, does create the directory if it
doesn't exist. However, interestingly, the unzip tool creates only one
level of that directory if it doesn't exist. Specifically, if you specify:

unzip foo.zip -d /tmp/blah/

and if "blah/" isn't a directory inside /tmp/ directory, then it creates
the "blah/" directory inside /tmp/ and then extracts the contents of the
zip into it.

However,

unzip foo.zip -d /tmp/blah/hello/

and if "blah/" isn't a directory inside /tmp/ directory, then this
command fails with an error and it doesn't create the hierarchy of the
target directories.

Coming to the jimage and the jmod commands, both these commands create
the entire directory hierarchy if the target directory specified during
extract, using --dir, doesn't exist. So a command like:

jimage extract --dir /tmp/blah/foo/bar/ jdkmodules

will create the blah/foo/bar/ directory hierarchy if blah doesn't exist
in /tmp/, while extracting the "jdkmodules" image.

From the user point of view, I think this behaviour of creating the
directories if the target directory doesn't exist, is probably the most
intuitive and useful and if we did decide to use this approach for this
new option for jar extract command, then it would align with what we
already do in jimage and jmod commands.

One another minor detail, while we are at this, is that, IMO we should
let the jar extract command to continue to behave the way it currently
does when it comes to overwriting existing files. If the jar being
extracted contains a file by the same name, in the target directory
(hierarchy) then it should continue to overwrite that file. In other
words, I don't think we should change the way the jar extract command
currently behaves where it overwrites existing files when extracting.

-Jaikiran

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210304/dedf34b2/attachment.htm>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 4, 2021

Mailing list message from Lance Andersen on compiler-dev:

Hi JaikiranFrom https://docs.oracle.com/en/java/javase/15/docs/specs/man/jar.html

The jar man page includes the following :
The syntax for the jar command resembles the syntax for the tar command.

Because of the above, I feel that we should support:

???
-C
?dir
?directory
????

The addition of ?-dir? adds support for an option used by some of the other java command line tools.

I would suggest for the next step is flush/write out your proposed syntax as it would be included in an updated version of the jar man page.

Given the other java command line tools create the directory if it does not exist, I think that is reasonable to propose that.

Your change should not modify the longstanding overwrite behavior of jar.

Another thing to think about is whether there should be any additional output when the -v option is specified

In summary, I think you are moving in the right direction. The next step is to make a pass at creating the man page updates so that we can reach consensus on the syntax and behavior.

Thank you again for your efforts on this

Best
Lance

On Mar 3, 2021, at 9:40 PM, Jaikiran Pai <jai.forums2013 at gmail.com<mailto:jai.forums2013 at gmail.com>> wrote:

Hello Lance,

On 03/03/21 9:14 pm, Lance Andersen wrote:

Some other things needed to be defined and agreed upon in order to move forward

* The behavior if the path does not exist
* If the option is specified more than once on the command line
* Clarify the behavior if any of the files exist in the specified target directory.

One of my previous reply included the details of how I think it should behave for 2 of the above cases. I'll paste that here again for easier visibility. As for how it should behave if the option is specified more than once, I'll spend some time today to see how the jar tool currently behaves for some of the other options in this aspect and send back my response. Thank you for your help so far. Pasting below my proposal from a previous reply for the other 2 cases:

There are other discussion points around the behavior when the target directory exists or does not exist, to ensure there is some consistency with main stream tools.

I'm guessing you mean the behaviour of creating a directory (or a hierarchy of directories) if the target directory is not present? My testing with the tar tool (both on MacOS and CentOS) shows that if the specified target directory doesn't exist, then the extract fails. The tar extract command doesn't create the target directory during extract. On the other hand, the unzip tool, does create the directory if it doesn't exist. However, interestingly, the unzip tool creates only one level of that directory if it doesn't exist. Specifically, if you specify:

unzip foo.zip -d /tmp/blah/

and if "blah/" isn't a directory inside /tmp/ directory, then it creates the "blah/" directory inside /tmp/ and then extracts the contents of the zip into it.

However,

unzip foo.zip -d /tmp/blah/hello/

and if "blah/" isn't a directory inside /tmp/ directory, then this command fails with an error and it doesn't create the hierarchy of the target directories.

Coming to the jimage and the jmod commands, both these commands create the entire directory hierarchy if the target directory specified during extract, using --dir, doesn't exist. So a command like:

jimage extract --dir /tmp/blah/foo/bar/ jdkmodules

will create the blah/foo/bar/ directory hierarchy if blah doesn't exist in /tmp/, while extracting the "jdkmodules" image.From the user point of view, I think this behaviour of creating the directories if the target directory doesn't exist, is probably the most intuitive and useful and if we did decide to use this approach for this new option for jar extract command, then it would align with what we already do in jimage and jmod commands.

One another minor detail, while we are at this, is that, IMO we should let the jar extract command to continue to behave the way it currently does when it comes to overwriting existing files. If the jar being extracted contains a file by the same name, in the target directory (hierarchy) then it should continue to overwrite that file. In other words, I don't think we should change the way the jar extract command currently behaves where it overwrites existing files when extracting.

-Jaikiran

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210304/13818262/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: oracle_sig_logo.gif
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210304/13818262/oracle_sig_logo-0001.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 11, 2021

Mailing list message from Alan Bateman on core-libs-dev:

On 04/03/2021 12:01, Lance Andersen wrote:

Hi Jaikiran

From https://docs.oracle.com/en/java/javase/15/docs/specs/man/jar.html
<https://docs.oracle.com/en/java/javase/15/docs/specs/man/jar.html>

The jar man page includes the following :
?The syntax for the |jar|?command resembles the syntax for the
|tar|?command.

Because of the above, I feel that we should support:

???
-C
?dir
?directory
????

The addition of ?-dir? adds support for an option used by some of the
other java command line tools.

Is --directory needed with this proposal?

I agree with the suggest to create the directory so that it's consistent
with other tools.

-Alan.

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 11, 2021

Mailing list message from Lance Andersen on core-libs-dev:

On Mar 11, 2021, at 9:29 AM, Alan Bateman <alan.bateman at oracle.com<mailto:alan.bateman at oracle.com>> wrote:

On 04/03/2021 12:01, Lance Andersen wrote:
Hi JaikiranFrom https://docs.oracle.com/en/java/javase/15/docs/specs/man/jar.html

The jar man page includes the following :
The syntax for the jar command resembles the syntax for the tar command.

Because of the above, I feel that we should support:

???
-C
?dir
?directory
????

The addition of ?-dir? adds support for an option used by some of the other java command line tools.

Is --directory needed with this proposal?

I agree with the suggest to create the directory so that it's consistent with other tools.

The only reason I included it is for completeness with tar which the jar options were originally derived from.

Could go either way though

Best
Lance

-Alan.

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 12, 2021

Mailing list message from Alan Bateman on core-libs-dev:

On 11/03/2021 15:25, Lance Andersen wrote:

The only reason I included it is for completeness with tar which the
jar options were originally derived from.

I think it would be surprising to have two GNU-style long options so I
think we should pick one.? "--dir" seems okay to me and is consistent
with the other the other JDK tools that extract to a directory (although
those tools might not be well known). If you prefer "--directory" then I
think we'll should add it to the other tools and hide "--dir" from the
usage output.

-Alan

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 12, 2021

Mailing list message from Lance Andersen on core-libs-dev:

On Mar 12, 2021, at 6:32 AM, Alan Bateman <alan.bateman at oracle.com<mailto:alan.bateman at oracle.com>> wrote:

On 11/03/2021 15:25, Lance Andersen wrote:

The only reason I included it is for completeness with tar which the jar options were originally derived from.

I think it would be surprising to have two GNU-style long options so I think we should pick one. "--dir" seems okay to me and is consistent with the other the other JDK tools that extract to a directory (although those tools might not be well known). If you prefer "--directory" then I think we'll should add it to the other tools and hide "--dir" from the usage output.

I don?t have a strong preference but lean slightly towards ?-directory? as it is more descriptive, similar to the other GNU-style commands jar currently supports . Tar supports ??cd?, ??directory? in addition to ?-C? which is why I suggested supporting both GNU-style long options.

Perhaps jpackage should also support ?dir/directory in addition to ??dest' if we are looking at consistency between java tools.

I do agree that it would be nice to be consistent across the java tools for options so if we go the ?-directory?, we should follow your suggestion and make it the primary and remove ??dir? from the usage output.

-Alan

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 14, 2021

Mailing list message from Alan Bateman on core-libs-dev:

On 12/03/2021 12:18, Lance Andersen wrote:

:

I don?t have a strong preference but lean slightly towards
?-directory? as it is more descriptive, similar to the other GNU-style
commands jar currently supports . ?Tar supports ??cd?, ??directory? in
addition to ?-C? which is why I suggested supporting ?both GNU-style
long options.

Perhaps jpackage should also support ?dir/directory in addition to
??dest' if we are looking at consistency between java tools.

I do agree that it would be nice to be consistent across the java
tools for options so if we go the ?-directory?, we should follow your
suggestion and make it the primary and remove ??dir? from the usage
output.

My comment on consistency was limited to the long option to specify the
directory when extracting, didn't mean to suggest doing anything with
the other tools that specify an output/destination directory. In any
case, I think we have enough to make progress on this issue now.

-Alan

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 15, 2021

Mailing list message from Jaikiran Pai on core-libs-dev:

On 14/03/21 6:21 pm, Alan Bateman wrote:

On 12/03/2021 12:18, Lance Andersen wrote:

:

I don?t have a strong preference but lean slightly towards
?-directory? as it is more descriptive, similar to the other
GNU-style commands jar currently supports . ?Tar supports ??cd?,
??directory? in addition to ?-C? which is why I suggested supporting
?both GNU-style long options.

Perhaps jpackage should also support ?dir/directory in addition to
??dest' if we are looking at consistency between java tools.

I do agree that it would be nice to be consistent across the java
tools for options so if we go the ?-directory?, we should follow your
suggestion and make it the primary and remove ??dir? from the usage
output.
My comment on consistency was limited to the long option to specify
the directory when extracting, didn't mean to suggest doing anything
with the other tools that specify an output/destination directory. In
any case, I think we have enough to make progress on this issue now.

I'll sending the man page content that I have been working on, shortly
and will then go ahead with changing the PR to incorporate some of the
feedback received in this discussion.

-Jaikiran

@jaikiran jaikiran force-pushed the jaikiran:8173970 branch from 3a8e329 to a995424 Mar 24, 2021
@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 24, 2021

Mailing list message from Jaikiran Pai on core-libs-dev:

Based on the inputs so far, I've updated the PR to include the provided
feedback. Since the PR code review hadn't yet started, I decided to do a
force push to the PR so that we can start it afresh.

Command option:

In this current discussion, we seem to have an agreement for using -C
and --dir as the short and long options for this feature. The
implementation in this PR now uses these options. There was also a
suggestion to additionally allow --directory as an option too. I haven't
added that yet, since I wasn't sure if we really want that. It was
suggested that if we do use --directory, we should "hide" --dir. If we
do need the --directory option, I can add that in, in subsequent updates
to this PR.

Directories creation:

There was an agreement in our discussion that if the destination
directory hierarchy isn't present, then we should create that whole
hierarchy and extract the jar into it. The implementation in this PR
matches this decision.

Verbose logging:

During the discussion, there was a question whether this feature should
introduce any new verbose logs during extraction. IMO, it's a good idea
to log the target directory to which the jar is being extracted. So, in
the implementation, I have introduced a new (resource bundle backed)
verbose log message which prints the absolute path to which the jar will
be extracted. Do note that this verbose log message will be printed even
if you don't explicitly specify any target directory. i.e. even when the
default current directory is used, this verbose log message will be
printed if the "-v" option is used.

Repeatability of the newly introduce options:

Unlike in the other main operations of the jar command, the -C option
that we use during the extract main operation, IMO, shouldn't be allowed
to be used more than once. More specifically the destination directory
to which the jar needs to be extracted must only be specified once,
irrespective of whether it's through the use of -C or --dir. The code in
the PR, explicitly throws an error when such repeatition is encountered.

An alternate approach would have been to allow the -C and/or --dir
option to be repeated, but use the last specified value of these
options. However, I decided not to pursue that approach, to keep it
simple as well as to avoid any confusion on the command usage.

Overwriting of contents in existing target directory:

No specific change has been done when it comes to dealing with the
extraction logic itself. Specifically, when the explicitly specified or
the default current directory already has directories/files that belong
to the jar being extracted, those files/dirs will continue to be
overwritten.

Compatibility mode:

The code in this PR also supports the compatibility mode for this
option. Specifically, a command like:

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

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

Message/error internationalization:

I have only updated the jar.properties for the English version of the
new output and error messages. I don't know what the process is for
adding this to other languages, if at all that needs to be done in this PR.

jar --help output:

Currently the jar --help output only talks about creation and updation
of the jar. There's no mention of using the tool for extracting the jar
content:

"jar creates an archive for classes and resources, and can manipulate or
restore individual classes or resources from an archive."

It does mention "manipulate" but doesn't specifically say extraction.
The examples in the help command output don't have any examples for
extraction. Should we add an example for extracting the jar file, in
this help output?

Testing:

A new jtreg test has been introduced which tests various aspects of this
feature. It runs most of those tests against both absolute and relative
paths.

A couple of tests in the new introduced test case, check for the
output/error messages. The jar tool uses resource bundles to print out
these messages. I need input on whether I should enforce a specific
locale to run these tests so that I can compare the error/output
messages for expected strings? See testExtractFailWithMultipleDir() or
testHelpOutput() for what I mean.

Man page:

This one I need input on. I have tried to see how these man pages are
generated and from what I can understand it looks like these man pages
are autogenerated during the build process using pandoc. Is that right?
The hints that I see in the Docs.gmk seems to suggest that there are
some markdown source files from which these man pages get generated.
However, I can't seem to locate any such markdown files for this or
other tools, from which the man pages get generated. Any help on how I
should go about editing/updating the man page for the jar tool?

Example usage:

Here are some example usages:

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

This command extracts the somejar.jar file to the /tmp/foo/bar/
directory, creating it 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), "d1/f2.txt" and other
files, then the above command extracts only "f1.txt" and "d1/f2.txt"
into the /tmp/foo/bar/ directory.

-Jaikiran

On 14/03/21 6:21 pm, Alan Bateman wrote:

On 12/03/2021 12:18, Lance Andersen wrote:

:

I don?t have a strong preference but lean slightly towards
?-directory? as it is more descriptive, similar to the other
GNU-style commands jar currently supports . ?Tar supports ??cd?,
??directory? in addition to ?-C? which is why I suggested supporting
?both GNU-style long options.

Perhaps jpackage should also support ?dir/directory in addition to
??dest' if we are looking at consistency between java tools.

I do agree that it would be nice to be consistent across the java
tools for options so if we go the ?-directory?, we should follow your
suggestion and make it the primary and remove ??dir? from the usage
output.
My comment on consistency was limited to the long option to specify
the directory when extracting, didn't mean to suggest doing anything
with the other tools that specify an output/destination directory. In
any case, I think we have enough to make progress on this issue now.

-Alan

@AlanBateman
Copy link
Contributor

@AlanBateman AlanBateman commented Mar 27, 2021

I think the summary is that we've converged on -C/--dir. We might have to tweak the usage message for -C so that it starts with the existing "Change to the specified directory ..." rather than changing it to start with the extract case.
Are you, or Lance, going to create the CSR for this?

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 27, 2021

Mailing list message from Lance Andersen on compiler-dev:

On Mar 27, 2021, at 12:05 PM, Alan Bateman <alanb at openjdk.java.net<mailto:alanb at openjdk.java.net>> wrote:

On Fri, 26 Feb 2021 17:03:11 GMT, Jaikiran Pai <jpai at openjdk.org<mailto:jpai at openjdk.org>> wrote:

Can I please get a review for this patch which proposes to implement the enhancement request noted in https://bugs.openjdk.java.net/browse/JDK-8173970?

The commit in this PR introduces the `-o` and `--output-dir` option to the `jar` command. The option takes a path to a destination directory as a value and extracts the contents of the jar into that directory. This is an optional option and the changes in the commit continue to maintain backward compatibility where the jar is extracted into current directory, if no `-o` or `--output-dir` option has been specified.

As far as I know, there hasn't been any discussion on what the name of this new option should be. I was initially thinking of using `-d` but that is currently used by the `jar` command for a different purpose. So I decided to use `-o` and `--output-dir`. This is of course open for change depending on any suggestions in this PR.

The commit in this PR also updates the `jar.properties` file which contains the English version of the jar command's `--help` output. However, no changes have been done to the internationalization files corresponding to this one (for example: `jar_de.properties`), because I don't know what process needs to be followed to have those files updated (if at all they need to be updated).

The commit also includes a jtreg testcase which verifies the usage of this new option.

I think the summary is that we've converged on -C/--dir. We might have to tweak the usage message for -C so that it starts with the existing "Change to the specified directory ..." rather than changing it to start with the extract case.
Are you, or Lance, going to create the CSR for this?

I have not had a chance to go through the latest update from Jaikiran or his revised PR yet.

Yes, once we flush everything out, I will work with Jaikiran on the CSR and determine which of us will create the CSR. On the todo list for next week.

Best
Lance

-------------

PR: https://git.openjdk.java.net/jdk/pull/2752

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210327/8f3af85f/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: oracle_sig_logo.gif
Type: image/gif
Size: 658 bytes
Desc: oracle_sig_logo.gif
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20210327/8f3af85f/oracle_sig_logo-0001.gif>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 28, 2021

Mailing list message from Jaikiran Pai on core-libs-dev:

Lance ran some tests against the proposed patch and that has exposed an
area which we haven't yet taken into account for this feature.

The jar tool has a (hidden) option "-P" which can be used with the "c"
(create), "u" (update) and "x" (extract) main operations. When this -P
option is used, the jar tool will preserve/won't strip leading slash and
".." component from file name. So imagine a jar created with the -P
option as follows:

jar -cfP foo.jar /tmp/blah.txt

This will add /tmp/blah.txt with the the leading / preserved, so the
contents of the jar will be:

jar -tf foo.jar
META-INF/
META-INF/MANIFEST.MF
/tmp/blah.txt

Consider being in /home/me/ directory and running the jar -xfP command
against this jar. When you do that, the /tmp/blah.txt will get extracted
to the /tmp/blah.txt absolute path and the META-INF and the other
entries get extracted inside the /home/me/ directory. This is how the
jar tool currently behaves when the leading slashes (and ..) are
involved with the -P option.

Now coming to this new feature we are talking about, IMO, we cannot
break this existing behaviour. So when the user continues to use:

jar -xfP foo.jar

without any explicit -C or --dir option, then IMO, the extract should
continue to work just like it does now and continue to extract the
/tmp/blah.txt to that absolute location. Now when the user explicitly
specifies the new -C or --dir option with the -P option for extract,
something like:

jar -xfP foo.jar -C /tmp/hello/

I think we should continue to extract the /tmp/blah.txt to that absolute
location instead of making it relative to the /tmp/hello/ directory.
Given that -P is a hidden option, I am not sure if this should be
documented in some manner (other than maybe code comments), but I wanted
to bring this up so that we can come to a decision and have the proposed
implementation work in that manner.

-Jaikiran

On 24/03/21 4:10 pm, Jaikiran Pai wrote:

Based on the inputs so far, I've updated the PR to include the
provided feedback. Since the PR code review hadn't yet started, I
decided to do a force push to the PR so that we can start it afresh.

Command option:

In this current discussion, we seem to have an agreement for using -C
and --dir as the short and long options for this feature. The
implementation in this PR now uses these options. There was also a
suggestion to additionally allow --directory as an option too. I
haven't added that yet, since I wasn't sure if we really want that. It
was suggested that if we do use --directory, we should "hide" --dir.
If we do need the --directory option, I can add that in, in subsequent
updates to this PR.

Directories creation:

There was an agreement in our discussion that if the destination
directory hierarchy isn't present, then we should create that whole
hierarchy and extract the jar into it. The implementation in this PR
matches this decision.

Verbose logging:

During the discussion, there was a question whether this feature
should introduce any new verbose logs during extraction. IMO, it's a
good idea to log the target directory to which the jar is being
extracted. So, in the implementation, I have introduced a new
(resource bundle backed) verbose log message which prints the absolute
path to which the jar will be extracted. Do note that this verbose log
message will be printed even if you don't explicitly specify any
target directory. i.e. even when the default current directory is
used, this verbose log message will be printed if the "-v" option is
used.

Repeatability of the newly introduce options:

Unlike in the other main operations of the jar command, the -C option
that we use during the extract main operation, IMO, shouldn't be
allowed to be used more than once. More specifically the destination
directory to which the jar needs to be extracted must only be
specified once, irrespective of whether it's through the use of -C or
--dir. The code in the PR, explicitly throws an error when such
repeatition is encountered.

An alternate approach would have been to allow the -C and/or --dir
option to be repeated, but use the last specified value of these
options. However, I decided not to pursue that approach, to keep it
simple as well as to avoid any confusion on the command usage.

Overwriting of contents in existing target directory:

No specific change has been done when it comes to dealing with the
extraction logic itself. Specifically, when the explicitly specified
or the default current directory already has directories/files that
belong to the jar being extracted, those files/dirs will continue to
be overwritten.

Compatibility mode:

The code in this PR also supports the compatibility mode for this
option. Specifically, a command like:

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

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

Message/error internationalization:

I have only updated the jar.properties for the English version of the
new output and error messages. I don't know what the process is for
adding this to other languages, if at all that needs to be done in
this PR.

jar --help output:

Currently the jar --help output only talks about creation and updation
of the jar. There's no mention of using the tool for extracting the
jar content:

"jar creates an archive for classes and resources, and can manipulate or
restore individual classes or resources from an archive."

It does mention "manipulate" but doesn't specifically say extraction.
The examples in the help command output don't have any examples for
extraction. Should we add an example for extracting the jar file, in
this help output?

Testing:

A new jtreg test has been introduced which tests various aspects of
this feature. It runs most of those tests against both absolute and
relative paths.

A couple of tests in the new introduced test case, check for the
output/error messages. The jar tool uses resource bundles to print out
these messages. I need input on whether I should enforce a specific
locale to run these tests so that I can compare the error/output
messages for expected strings? See testExtractFailWithMultipleDir() or
testHelpOutput() for what I mean.

Man page:

This one I need input on. I have tried to see how these man pages are
generated and from what I can understand it looks like these man pages
are autogenerated during the build process using pandoc. Is that
right? The hints that I see in the Docs.gmk seems to suggest that
there are some markdown source files from which these man pages get
generated. However, I can't seem to locate any such markdown files for
this or other tools, from which the man pages get generated. Any help
on how I should go about editing/updating the man page for the jar tool?

Example usage:

Here are some example usages:

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

This command extracts the somejar.jar file to the /tmp/foo/bar/
directory, creating it 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), "d1/f2.txt" and
other files, then the above command extracts only "f1.txt" and
"d1/f2.txt" into the /tmp/foo/bar/ directory.

-Jaikiran

On 14/03/21 6:21 pm, Alan Bateman wrote:

On 12/03/2021 12:18, Lance Andersen wrote:

:

I don?t have a strong preference but lean slightly towards
?-directory? as it is more descriptive, similar to the other
GNU-style commands jar currently supports . ?Tar supports ??cd?,
??directory? in addition to ?-C? which is why I suggested supporting
?both GNU-style long options.

Perhaps jpackage should also support ?dir/directory in addition to
??dest' if we are looking at consistency between java tools.

I do agree that it would be nice to be consistent across the java
tools for options so if we go the ?-directory?, we should follow
your suggestion and make it the primary and remove ??dir? from the
usage output.
My comment on consistency was limited to the long option to specify
the directory when extracting, didn't mean to suggest doing anything
with the other tools that specify an output/destination directory. In
any case, I think we have enough to make progress on this issue now.

-Alan

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 28, 2021

Mailing list message from Lance Andersen on core-libs-dev:

On Mar 28, 2021, at 9:24 AM, Jaikiran Pai <jai.forums2013 at gmail.com<mailto:jai.forums2013 at gmail.com>> wrote:

Lance ran some tests against the proposed patch and that has exposed an area which we haven't yet taken into account for this feature.

The jar tool has a (hidden) option "-P" which can be used with the "c" (create), "u" (update) and "x" (extract) main operations. When this -P option is used, the jar tool will preserve/won't strip leading slash and ".." component from file name. So imagine a jar created with the -P option as follows:

jar -cfP foo.jar /tmp/blah.txt

This will add /tmp/blah.txt with the the leading / preserved, so the contents of the jar will be:

jar -tf foo.jar
META-INF/
META-INF/MANIFEST.MF
/tmp/blah.txt

Consider being in /home/me/ directory and running the jar -xfP command against this jar. When you do that, the /tmp/blah.txt will get extracted to the /tmp/blah.txt absolute path and the META-INF and the other entries get extracted inside the /home/me/ directory. This is how the jar tool currently behaves when the leading slashes (and ..) are involved with the -P option.

Now coming to this new feature we are talking about, IMO, we cannot break this existing behaviour. So when the user continues to use:

jar -xfP foo.jar

without any explicit -C or --dir option, then IMO, the extract should continue to work just like it does now and continue to extract the /tmp/blah.txt to that absolute location.

Agree

Now when the user explicitly specifies the new -C or --dir option with the -P option for extract, something like:

jar -xfP foo.jar -C /tmp/hello/

Given the support of -C/-dir is new and -P is there for backwards compatibility then I see the choices are:

* Issue an error when -P and -C/-dir are specified together with -x
* Silently ignore the -P option
* Ignore -C/-dir and the behavior is if -xfP was specified.

I am leaning towards an error given this is a new feature when -P and -C/-dir are specified with -x

Best
Lance

I think we should continue to extract the /tmp/blah.txt to that absolute location instead of making it relative to the /tmp/hello/ directory. Given that -P is a hidden option, I am not sure if this should be documented in some manner (other than maybe code comments), but I wanted to bring this up so that we can come to a decision and have the proposed implementation work in that manner.

-Jaikiran

On 24/03/21 4:10 pm, Jaikiran Pai wrote:
Based on the inputs so far, I've updated the PR to include the provided feedback. Since the PR code review hadn't yet started, I decided to do a force push to the PR so that we can start it afresh.

Command option:

In this current discussion, we seem to have an agreement for using -C and --dir as the short and long options for this feature. The implementation in this PR now uses these options. There was also a suggestion to additionally allow --directory as an option too. I haven't added that yet, since I wasn't sure if we really want that. It was suggested that if we do use --directory, we should "hide" --dir. If we do need the --directory option, I can add that in, in subsequent updates to this PR.

Directories creation:

There was an agreement in our discussion that if the destination directory hierarchy isn't present, then we should create that whole hierarchy and extract the jar into it. The implementation in this PR matches this decision.

Verbose logging:

During the discussion, there was a question whether this feature should introduce any new verbose logs during extraction. IMO, it's a good idea to log the target directory to which the jar is being extracted. So, in the implementation, I have introduced a new (resource bundle backed) verbose log message which prints the absolute path to which the jar will be extracted. Do note that this verbose log message will be printed even if you don't explicitly specify any target directory. i.e. even when the default current directory is used, this verbose log message will be printed if the "-v" option is used.

Repeatability of the newly introduce options:

Unlike in the other main operations of the jar command, the -C option that we use during the extract main operation, IMO, shouldn't be allowed to be used more than once. More specifically the destination directory to which the jar needs to be extracted must only be specified once, irrespective of whether it's through the use of -C or --dir. The code in the PR, explicitly throws an error when such repeatition is encountered.

An alternate approach would have been to allow the -C and/or --dir option to be repeated, but use the last specified value of these options. However, I decided not to pursue that approach, to keep it simple as well as to avoid any confusion on the command usage.

Overwriting of contents in existing target directory:

No specific change has been done when it comes to dealing with the extraction logic itself. Specifically, when the explicitly specified or the default current directory already has directories/files that belong to the jar being extracted, those files/dirs will continue to be overwritten.

Compatibility mode:

The code in this PR also supports the compatibility mode for this option. Specifically, a command like:

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

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

Message/error internationalization:

I have only updated the jar.properties for the English version of the new output and error messages. I don't know what the process is for adding this to other languages, if at all that needs to be done in this PR.

jar --help output:

Currently the jar --help output only talks about creation and updation of the jar. There's no mention of using the tool for extracting the jar content:

"jar creates an archive for classes and resources, and can manipulate or
restore individual classes or resources from an archive."

It does mention "manipulate" but doesn't specifically say extraction. The examples in the help command output don't have any examples for extraction. Should we add an example for extracting the jar file, in this help output?

Testing:

A new jtreg test has been introduced which tests various aspects of this feature. It runs most of those tests against both absolute and relative paths.

A couple of tests in the new introduced test case, check for the output/error messages. The jar tool uses resource bundles to print out these messages. I need input on whether I should enforce a specific locale to run these tests so that I can compare the error/output messages for expected strings? See testExtractFailWithMultipleDir() or testHelpOutput() for what I mean.

Man page:

This one I need input on. I have tried to see how these man pages are generated and from what I can understand it looks like these man pages are autogenerated during the build process using pandoc. Is that right? The hints that I see in the Docs.gmk seems to suggest that there are some markdown source files from which these man pages get generated. However, I can't seem to locate any such markdown files for this or other tools, from which the man pages get generated. Any help on how I should go about editing/updating the man page for the jar tool?

Example usage:

Here are some example usages:

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

This command extracts the somejar.jar file to the /tmp/foo/bar/ directory, creating it 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), "d1/f2.txt" and other files, then the above command extracts only "f1.txt" and "d1/f2.txt" into the /tmp/foo/bar/ directory.

-Jaikiran

On 14/03/21 6:21 pm, Alan Bateman wrote:
On 12/03/2021 12:18, Lance Andersen wrote:

:

I don?t have a strong preference but lean slightly towards ?-directory? as it is more descriptive, similar to the other GNU-style commands jar currently supports . Tar supports ??cd?, ??directory? in addition to ?-C? which is why I suggested supporting both GNU-style long options.

Perhaps jpackage should also support ?dir/directory in addition to ??dest' if we are looking at consistency between java tools.

I do agree that it would be nice to be consistent across the java tools for options so if we go the ?-directory?, we should follow your suggestion and make it the primary and remove ??dir? from the usage output.
My comment on consistency was limited to the long option to specify the directory when extracting, didn't mean to suggest doing anything with the other tools that specify an output/destination directory. In any case, I think we have enough to make progress on this issue now.

-Alan

[cid:E1C4E2F0-ECD0-4C9D-ADB4-B16CA7BCB7FC at home]

Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>

@mlbridge
Copy link

@mlbridge mlbridge bot commented Mar 29, 2021

Mailing list message from Jaikiran Pai on core-libs-dev:

On 28/03/21 9:52 pm, Lance Andersen wrote:

On Mar 28, 2021, at 9:24 AM, Jaikiran Pai <jai.forums2013 at gmail.com
<mailto:jai.forums2013 at gmail.com>> wrote:

Now when the user explicitly specifies the new -C or --dir option
with the -P option for extract, something like:

jar -xfP foo.jar -C /tmp/hello/

Given the support of -C/-dir is new and -P is there for backwards
compatibility then I see the choices are:

* Issue an error when -P and -C/-dir are specified together with -x
* Silently ignore the -P option
* Ignore -C/-dir and the behavior is if -xfP was specified.

I am leaning towards an error given this is a new feature when -P and
-C/-dir are specified with -x

That sounds reasonable to me. I'll update the PR accordingly to take
this into account.

-Jaikiran

@jaikiran
Copy link
Member Author

@jaikiran jaikiran commented Mar 31, 2021

A CSR for this enhancement has now been created https://bugs.openjdk.java.net/browse/JDK-8264510

Copy link
Contributor

@LanceAndersen LanceAndersen left a comment

Hi Jaikiran

Overall this looks good. I have a few comments below and will look at the CSR shortly.

@@ -1391,7 +1424,7 @@ ZipEntry extractFile(InputStream is, ZipEntry e) throws IOException {
if (name.length() == 0) {
return rc; // leading '/' or 'dot-dot' only path
}
File f = new File(name.replace('/', File.separatorChar));
File f = new File(xdestDir, name.replace('/', File.separatorChar));

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Could you please add a comment regarding xdestDir and also correct the typo on line 1418 'requres' -> 'requires'

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Fixed the typo and also added code comment about the xdestDir usage and semantics. If the new comment needs clarification/changes, do let me know.

@@ -159,6 +163,8 @@ out.inflated=\
\ inflated: {0}
out.size=\
(in = {0}) (out= {1})
out.extract.dir=\
extracting to {0}

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps 'Extracting to directory: {0}'

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Updated the message to say extracting to directory: {0}. I decided to use lower case for extracting to keep it consistent with other similar messages that get logged here.

}
return abs;
}

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Please add a comment to each test giving a high level overview of what it does as it will help future maintainers

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Done in latest update to this PR

Assert.assertEquals(exitCode, 0, "Failed to extract " + testJarPath);
// make sure only the specific files were extracted
final Stream<Path> paths = Files.walk(Path.of(tmpDir));
Assert.assertEquals(paths.count(), 6, "Unexpected number of files/dirs in " + tmpDir);

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Should '6' be in a local variable to make it clearer or at a minimum a comment

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

The latest update to the PR includes a comment explaining what this number represents.

Assert.assertEquals(Files.readAllBytes(f2), FILE_CONTENT, "Unexpected content in file " + f2);
}

private static Path createJarWithPFlagSemantics() throws IOException {

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a comment as to what the method does

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Done

@@ -239,7 +245,8 @@ main.help.opt.any=\
\ Operation modifiers valid in any mode:\n\
\n\
\ -C DIR Change to the specified directory and include the\n\
\ following file
\ following file. When used in extract mode, extracts\n\
\ the jar to the specified directory

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Should this be updated on line 187 as well in the compatibility mode section?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Updated in latest version of the PR.

error.extract.multiple.dest.dir=\
You may not specify more than one directory for extracting the jar
error.extract.pflag.not.allowed=\
-P option cannot be used when extracting a jar to a specific location

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps something similar to

You may not specify '-Px' with the '-C' or '--dir' options

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Makes sense. I've updated the PR with this change.

@@ -58,6 +58,10 @@ error.incorrect.length=\
incorrect length while processing: {0}
error.create.tempfile=\
Could not create a temporary file
error.extract.multiple.dest.dir=\
You may not specify more than one directory for extracting the jar

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps something similar to:

You may not specify the '-C' or '--dir' option more than once with the '-x' option

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Done

Copy link
Contributor

@LanceAndersen LanceAndersen left a comment

Some additional comments basically suggesting that we test --extract in addition to -x

*/
@Test
public void testExtractWithDirPFlagNotAllowed() throws Exception {
final String expectedErrMsg = "-P option cannot be used when extracting a jar to a specific location";

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Probably need to add a comment that this must match the entry in jar.properties

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Added a comment mentioning where this message is sourced from.

* {@code --dir} option is used
*/
@Test
public void testExtractWithDirPFlagNotAllowed() throws Exception {

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

I would include --extract in your testing options

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Done in latest version of the PR

* Tests that {@code jar -xvf <jarname> -C <dir>} works fine too
*/
@Test
public void testLegacyCompatibilityMode() throws Exception {

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

So from what I understand of the code in the jar tool the "legacy compatibility" mode stands for using the single hypen option and clubbing multiple options into one. Something like -xvfP instead of -x -v -f -P and this legacy compatibility mode isn't applicable for the long form options like --extract. So IMO using --extract here won't work. Let me know if I have misunderstood this review comment or the semantics of the legacy compatibility mode.

final List<String[]> cmdArgs = new ArrayList<>();
cmdArgs.add(new String[]{"-x", "-f", testJarPath.toString(), "-C", tmpDir, "-C", tmpDir});
cmdArgs.add(new String[]{"-x", "-f", testJarPath.toString(), "--dir", tmpDir, "--dir", tmpDir});
cmdArgs.add(new String[]{"-x", "-f", testJarPath.toString(), "--dir", tmpDir, "-C", tmpDir});

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps use a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Done

@Test
public void testExtractPartialContent() throws Exception {
final String tmpDir = Files.createTempDirectory(Path.of("."), "8173970-").toString();
final String[] cmdArgs = new String[]{"-x", "-f", testJarPath.toString(), "--dir", tmpDir,

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Didn't use a data provider, but did add tests for --extract as well, in the latest version of this PR.

* Extracts the jar file using {@code jar -x -f <jarfile> -C <dest>}
*/
private void testExtract(final String dest) throws Exception {
final String[] args = new String[]{"-x", "-f", testJarPath.toString(), "-C", dest};

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

The latest version of the PR tests the --extract as well.

cmdArgs.add(new String[]{"-x", "-f", testJarPath.toString(), "-P", "--dir", tmpDir});
cmdArgs.add(new String[]{"-x", "-f", testJarPath.toString(), "-P", "-C", "."});
cmdArgs.add(new String[]{"-x", "-f", testJarPath.toString(), "-P", "--dir", "."});
cmdArgs.add(new String[]{"-xvfP", testJarPath.toString(), "-C", tmpDir});

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Not a data provider but the latest version of PR tests --extract as well.

// create a jar which has leading slash (/) and dot-dot (..) preserved in entry names
final Path jarPath = createJarWithPFlagSemantics();
// extract with -P flag without any explicit destination directory (expect the extraction to work fine)
final String[] args = new String[]{"-xvfP", jarPath.toString()};

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Not a data provider but the latest version of PR tests --extract as well

public void testExtractLongForm() throws Exception {
final String dest = "foo-bar";
System.out.println("Extracting " + testJarPath + " to " + dest);
final int exitCode = JAR_TOOL.run(System.out, System.err, "-x", "-f", testJarPath.toString(),

This comment has been minimized.

@LanceAndersen

LanceAndersen Mar 31, 2021
Contributor

Perhaps add a DataProvider so you can test --extract as well?

This comment has been minimized.

@jaikiran

jaikiran Apr 1, 2021
Author Member

Not a data provider but the latest version of PR tests --extract as well

@jaikiran
Copy link
Member Author

@jaikiran jaikiran commented Apr 1, 2021

Thank you for the reviews, Lance. The latest version of this PR has taken into account most of these comments. There's one review comment which hasn't resulted in a change and I've added a reply to that review comment explaining my thoughts.

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented Apr 29, 2021

@jaikiran This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply add a new comment to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

@jaikiran
Copy link
Member Author

@jaikiran jaikiran commented Apr 29, 2021

Still active. Been busy with a few other things and I just need to get back and implement some inputs from Lance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
4 participants