RFR: 8274771: Map, FlatMap and OrElse fluent bindings for ObservableValue [v10]

[John Hendrikx]

On Sun, 20 Mar 2022 03:08:59 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Both seem fine, I don't have any preference over one or the other.
>
> I struggled with finding a good description here [previously](https://github.com/openjdk/jfx/pull/675#discussion_r777801130). I think that mstr2 gave a good approach. What we can do if we want to have "the best of both worlds" is to write something in this form:
> 
> <Simple slightly-inaccurate summary>. More precisely, <Correct and more convoluted description>
> 
> 
> I would offer something like this based on your suggestions:
> 
> 
> Creates a new {@code ObservableValue} that holds the value of a nested {@code ObservableValue} supplied by the
> given mapping function. The result is updated when either this or the nested {@code ObservableValue} changes.
> If either this or the nested value is {@code null}, the resulting value is {@code null} (no mapping is applied if
> this value is {@code null}).
> More precisely, the created {@code ObservableValue} holds the value of an {@code ObservableValue} resulting
> from applying a mapping on this {@code ObservableValue}'s value.
> 
> I'm honestly not sure the "More precisely" part is even needed at his point. Up to you.
> 
> The `@return` description can be changed accordingly with the simplified explanation if you think it's clearer.
> 
> You can also specify a `@throws` NPE if the mapping function parameter is `null` instead of writing "cannot be null", like mstr2 suggested in another place if you like this pattern.
> 
> By the way, if we change "Creates an..." to "Creates a new..." we should change it in the other methods. I don't think there's a difference.

Resolving this one as we have this discussion elsewhere as well.

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

PR: https://git.openjdk.java.net/jfx/pull/675