Could we/May I fix the Swing Tutorial for Monitoring Progress?

[David Alayachew]

Hello Client Libs Dev Team,

The Swing tutorials found here (
https://docs.oracle.com/javase/tutorial/uiswing/) are top-notch, as
detailed as they need to be, and beginner friendly. These tutorials are
excellent, and I have most of the links on that page bookmarked, as I
reference them frequently when building GUI's.

That is why it is so surprising to see that the tutorial for Monitoring
Progress is so much worse than most of the others. Here is a link to the
tutorial in question.

https://docs.oracle.com/javase/tutorial/uiswing/components/progress.html

I have the short version of my thoughts here (
https://stackoverflow.com/questions/24835638/issues-with-swingworker-and-jprogressbar/24835935#comment136182857_24835935).
But I'll try and keep things down to what's needed.

For starters, the tutorial feels backwards. Normally, you would start with
the most basic/common use-cases first, then delve into the fringe/uncommon
use-cases later on in the tutorial. That is not what happens. We start off
with the more complex and configurable JProgressBar, and it is only after
we reach the halfway point of the tutorial, does it decide to let us know
that the ProgressMonitor, the simpler and more constrained option, is
available to us. This makes the on-ramp for learning this tool needlessly
steeper, just by approaching things in the wrong order.

Compare and contrast this to the Dialog tutorial (
https://docs.oracle.com/javase/tutorial/uiswing/components/dialog.html).
They follow a similar premise -- there is the complex JDialog, and the
simple JOptionPane. However, the Dialog tutorial gets it right. They start
off with an explicit intro that says "Here are 2 API's, one complex, one
simple. We will start with the simple one, but if it does not meet your
needs, you can easily switch to (or even compose your JOptionPane into) the
JDialog, allowing you to add complexity, only where necessary." This is
beginner friendly because it gives the most common use case first, and then
lets the user read on if they need something more complex.

Next, the code example they gave is spaghetti-code. Please look at it here (
https://docs.oracle.com/javase/tutorial/uiswing/examples/components/ProgressBarDemoProject/src/components/ProgressBarDemo.java).
Everything is bundled into a single file, when there's really at least 3
files here. It makes the example so difficult to read and follow along
with, as you struggle to put boundaries on what can and cannot occur at any
given point in the code.

After that, they pick the most beginner unfriendly way to demonstrate
concurrency to the user.

Monitoring progress and updating the progress bar simultaneously
necessitates using Concurrency in Swing (understandable). Therefore, the
tutorial encourages the user to accomplish this using the class SwingWorker
(as they should). But then, they pick the literal most complex and foot-gun
like way to do things - so much so that it defeats the entire point.

They tell the user to use SwingWorker::setProgress, which fires an event to
PropertyChangeListener, which can then be extracted from the ::getNewValue
method from the "progress" PropertyChangeEvent. Already, that's unideal,
but the real footgun is that there is the undocumented invariant that the
value you pass to ::setProgress must be between 0-100. This is particularly
foot-gun like because JProgressBar allows you to set the value to whatever
you want, and it will calculate the ratio for you (very nice). Many
developers will opt in to this convenience feature, and thus, will be
setting themselves up for failure when they try to follow the tutorials
direction of using a PropertyChangeListener, thinking they can just pass in
the new value for JProgressBar::setValue via the PropertyChangeListener.

This entire foot-gun situation could have easily been avoided if they just
used the ::publish/::process pair of methods, which are not only simpler,
but also facilitate the bundling of events, should the developer choose to
get involved with that.

Hopefully I have demonstrated how this particular tutorial has problems.

If so, I volunteer my time and efforts to fixing this tutorial. If anyone
could point me to the right place, I will happily submit a JBS ticket, and
then get started making the commit.

And I want to emphasize - the Oracle Swing tutorials are excellent. I
tutor, and when I teach Swing/GUI's, I always encourage them to start with
the Oracle Swing tutorials. That's my biggest reason for doing this - I
want to be able to say that about this tutorial too.

Please let me know your thoughts.

Thank you all for your time!
David Alayachew
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/client-libs-dev/attachments/20231007/c615e0dd/attachment.htm>