Results of review of private JavaFX API for consideration to make public in JDK 9

[Jonathan Giles]

Hi all. In April of this year a discussion began when news broke that 
with JDK 9 access to private com.sun.* APIs would be disappearing [1]. A 
while back I posted a request to openjfx-dev for people to send me their 
JDeps output so that it could be analysed and used to inform our 
decisions around which API we should try to promote into public API. The 
response was very useful (and I should note: its too late now, please 
don't send me anymore JDeps files), and I believe we have the beginnings 
of a plan on how to move forward.

Before I outline the plan, please note that this discussion would 
ideally _not_ devolve into a feature requests discussion. What we are 
wanting to talk about today is simply API that exists in the com.sun.* 
package namespace which we can conceivably bring out of this namespace 
for JDK 9. Developing new API is expressly out of scope (unless it is 
related to simplifying or wrapping the com.sun.* API).

Another important point - UI control skins and a lot of very useful CSS 
API are being made public under JEP 253 [2]. A lot of the skin code has 
already been cleaned up, simplified, documented, etc, and will be 
merging into a repo very soon. I'll also post a separate post about JEP 
253 soon.

So, what does my JDeps analysis show (ignoring UI Controls and CSS 
usage, which has been largely resolved by JEP 253)? I can sum it up in 
the following categories:

== 'Toolkit' API ==
A lot of people use a small amount of API from Toolkit, such as the API 
for nested event loops, to fire a pulse, and to add / remove pulse 
listeners. Based on this analysis, the current thinking is to add API 
into the javafx.application.Platform class to enable the first two use 
cases above (nested event loops and pulse firing). The third use case 
needs more engineering effort, and is a far less common use case, so 
isn't being considered for JDK 9.

== 'Traversal' API ==
This API lives in com.sun.javafx.scene.traversal, and is quite useful 
when writing custom controls to ensure that keyboard traversal puts the 
focus in the right node at the right time. My ControlsFX open source 
project is a common (ab)user of this API, so I have a vested interest in 
making this public. Having said this, the API is actually in quite good 
shape, and it is possible with just a little JavaDoc work it could make 
the move into javafx.scene.traversal.

== 'Collections Event' API ==
There exists classes in com.sun.javafx.collections that are quite useful 
if you create your own custom ObservableList implementation and want to 
fire events at certain times. In my analysis there are only two projects 
using these APIs: ControlsFX and JVx by SIB Visions. The other pertinent 
point is that this code is quite easy to reproduce, so, whilst I would 
like to see this API public, it doesn't seem to make sense for JavaFX 9.

== 'Utils' API ==
There exists three classes that are quite commonly used by people for 
the various utility methods contained within. These classes are 
com.sun.javafx.util.Utils, com.sun.javafx.PlatformUtil, and 
com.sun.javafx.application.PlatformImpl. As most of these classes are 
just a collection of self-contained methods, it is quite likely that a 
number of these methods will find public API alternatives in a new class 
(although there are no plans to move all the methods over!).

== Miscellaneous API ==
Finally, there are a few classes that popped up quite frequently. Here 
is the list, and my thoughts on what to do with them:

1) com.sun.javafx.runtime.VersionInfo: Questionable about usefulness - 
not a likely candidate for JDK 9.
2) com.sun.javafx.event.EventHandlerManager: Only used in ControlsFX - 
not a likely candidate for JDK 9.
3) Robot: A good API to make public, but not a small API, so the scope 
is possibly too great for JDK 9.
4) PerformanceTracker: Same as Robot - good, but API might require more 
time than is available for JDK 9.

== What about other private API ==
If I've stated that an API you use isn't likely to make the cut for 9, 
there is another option: pull up your sleeves and work with us to get 
the API into a shape where it is good enough to commit to as public API. 
I should note that you shouldn't just dive in and do this - ping us and 
let us know first, so we can sync up and make sure the plan is feasible 
(and not overlapping). Because any large chunk of work would require 
moving through the JEP process, it is unlikely that anything other than 
small tweaks would be acceptable. One such example might be the 
PerformanceTracker.

== Where to from here? ==
The first milestone is to get JEP 253 into the main repo. That should 
hopefully be done before the end of August. Once that is done, focus can 
shift to the areas identified in this email. In the mean time, if there 
is any community feedback, please get it in ASAP so it can be included 
in the consideration.

[1] 
http://mail.openjdk.java.net/pipermail/openjfx-dev/2015-April/017017.html
[2] http://openjdk.java.net/jeps/253

Thanks!
-- Jonathan