Discussion: Naming API method

[John Hendrikx]

Hi,

I'm working on https://github.com/openjdk/jfx/pull/830 where I asked for 
some opinions on the naming of a new method I'd like to introduce in 
ObservableValue.

I wrote a (perhaps too large) comment about the possible names and 
rationales: https://github.com/openjdk/jfx/pull/830#issuecomment-1304846220

I'd like to ask what others think what would be a good name for this new 
method (Observable#when in the PR) in order to move the PR forward, as I 
think it offers a very compelling feature to JavaFX (moving from weak 
reference to deterministic behavior when it comes to listener 
management).  My opinion has always been that using weak listeners for 
listener management is a crutch that relies far too much on the internal 
workings of the JVM and Garbage Collector which offer no guarantees as 
to the timely clean up of these references and the listeners related to 
them.

Leading contenders are (but not limited to these, if you have a better 
name):

1) conditionOn

2) updateWhen

3) when

4) whenever

Usage in code is nearly always going to be something like these constructs:

       // keeps text property in sync with longLivedProperty when label 
is shown:
label.textProperty().bind(longLivedProperty.**when**(label::isShownProperty));

       // keeps text property in sync with longLivedProperty when 
container is shown:
label.textProperty().bind(longLivedProperty.**when**(container::isShownProperty)); 


It can also be used to make a listener only actively listen when a 
condition is met (the listener is added/removed immediately when the 
condition changes, facilitating GC):

       // listen to changes of longLivedProperty when container is shown:
       longLivedProperty.when(container::isShownProperty)
             .addListener((obs, old, current) -> { ... change listener 
... });

Or it can be used to disable updates temporarily (or permanently):

         BooleanProperty allowUpdates = new SimpleBooleanProperty(true)

         // keeps text property in sync when updates are allowed:
         name.textProperty().bind(model.title.when(allowUpdates));
detail.textProperty().bind(model.subtitle.when(allowUpdates));
asyncImageProperty.imageHandleProperty().bind(model.imageHandle.when(allowUpdates));

This last example can be useful in Skin#dispose, but has uses outside of 
skins as well, for example when you want to prevent updates until things 
have settled down.

Thanks for reading!

--John