8340466: Add description for PassFailJFrame constructors

[aivanov-jdk]

I added description to all the constructors available in PassFailJFrame.

I generated the javadoc for it: PassFailJFrame constructor details which is easier to read. This hosted javadoc could be used as a reference to its API.

The constructor with the largest number of parameters contains a short description of how to use the PassFailJFrame object.

Shall we deprecate the constructors in favour of Builder?

The builder provides a more streamlined experience, therefore new tests should use it instead of constructors. We may update the tests which use the constructors, after which the constructors can be removed.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8340466: Add description for PassFailJFrame constructors (Sub-task - P4)

Reviewers

• Phil Race (@prrace - Reviewer)
• Harshitha Onkar (@honkar-jdk - Reviewer) Review applies to ff2e7f82

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/21145/head:pull/21145
$ git checkout pull/21145

Update a local copy of the PR:
$ git checkout pull/21145
$ git pull https://git.openjdk.org/jdk.git pull/21145/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 21145

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/21145.diff

Webrev

Link to Webrev Comment

[bridgekeeper]

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

@aivanov-jdk 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:

8340466: Add description for PassFailJFrame constructors

Reviewed-by: prr, honkar

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 48 new commits pushed to the master branch:

• 8f75619: 8340864: Remove unused lines related to vmClasses
• 84751cb: 8340831: Simplify simple validation for class definition in MethodHandles.Lookup
• df1959f: 8340838: Clean up MutableCallSite to use explicit release fence instead of AtomicInteger
• 1b2d40a: 8340956: ProblemList 4 java/nio/channels/DatagramChannel tests on macosx-all
• f7bc9ba: 8340228: Open source couple more miscellaneous AWT tests
• 0e0b0b0: 8340684: Reading from an input stream backed by a closed ZipFile has no test coverage
• 81b5f09: 8340946: Add vmTestbase/gc/memory/Nio/Nio.java and java/nio/Buffer/LimitDirectMemory.java to problem list
• 0474f02: 8340815: Add SECURITY.md file
• fb70325: 8338583: NMT: Malloc overhead is calculated incorrectly
• 083b980: 8340568: Incorrect escaping of single quotes when pretty-printing character literals
• ... and 38 more: https://git.openjdk.org/jdk/compare/e97f0fe1b4046bfcc40e85ba1bee4f4c40053300...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.

[openjdk]

@aivanov-jdk The following label will be automatically applied to this pull request:

• client

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.

[mlbridge]

Webrevs

• 02: Full - Incremental (2bac4d48)
• 01: Full - Incremental (ff2e7f82)
• 00: Full (c36d4076)

[honkar-jdk]

Shall we deprecate the constructors in favor of Builder?

The builder provides a more streamlined experience, therefore new tests should use it instead of constructors. We may update the tests which use the constructors, after which the constructors can be removed.

There are some cases where the builder approach may not work as expected especially modal dialog tests and in such instances the older constructor methods are used.

[honkar-jdk]

Doc changes looks good.

[aivanov-jdk]

Shall we deprecate the constructors in favor of Builder?

The builder provides a more streamlined experience, therefore new tests should use it instead of constructors. We may update the tests which use the constructors, after which the constructors can be removed.

There are some cases where the builder approach may not work as expected especially modal dialog tests and in such instances the older constructor methods are used.

I can't see how it's possible… Do you have an example?

The builder provides the same features as constructors do. The only difference is that builder automatically shows all the registered windows.

Just like with the PassFailJFrame constructors, you can do other stuff before you use builder to create an instance of PassFailJFrame; just like with the constructors, you can do other stuff after creating the instance and before calling awaitAndCheck. You can use addTestWindow and positionTestWindow during the test execution if needed.

You also can employ (window) events to start or to synchronise other parts of running the test, LotsOfMenuItemsTest.java is a great example of such an approach.

jdk/test/jdk/java/awt/MenuItem/LotsOfMenuItemsTest.java

Lines 74 to 85 in 9806d21

	public void componentShown(ComponentEvent e) {
	final int x = firstFrame.getX();
	final int y = firstFrame.getY() + firstFrame.getHeight() + 8;
	TestFrame testFrame;
	for (int i = 1; i < NUM_WINDOWS - 1; ++i) {
	testFrame = new TestFrame("Running(" + i + ")...", x, y);
	testFrame.setVisible(false);
	testFrame.dispose();
	}
	testFrame = new TestFrame("Last Frame", x, y);
	PassFailJFrame.addTestWindow(testFrame);
	}

I agree there could be shortcomings in the PassFailJFrame design where you have to write more code for an uncommon scenario. However, if the most common scenario lets you write less code, it is still a win.

[aivanov-jdk]

/integrate

[openjdk]

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

• e2626db: 8340899: Remove wildcard bound in PositionWindows.positionTestWindows
• 10da2c2: 8340923: The class LogSelection copies uninitialized memory
• 8c8f0d8: 8339260: Move rarely used constants out of ClassFile
• 47c1069: 8340812: LambdaForm customization via MethodHandle::updateForm is not thread safe
• 66f1639: 8339271: giflib attribution correction
• 8f75619: 8340864: Remove unused lines related to vmClasses
• 84751cb: 8340831: Simplify simple validation for class definition in MethodHandles.Lookup
• df1959f: 8340838: Clean up MutableCallSite to use explicit release fence instead of AtomicInteger
• 1b2d40a: 8340956: ProblemList 4 java/nio/channels/DatagramChannel tests on macosx-all
• f7bc9ba: 8340228: Open source couple more miscellaneous AWT tests
• ... and 43 more: https://git.openjdk.org/jdk/compare/e97f0fe1b4046bfcc40e85ba1bee4f4c40053300...master

Your commit was automatically rebased without conflicts.

[openjdk]

@aivanov-jdk Pushed as commit 3762ec3.

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