8357176: java.awt javadoc code examples still use Applet API #25278

prrace · 2025-05-16T23:04:28Z

Update the some code examples and accompanying images to no longer mention or display as applets.

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

Warnings

⚠️ Patch contains a binary file (src/java.desktop/share/classes/java/awt/doc-files/BorderLayout-1.png)
⚠️ Patch contains a binary file (src/java.desktop/share/classes/java/awt/doc-files/FlowLayout-1.png)
⚠️ Patch contains a binary file (src/java.desktop/share/classes/java/awt/doc-files/GridBagLayout-1.png)
⚠️ Patch contains a binary file (src/java.desktop/share/classes/java/awt/doc-files/GridBagLayout-2.png)
⚠️ Patch contains a binary file (src/java.desktop/share/classes/java/awt/doc-files/GridLayout-1.png)
⚠️ Patch contains a binary file (src/java.desktop/share/classes/java/awt/doc-files/GridLayout-2.png)

Issue

JDK-8357176: java.awt javadoc code examples still use Applet API (Bug - P4)

Reviewers

Alexey Ivanov (@aivanov-jdk - Reviewer)
Sergey Bylokhov (@mrserb - Reviewer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 25278

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

Using diff file

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

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-05-16T23:05:20Z

👋 Welcome back prr! 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 · 2025-05-16T23:06:06Z

@prrace 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:

8357176: java.awt javadoc code examples still use Applet API

Reviewed-by: aivanov, serb

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

4d70689: 8351993: VectorShuffle access to and from MemorySegments
afcbf6b: 8357173: Split jtreg test group jdk tier3
8153683: 8345826: Do not automatically resolve jdk.internal.vm.ci when libgraal is used
... and 77 more: https://git.openjdk.org/jdk/compare/f6b0f016f6da5d9c96b21c74d3b906ed8e6ae4b4...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 · 2025-05-16T23:06:41Z

@prrace 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 · 2025-05-16T23:09:41Z

Webrevs

mrserb · 2025-05-19T00:04:33Z

It seems the new screenshots could be improved by capturing them on a HiDPI (Retina) display, as the current images appear blurry. And to eliminate background elements in the corners, it might be better to capture screenshots of undecorated windows as was done in the old images.

aivanov-jdk · 2025-05-19T12:41:09Z

src/java.desktop/share/classes/java/awt/GridBagLayout.java

- *         gridbag.setConstraints(button, c);
- *         add(button);
- *     }
+ *  static void addButton(String name,


Suggested change

* static void addButton(String name,

* private static void addButton(String name,

aivanov-jdk · 2025-05-19T12:41:43Z

src/java.desktop/share/classes/java/awt/GridBagLayout.java

+ *  static void addButton(String name,
+ *                        GridBagLayout gridbag,
+ *                        GridBagConstraints c,
+ *                        Frame frame) {
+ *     Button button = new Button(name);
+ *     gridbag.setConstraints(button, c);
+ *     frame.add(button);
+ *  }


The add method should indented by 4 spaces to the right.

aivanov-jdk · 2025-05-19T12:42:50Z

src/java.desktop/share/classes/java/awt/GridBagLayout.java

+ *  public static void main(String[] args) throws Exception {
 *
- *         setFont(new Font("SansSerif", Font.PLAIN, 14));
- *         setLayout(gridbag);
+ *    EventQueue.invokeAndWait(() -> {
+ *       Frame frame = new Frame("GridBagLayout");
+ *       GridBagLayout gridbag = new GridBagLayout();
+ *       GridBagConstraints c = new GridBagConstraints();
+ *       frame.setLayout(gridbag);


The main method should be indented by 4 spaces to the right, it's inside GridBagLayoutExample class.

will adjust

aivanov-jdk · 2025-05-19T12:44:35Z

src/java.desktop/share/classes/java/awt/GridBagLayout.java

 * right-to-left container.
 *
- * <div style="margin:0 auto;width:680px;text-align:center;font-weight:bold">
+ * <div style="margin:0 auto;width:850px;text-align:center;font-weight:bold">


Is it possible to keep the width small as it was?

I doubt it - unless you make the font really small, maybe?
If you look at how it is today you'll see the buttons are packed together using Motif L&F
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/GridBagLayout.html
BTW I tried a couple of times to upload javadoc to cr.openjdk.org so I could show the new rendered javadoc but uploads failed ...

BTW I tried a couple of times to upload javadoc to cr.openjdk.org so I could show the new rendered javadoc but uploads failed ...

I experienced some issues with uploading files to cr.openjdk.org some time ago; recently it worked well, however, the login isn't instantaneous. I uploaded the updated javadoc for PassFailJFrame yesterday.

Yeah, it would be helpful to look at the updated javadoc. If I have some time, I'll build updated javadoc and upload it…

aivanov-jdk · 2025-05-19T12:46:56Z

src/java.desktop/share/classes/java/awt/MediaTracker.java

 *          for (int i = 0; i < 5; i++) {
- *              anim[i] = getImage(getDocumentBase(),
- *                      "images/anim"+i+".gif");
+ *              anim[i] = tk.getImage("anim"+i+".gif");


Suggested change

* anim[i] = tk.getImage("anim"+i+".gif");

* anim[i] = tk.getImage("anim" + i + ".gif");

aivanov-jdk · 2025-05-19T12:51:07Z

src/java.desktop/share/classes/java/awt/doc-files/BorderLayout-1.png

The images would look better with square borders… which are left on Windows 10 only.

If it's possible to make the pixels on the rounded corners transparent or at least white, the images would look better.

I did not feel like getting into manual touch up of these images. In some cases they are a massive improvement over what was there before regardless eg this is how FlowLayout looks today
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/doc-files/FlowLayout-1.gif

I absolutely agree, the new screenshots are of a better quality.

aivanov-jdk · 2025-05-19T13:02:45Z

It seems the new screenshots could be improved by capturing them on a HiDPI (Retina) display, as the current images appear blurry. And to eliminate background elements in the corners, it might be better to capture screenshots of undecorated windows as was done in the old images.

To make the screenshots look good on High DPI displays, we need several images (preferably at 100%, 150% and 200% as the most common scales) and use the srcset attribute of the <img> element to provide different resolutions.

If you just create a screenshot on (Retina at 200% scale), the screenshots will be too large and still blurry as browsers will still scale up the screenshots to the scale of the display because the src attribute is treated as 100%-scale candidate only.

If we agree to go this way, I can create screenshots on Windows 10 (which still uses square window borders) in different resolutions.

src/java.desktop/share/classes/java/awt/BorderLayout.java

prrace · 2025-05-20T20:25:54Z

It seems the new screenshots could be improved by capturing them on a HiDPI (Retina) display, as the current images appear blurry. And to eliminate background elements in the corners, it might be better to capture screenshots of undecorated windows as was done in the old images.

To make the screenshots look good on High DPI displays, we need several images (preferably at 100%, 150% and 200% as the most common scales) and use the srcset attribute of the <img> element to provide different resolutions.

If you just create a screenshot on (Retina at 200% scale), the screenshots will be too large and still blurry as browsers will still scale up the screenshots to the scale of the display because the src attribute is treated as 100%-scale candidate only.

If we agree to go this way, I can create screenshots on Windows 10 (which still uses square window borders) in different resolutions.

Re-doing the images was necessary because they were obviously applets and extremely dated, so they are better (IMO) and good enough. I just figured out how to do the screen capture without the corners. macOS screen capture included a massive shadow that doubled the size. There's a trick (or two)
(1) Cmd-Shift-4 to enable screen capture
(2) Space to say you want to capture a specific window
(3) Option-Enter or Option-Left-Click will capture WITHOUT the shadow (phew)

I'll upload new images

If you want to do more in a follow-up fix, that's fine, although I am not sure about Windows 10 .. as its already on the way out.
I'm also not sure about any scaling of Windows 10 rendering as it will have LCD text which is notoriously bad when scaled.

mrserb · 2025-05-20T21:17:22Z

src/java.desktop/share/classes/java/awt/GridLayout.java

+ *   public static void main(String[] args) throws Exception {
+ *
+ *     EventQueue.invokeAndWait(() -> {
+ *        Frame frame = new Frame("GridLayout");


I would like to bring this to the discussion not necessarily suggesting any changes. I noticed that the example uses a "frame", while the description above refers to a "window" it might be worth unification. Also, regarding invokeAndWait: it’s not strictly necessary here since this is AWT but it does not break anything. However, I wonder if it’s worth discussing the use of invokeAndWait vs invokeLater. In tests, we usually prefer invokeAndWait because we need to wait for the action to complete, but in applications invokeLater should work fine.

A Frame (the java class) creates a window (the desktop concept). I would not want to promote the java type Frame to mean the concept.
Regarding invokeAndWait vs invokeLater, either is fine in this case and main has nothing else to do whilst waiting and is the safest default.
I pondered whether to do either in this simple case, but we do generally these days recommend this pattern even for AWT as Swing classes may be used to implement AWT .. and if I did not I guarantee someone would have said I should use it ! Whether or not it matters in this case.

I'm in favour of using invokeLater (or invokeAndWait) even for AWT components.

AWT doesn't explicitly declares its threading model. It's safer to create UI on EDT either way—it'll work for both AWT and Swing.

prrace · 2025-05-20T22:41:29Z

Ok .. here's uploaded javadoc to view
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/BorderLayout.html
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/FlowLayout.html
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/GridBagLayout.html
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/GridLayout.html
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/MediaTracker.html

mrserb · 2025-05-20T23:09:53Z

Ok .. here's uploaded javadoc to view

 // The background image fills the frame so we
 // don't need to clear the applet on repaints.
 // Just call the paint method.
 public void update(Graphics g) {
     paint(g);
 }

https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/MediaTracker.html

aivanov-jdk

I still have some minor nits.

aivanov-jdk · 2025-05-21T14:51:03Z

src/java.desktop/share/classes/java/awt/BorderLayout.java

+ * public class BorderLayoutExample {
+ *
+ *   public static void main(String[] args) throws Exception {
+ *
+ *     EventQueue.invokeAndWait(() -> {
+ *        Frame frame = new Frame("BorderLayout");
+ *        frame.setLayout(new BorderLayout());


Suggested change

* public class BorderLayoutExample {

*

* public static void main(String[] args) throws Exception {

*

* EventQueue.invokeAndWait(() -> {

* Frame frame = new Frame("BorderLayout");

* frame.setLayout(new BorderLayout());

* public class BorderLayoutExample {

*

* public static void main(String[] args) throws Exception {

* EventQueue.invokeAndWait(() -> {

* Frame frame = new Frame("BorderLayout");

* frame.setLayout(new BorderLayout());

I suggest following the standard indentation of 4 spaces to align with the recommended Java code style and dropping the blank line inside the main method.

Is there any particular reason for using invokeAndWait instead of invokeLater? Most Java UI tutorials use invokeLater.

(In the tests, we have to use invokeAndWait.)

aivanov-jdk · 2025-05-21T14:52:06Z

src/java.desktop/share/classes/java/awt/BorderLayout.java

- * <hr><blockquote><pre>
- * import java.awt.*;
- * import java.applet.Applet;
+ * <hr>


Suggested change

* <hr>

Drop the horizontal line. It separates the code from the paragraph that introduces it.

aivanov-jdk · 2025-05-21T16:10:55Z

src/java.desktop/share/classes/java/awt/GridLayout.java

+ * <hr>
+ * {@snippet lang='java':
 * <pre>


Suggested change

* <hr>

* {@snippet lang='java':

* <pre>

* {@snippet lang='java':

<pre> is inside the sample code.

aivanov-jdk · 2025-05-21T16:14:23Z

src/java.desktop/share/classes/java/awt/GridLayout.java

+ *   public static void main(String[] args) throws Exception {
+ *
+ *     EventQueue.invokeAndWait(() -> {
+ *        Frame frame = new Frame("GridLayout");


I'm in favour of using invokeLater (or invokeAndWait) even for AWT components.

AWT doesn't explicitly declares its threading model. It's safer to create UI on EDT either way—it'll work for both AWT and Swing.

aivanov-jdk · 2025-05-21T16:17:36Z

src/java.desktop/share/classes/java/awt/FlowLayout.java

- * <hr><blockquote><pre>
- * import java.awt.*;
- * import java.applet.Applet;
+ * <hr>


Suggested change

* <hr>

I suggest dropping the horizontal line from all the sample code.

aivanov-jdk · 2025-05-21T16:20:51Z

src/java.desktop/share/classes/java/awt/GridBagLayout.java

+ * import java.awt.GridBagLayout;
 *
- * public class GridBagEx1 extends Applet {
+ * public class GridBagLayoutExample {


This sample indents each code block by 4 spaces, which is good.

aivanov-jdk · 2025-05-21T16:23:52Z

src/java.desktop/share/classes/java/awt/GridLayout.java

+ * public class GridLayoutExample {
+ *
+ *   public static void main(String[] args) throws Exception {
+ *
+ *     EventQueue.invokeAndWait(() -> {
+ *        Frame frame = new Frame("GridLayout");


Let's indent the code by 4 spaces.

I'm also for removing the blank line that starts the main method.

aivanov-jdk · 2025-05-21T16:24:03Z

src/java.desktop/share/classes/java/awt/MediaTracker.java

 *
- * <hr><blockquote><pre>{@code
- * import java.applet.Applet;
+ * <hr>


Suggested change

* <hr>

aivanov-jdk · 2025-05-21T16:25:06Z

src/java.desktop/share/classes/java/awt/FlowLayout.java

- * import java.awt.*;
- * import java.applet.Applet;
+ * <hr>
+ * {@snippet  lang='java':


Suggested change

* {@snippet lang='java':

* {@snippet lang='java':

Not really an issue, however, other instances have just one space.

aivanov-jdk · 2025-05-21T16:27:38Z

src/java.desktop/share/classes/java/awt/MediaTracker.java

- *      public void stop() {
- *          animator = null;
- *      }
+ *     }


Suggested change

* }

* }

Correct the indentation.

aivanov-jdk · 2025-05-21T16:38:49Z

src/java.desktop/share/classes/java/awt/FlowLayout.java

- * <img src="doc-files/FlowLayout-1.gif"
+ * <img src="doc-files/FlowLayout-1.png"
 * ALT="Graphic of Layout for Three Buttons"
 * style="margin: 7px 10px;">


I'd drop this style attribute. It indents the image by 10 pixels to the right so that it doesn't align to the left edge of the surrounding text.

I see no value in increasing the vertical margins by 7px. Each paragraph has already 14px top/bottom margins.

aivanov-jdk · 2025-05-21T16:39:12Z

src/java.desktop/share/classes/java/awt/BorderLayout.java

+ * <img src="doc-files/BorderLayout-1.png" alt="Diagram of a window
 * demonstrating BorderLayout. Each section of the BorderLayout contains a
 * Button corresponding to its position in the layout, one of: North, West,
 * Center, East, or South." style="margin: 7px 10px;">


I'd drop this style attribute, too.

prrace · 2025-05-21T17:31:38Z

I think I have addressed all the "nits"

mrserb · 2025-05-21T18:56:51Z

Ok .. here's uploaded javadoc to view
 // The background image fills the frame so we
 // don't need to clear the applet on repaints.
 // Just call the paint method.
 public void update(Graphics g) {
     paint(g);
 }
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/MediaTracker.html

this reference to applet still exists.

mrserb · 2025-05-21T18:58:29Z

btw maybe it is better to present these layouts using swing(and its components)?

aivanov-jdk

It looks good to me.

Sergey's comment hasn't been resolved: MediaTracker.java still references applets in the code sample at line 148:

jdk/src/java.desktop/share/classes/java/awt/MediaTracker.java

Lines 147 to 150 in 42242c3

    
            *      // The background image fills the frame so we 
        
            *      // don't need to clear the applet on repaints. 
        
            *      // Just call the paint method. 
        
            *      public void update(Graphics g) {

prrace · 2025-05-21T20:13:07Z

Ok .. here's uploaded javadoc to view
 // The background image fills the frame so we
 // don't need to clear the applet on repaints.
 // Just call the paint method.
 public void update(Graphics g) {
     paint(g);
 }
https://cr.openjdk.org/~prr/8357176/api/java.desktop/java/awt/MediaTracker.html
this reference to applet still exists.

oops. I missed what that comment was about

prrace · 2025-05-21T20:15:43Z

btw maybe it is better to present these layouts using swing(and its components)?

This is in the AWT package so I think AWT components is better.
And the goal is just to get rid of the applet mentions and I've now done that (after the last one)

mrserb · 2025-05-21T20:53:32Z

This is in the AWT package so I think AWT components is better.
And the goal is just to get rid of the applet mentions and I've now done that (after the last one)

But these layout classes are used for both awt and swing libraries. And since we modernize the example and drop outdated applets we may change them to jframe instead+jbutton, on mac the images will be the same as for awt.

prrace · 2025-05-21T21:00:24Z

This is in the AWT package so I think AWT components is better.
And the goal is just to get rid of the applet mentions and I've now done that (after the last one)

But these layout classes are used for both awt and swing libraries. And since we modernize the example and drop outdated applets we may change them to jframe instead+jbutton, on mac the images will be the same as for awt.

I really don't see that as being the right thing to do here.

mrserb · 2025-05-21T21:54:54Z

I really don't see that as being the right thing to do here.

The goal of this change is to delete the usage of applet, but as a replacement the change uses the awt frame, while i think the right thing to use in our examples are "modern" swing components

prrace · 2025-05-22T19:19:14Z

/integrate

openjdk · 2025-05-22T19:19:49Z

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

b1b786a: 8357402: Crash in AdapterHandlerLibrary::lookup
9ca1004: 8352926: New test TestDockerMemoryMetricsSubgroup.java fails
1258af4: 8357135: java.lang.OutOfMemoryError: Error creating or attaching to libjvmci after JDK-8356447
... and 101 more: https://git.openjdk.org/jdk/compare/f6b0f016f6da5d9c96b21c74d3b906ed8e6ae4b4...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-05-22T19:20:02Z

@prrace Pushed as commit 139a05d.

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

8357176

d3d8a1c

openjdk bot changed the title ~~8357176~~ 8357176: java.awt javadoc code examples still use Applet API May 16, 2025

openjdk bot added the rfr Pull request is ready for review label May 16, 2025

openjdk bot added the client client-libs-dev@openjdk.org label May 16, 2025

aivanov-jdk reviewed May 19, 2025

View reviewed changes

aivanov-jdk reviewed May 20, 2025

View reviewed changes

src/java.desktop/share/classes/java/awt/BorderLayout.java Show resolved Hide resolved

8357176

9bfba37

mrserb reviewed May 20, 2025

View reviewed changes

8357176

21f4cba

aivanov-jdk suggested changes May 21, 2025

View reviewed changes

aivanov-jdk reviewed May 21, 2025

View reviewed changes

8357176

42242c3

aivanov-jdk suggested changes May 21, 2025

View reviewed changes

8357176

9104493

aivanov-jdk approved these changes May 21, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label May 21, 2025

mrserb approved these changes May 21, 2025

View reviewed changes

honkar-jdk mentioned this pull request May 22, 2025

JDK-8357082 : Stabilize and add debug logs to CopyAreaOOB.java #25279

Closed

3 tasks

openjdk bot added the integrated Pull request has been integrated label May 22, 2025

openjdk bot closed this May 22, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels May 22, 2025

	* static void addButton(String name,
	* private static void addButton(String name,

	* anim[i] = tk.getImage("anim"+i+".gif");
	* anim[i] = tk.getImage("anim" + i + ".gif");

	* // The background image fills the frame so we
	* // don't need to clear the applet on repaints.
	* // Just call the paint method.
	* public void update(Graphics g) {

8357176: java.awt javadoc code examples still use Applet API #25278

8357176: java.awt javadoc code examples still use Applet API #25278

Uh oh!

Conversation

prrace commented May 16, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Warnings

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented May 16, 2025

Uh oh!

openjdk bot commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented May 16, 2025

Uh oh!

mlbridge bot commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

mrserb commented May 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aivanov-jdk commented May 19, 2025

Uh oh!

Uh oh!

prrace commented May 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

prrace commented May 20, 2025

Uh oh!

mrserb commented May 20, 2025

Uh oh!

aivanov-jdk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

prrace commented May 16, 2025 •

edited by openjdk bot

Loading

openjdk bot commented May 16, 2025 •

edited

Loading

mlbridge bot commented May 16, 2025 •

edited

Loading

aivanov-jdk left a comment •

edited

Loading