8280543: Update the "java" and "jcmd" tool specification for CDS

[iklam]

The discussion of CDS in the man pages need to be cleaned up and updated to match the latest functionalities and intended usage.

For java.md:

• Reorganized the flow of the doc: Overview -> How to use -> How to create -> Restrictions and notes. I think this will be easier to read.
• Added information about jcmd VM.cds static_dump|dynamic_dump
• Removed a few sections that are no longer relevant or are uncommon usage (config files, sharing across two different apps)
• Removed discussion of uncommon error conditions (such as array classes)
• Removed detailed error messages. I think a simple note like "unsupported" will be good enough for readers of the man page.
• Removed discussion of different version of JDK (these should have been in release note)

For jcmd.md:

• Added some more details about default file name and output directory.

For ease of reviewing, please see the pre-rendered HTML pages:

http://cr.openjdk.java.net/~iklam/jdk19/8280543-update-java-and-jcmd-manpage-for-cds2/specs/man/

---

Progress

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

Issue

• JDK-8280543: Update the "java" and "jcmd" tool specification for CDS

Reviewers

• Harold Seigel (@hseigel - Reviewer) ⚠️ Review applies to edb4215
• Serguei Spitsyn (@sspitsyn - Reviewer) ⚠️ Review applies to edb4215
• Calvin Cheung (@calvinccheung - Reviewer) ⚠️ Review applies to edb4215

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 7255

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

Using diff file

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

[bridgekeeper]

👋 Welcome back iklam! 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]

@iklam The following label will be automatically applied to this pull request:

• serviceability

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

[iklam]

/label add hotspot-runtime

[openjdk]

@iklam
The hotspot-runtime label was successfully added.

[mlbridge]

Webrevs

• 01: Full - Incremental (120e4f86)
• 00: Full (edb42155)

[hseigel]

LGTM. The copyright in jcmd.1 needs updating.
Thanks, Harold

[openjdk]

@iklam This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8280543: Update the "java" and "jcmd" tool specification for CDS

Reviewed-by: hseigel, sspitsyn, ccheung

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 38 new commits pushed to the master branch:

• f991891: 8280949: Correct the references for the Java Security Standard Algorithm Names specification
• 319b774: 8277101: jcmd VM.cds dynamic_dump should not regenerate holder classes
• 993a248: 8280450: Add task queue printing to STW Full GCs
• dcc666d: 8280139: Report more detailed statistics about task stealing in task queue stats
• bdda43e: 8280705: Parallel: Full gc mark stack draining should prefer to make work available to other threads
• 091aff9: 8278908: [macOS] Unexpected text normalization on pasting from clipboard
• 61794c5: 8280817: Clean up and unify empty VM operations
• c6ed204: 8278263: Remove redundant synchronized from URLStreamHandler.openConnection methods
• 251351f: 8280889: java/lang/instrument/GetObjectSizeIntrinsicsTest.java fails with -XX:-UseCompressedOops
• be9f984: 8280553: resourcehogs/serviceability/sa/TestHeapDumpForLargeArray.java can fail if GC occurs
• ... and 28 more: https://git.openjdk.java.net/jdk/compare/c2ee1b33c37e6f2848dc8b3e5417b93b1dac1112...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[sspitsyn]

The jcmd update looks good.
Thanks,
Serguei

[calvinccheung]

LGTM

[iklam]

Thanks @hseigel @calvinccheung @sspitsyn for the review.
/integrate

[openjdk]

Going to push as commit 3916561.
Since your change was applied there have been 38 commits pushed to the master branch:

• f991891: 8280949: Correct the references for the Java Security Standard Algorithm Names specification
• 319b774: 8277101: jcmd VM.cds dynamic_dump should not regenerate holder classes
• 993a248: 8280450: Add task queue printing to STW Full GCs
• dcc666d: 8280139: Report more detailed statistics about task stealing in task queue stats
• bdda43e: 8280705: Parallel: Full gc mark stack draining should prefer to make work available to other threads
• 091aff9: 8278908: [macOS] Unexpected text normalization on pasting from clipboard
• 61794c5: 8280817: Clean up and unify empty VM operations
• c6ed204: 8278263: Remove redundant synchronized from URLStreamHandler.openConnection methods
• 251351f: 8280889: java/lang/instrument/GetObjectSizeIntrinsicsTest.java fails with -XX:-UseCompressedOops
• be9f984: 8280553: resourcehogs/serviceability/sa/TestHeapDumpForLargeArray.java can fail if GC occurs
• ... and 28 more: https://git.openjdk.java.net/jdk/compare/c2ee1b33c37e6f2848dc8b3e5417b93b1dac1112...master

Your commit was automatically rebased without conflicts.

[openjdk]

@iklam Pushed as commit 3916561.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.