RFR: 8340133: Add concise usage message to the java executable [v7]

[Magnus Ihse Bursie]

On Mon, 11 Nov 2024 14:23:46 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
>> 
>>  - Merge branch 'master' into JDK-8340133-2
>>  - Using correct pplaceholders.
>>  - Adjusting text as suggested.
>>  - Cleaning up the concise message:
>>    - using 2 spaces instead of 4,
>>    - rewording the "for more use --help" part of the message as suggested to avoid the word "launcher".
>>  - Using lowercase for the keys in the help, using 'source-file' program instead of 'single-file' program.
>>  - Using an enum instead of booleans, as suggested.
>>  - Adjusting the concise help as suggested: 'using main class of a JAR archive' and '<JarFile>.jar'/'<SourceFile>.java'
>>  - Adjusting the concise help based on review suggestions.
>>  - Cleanup.
>>  - Adjusting/improving the concise help.
>>  - ... and 1 more: https://git.openjdk.org/jdk/compare/59b0cde0...b4d7b493
>
> src/java.base/share/classes/sun/launcher/resources/launcher.properties line 241:
> 
>> 239: \  -jar <jarfile>.jar         to execute the main class of a JAR archive\n\
>> 240: \  -m <module>[/<mainclass>]  to execute the main class of a module\n\
>> 241: \  <sourcefile>.java          to compile and execute a source-file program\n\n\
> 
> I'm not sure about the description of <mainclass>. It uses "compiled class", maybe you meant "compiled main class" or something else to connect it "<mainclass>"?
> 
> "-jar <jarfile>.jar" may be confusing because the "java -help" uses "-java <jarfile">". I think the usages need to be the same.

@AlanBateman I'd like to respectfully disagree that this was an improvement. If consistency was the important objection here, maybe it would have been better to update "java -help" to include the `.jar`?

In particular, losing the `.java` extension is problematic. I believe that this is essential to the launcher in how it determines if I am trying to launch a class or a source-file program. I just recently tried renaming my `HelloWorld.java` to `HelloWorld.java.old`, but when I ran `java HelloWorld.java.old` I got a warning implying that java thought I was trying to run the class `old` in the package `HelloWorld.java`.

I guess a better solution for the launcher would be to check if the argument given could match an existing text file, even if it looks like a fully qualified class name (but that does not exist). In fact, that might probably be worth a bug report of its own.

But I insist that as long as the current behavior stands, where the trailing `.java` is essential for the launcher to understand that it is launching a source-file program, then the `.java` literal should be a part of the help.

And, for the sake of consistency, that would also imply that the `.jar` suffix should be kept. (I don't know if the launcher would accept like `-jar foo.jar.old`..?)

I still recall how I **struggled** when learning Java that I should do `javac HelloWorld`**`.java`** but not `java HelloWorld`**`.class`**. By explicitly stating `.jar` and `.java` where those are expected, we indirectly underscore the important fact that the class specifications should be made **without** any extension.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21411#discussion_r1838130624