RFR: 8324797: Code example in JavaDoc of ObservableValue#when doesn't compile

[Philippe Altherr]

On Wed, 10 Jan 2024 02:36:32 GMT, Philippe Altherr <duke at openjdk.org> wrote:

> 8324797: Code example in JavaDoc of ObservableValue#when doesn't compile

If I can file the bug, I'm glad to do it.

It's a tiny bug. I noticed it while looking into Java FX for a new project. As I had no experience of FX, it wasn't immediately clear to me how to fix the example. Once I got the answer, I thought that I could as well quickly fix the documentation...

I did a quick search to see if there other instances of the same problem under [jfx/modules...](https://github.com/openjdk/jfx/blob/master/modules/). I didn't find any but I noticed that [here](https://github.com/openjdk/jfx/blob/37d7561c390f706b9e711dd535580fe5ae76e879/modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java#L160) and [here](https://github.com/openjdk/jfx/blob/37d7561c390f706b9e711dd535580fe5ae76e879/modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java#L191) in the same file you have the same issue and avoid it by using a `var`, which looks cleaner. My fix should probably do the same.

Below is the current code of the example. None of the calls to `setValue` compile.


     ObservableValue<Boolean> condition = new SimpleBooleanProperty(true);
     ObservableValue<String> longLivedProperty = new SimpleStringProperty("A");
     ObservableValue<String> whenProperty = longLivedProperty.when(condition);

     // observe whenProperty, which will in turn observe longLivedProperty
     whenProperty.addListener((ov, old, current) -> System.out.println(current));

     longLivedProperty.setValue("B");  // "B" is printed

     condition.setValue(false);

     // After condition becomes false, whenProperty stops observing longLivedProperty; condition
     // and whenProperty may now be eligible for GC despite being observed by the ChangeListener

     longLivedProperty.setValue("C");  // nothing is printed
     longLivedProperty.setValue("D");  // nothing is printed

     condition.setValue(true);  // longLivedProperty is observed again, and "D" is printed

I have enabled workflows. I have also filed an issue but it looks like this will go through a review of its own: review ID : 9076496 :-( In retrospect, I should have added a link to this PR.

modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java line 275:

> 273:      * For example:
> 274:      * <pre>{@code
> 275:      * Property<Boolean> condition = new SimpleBooleanProperty(true);

A better alternative might be to use a `var` like at line 160 and 191.

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

PR Comment: https://git.openjdk.org/jfx/pull/1325#issuecomment-1912611708
PR Comment: https://git.openjdk.org/jfx/pull/1325#issuecomment-1913185906
PR Comment: https://git.openjdk.org/jfx/pull/1325#issuecomment-1913190765
PR Review Comment: https://git.openjdk.org/jfx/pull/1325#discussion_r1468536432