Headless Platform module?

[Kevin Rushforth]

Interesting questions. There are two high level questions here (I 
think). First, should the Monocle headless platform be part of the 
javafx.graphics module or should it be a separate module? Second, should 
the headless "platform" be considered a completely different OS platform 
or, since it is largely platform-independent, should the headless 
platform be built and bundled with each OS. The two questions are 
somewhat related.

I haven't looked at the implementation of the headless platform, so this 
is a somewhat less informed opinion than it would be once I do.

As long as it is fairly small and doesn't have any public API surface 
(meaning that the only way to use it is a system property that then 
loads the Monocle glass backend along with another system property that 
selects the headless Monocle platform), it would seem easiest to leave 
it in javafx.graphics. This would mean we would start shipping the 
Monocle classes that we currently exclude as well as the new headless 
package. The second one depends on whether or not there is any native 
code associated with the headless glass platform. If not, then the 
easiest thing to do would be to always include it on all OS platforms.

There might be some advantages to putting it in its own module, but 
without also moving all of Monocle to a different module, this sounds 
like a lot of work and also would raise some issues that would have to 
be solved. Would we need to define an SPI? Formalize the Monocle back 
end interfaces? Hmm.

Anyway, this is just food for thought at this point.

-- Kevin


On 5/16/2025 5:14 AM, Johan Vos wrote:
> Hi,
>
> The Headless Glass Platform has been in the jfx sandbox repository [1] 
> for some time now, and we have provided a number of builds allowing 
> users to test the headless platform. The reactions were very positive. 
> It's mainly being used in 2 areas: testing is obviously a major 
> usecase, especially remote testing and testing on systems where you 
> don't want a UI to popup while developing; and applications where 
> desktop functionality is used (e.g. printing, snapshots,...) without a 
> UI window being shown.
>
> I got a number of requests from developers who want to see this part 
> of a non-sandbox build of OpenJFX.
> Hence, I want to start the work on adding the headless functionality 
> in the OpenJFX main repository. If you look at the diff between the 
> current head of the headless branch [1] and the master branch, you'll 
> notice it almost exclusively touches a new package: 
> com.sun.glass.ui.headless.
> There are some minor changes in quantum and gtk, but those can be 
> handled separately.
>
> Before starting the work on a JEP and a PR, I'd like to discuss the 
> following: do we want the headless platform to be part of an existing 
> module (javafx.graphics), or do we want it to be part of a new module?
> Currently, all glass platforms are part of the same module 
> (javafx.graphics), and different SDKs contain different 
> implementations -- with the Java top-level API being the same in all 
> modules.
>
> Apart from Monocle, there is a (non-official) 1-1 match between OS 
> platform and glass platform (e.g. linux using GTK, MacOS using mac, 
> iOS using ios,...). Therefore, the jmods, which are OS-specific, can 
> be (and are) organized in a way that they only contain the code that 
> is relevant to the target OS. It would be bad if the javafx.graphics 
> jmod for linux contained the windows-specific glass platform.
> Monocle violates this rule, because it is platform-independent (at its 
> own top-level, that is, because inside Monocle are a bunch of 
> platform-specific components). Our "official" builds do not include 
> Monocle, but we also offer builds with monocle, and it is pretty 
> confusing. There is some logic in the current build.gradle that either 
> includes or excludes monocle from the modules.
>
> I want to avoid this confusion with the Headless Platform.
> It is clear that a javafx.graphics module for MacOS should not contain 
> code for Windows, but should it contain code for Headless? I would 
> expect the answer to be "no". But then, how can developers use the 
> Headless Platform? The bad scenario is the one that currently is used 
> with monocle, where the answer is: "It depends". If you download a 
> "monocle SDK", then the javafx.graphcis jmod contains monocle, and 
> your SDK can use monocle, hence setting glass.platform=Monocle will 
> work. But with a regular build, the same will not work.
>
> Therefore, I believe it is worth considering the Headless Platform to 
> move into its own module. If developers want to leverage the Headless 
> Platform, they need to add the module. This requires work in the 
> javafx.graphics module, as the headless code requires access to 
> con.sun.glass.ui code, but I don't see any major issues here -- 
> although I don't want to underestimate the work needed to securely add 
> "glass providers" inside javafx.graphics. The latter might open the 
> road to external glass implementations being added at runtime in 
> specific configurations.
>
> A drawback I see for this approach is that the Headless Platform is 
> then treated differently from the other (existing) platforms. The GTK, 
> mac, win, android, ios platforms are all part of a single module, 
> where the Headless Platform would be in its own module. As explained 
> before, there is a very good reason for this (the 1-1 match between 
> those platforms and the target system OS), so I don't see that as an 
> ugly thing.
>
> Before going in more detail, I'd like to hear opinions about this 
> proposal to add a new module for the Headless Platform.
>
> - Johan
>
> [1] https://github.com/openjdk/jfx-sandbox/tree/johanvos-headless
> [2] https://gluonhq.com/products/javafx/ , select [Headless] in JavaFX 
> version