Skip to content

8358526: Clarify behavior of java.awt.HeadlessException constructed with no-args #25881

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.

Sign up for GitHub

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

Closed
wants to merge 1 commit into from
Closed

8358526: Clarify behavior of java.awt.HeadlessException constructed with no-args #25881

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/java.desktop/share/classes/java/awt/HeadlessException.java
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do copyright years need to be updated for this file if there's a docs change?

Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ public class HeadlessException extends UnsupportedOperationException {
private static final long serialVersionUID = 167183644944358563L;

/**
* Constructs new {@code HeadlessException} with empty message.
* Constructs a new {@code HeadlessException} with {@code null} as its detail message.
* The default headless message may replace {@code null} in some cases, as outlined below.
* <p>
* For such {@code HeadlessException} the default headless error message
* may be auto-generated for some platforms.
* The text of the default headless message may depend on
Comment on lines 54 to 56
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't align, the following text has to be modified too.

The first sentence of the second paragraph, “For such {@code HeadlessException} the default headless error message may be auto-generated for some platforms,” should be replaced with the slightly edited text from the HeadlessException(String) constructor: “For some platforms, the {@code null} detail message may be replaced with the default headless error message.”

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see why.

Expand Down
49 changes: 49 additions & 0 deletions test/jdk/java/awt/Headless/HeadlessExceptionTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
/*
* Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/

import java.awt.HeadlessException;

/*
* @test 8358526
* @summary Verify behaviour of no-args HeadlessException and getMessage
* @run main/othervm -Djava.awt.headless=true HeadlessExceptionTest
* @run main/othervm HeadlessExceptionTest
*/

public class HeadlessExceptionTest {

public static void main (String[] args) {
String nullmsg = new HeadlessException().getMessage();
String emptymsg = new HeadlessException("").getMessage();
Comment on lines +36 to +37
Copy link
Contributor

@honkar-jdk honkar-jdk Jun 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@prrace I was thinking of a case which would actually throw HeadlessException when run with Djava.awt.headless=true such as creating a frame or robot but the exception msg can be null or default message from GraphicsEnvironment so making it difficult to validate on different platforms. The current test works well to validate both empty and null message.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this test is run on headless hosts, the default headless message will always be present on Linux, therefore nullmsg will not be null.

If the test is run on headful hosts, the message should be null and empty string correspondingly.

@honkar-jdk Do you suggest a test needs expanding to cover both cases where the default headless message is present or not?

Copy link
Contributor

@honkar-jdk honkar-jdk Jun 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aivanov-jdk

Since this test is run on headless hosts, the default headless message will always be present on Linux, therefore nullmsg will not be null.

That is correct Alex. But since this default headless message is platform and GraphicsEnvironment specific, checking for specific message may not be feasible. Did you mean to verify just a non-null msg (on headless)?

@honkar-jdk Do you suggest a test needs expanding to cover both cases where the default headless message is present or not?

I think it can be added as an extra case but it may not be as important as the cases already being tested.
A test case where a Frame is created and displayed, run on headless env and we verify that headless exception is thrown with non-null msg. What do you think?

System.out.println("nullmsg=" + nullmsg);
System.out.println("emptymsg=" + emptymsg);
if (nullmsg != null) {
if ("".equals(nullmsg)) {
throw new RuntimeException("empty message instead of null");
}
if (!nullmsg.equals(emptymsg)) {
throw new RuntimeException("non-null messages differ");
}
}
}
}