GUI frameworks
Setting up JavaFX
  1. Development tools
  2. JPMS module info
    1. module-info.java
    2. Legacy build
  3. Maven
    1. Required steps
    2. POM Configuration
    3. Any easier way?
    4. Basic usage
  4. Other build systems and languages
  5. Distribution applications
  6. Old instructions (deprecated)

This tutorial will set up Maven to use the JavaFX. All the JavaFX related library and runtime files will be automatically downloaded with Maven. We recommend using the latest stable version.

Note that Gluon does not offer free updates to old JavaFX versions. Any updates to the LTS branch are only available for commercial users. Thus, from our point of view, the latest version is the recommended one to use. Currently the version 19 seems to be a fully working version without any major issues.

A special note for those using the OpenJFX Maven Archetypes for JavaFX: please update the JavaFX version number in pom.xml.

Development tools

If you're not familiar with Java development tools, please start by checking out the instructions for setting up the Java development tools.

This course assumes the development workstation is equipped with the following tools:
Java JDK (OpenJDK 11 or later), IDE (IDEA or Eclipse), Maven, Git, SceneBuilder, Scenic View (optional), Gradle (optional).

JPMS module info

The JPMS module info file is a preliminary requirement that does not depend on the selected build system.

module-info.java

From an application developer's point of view, the most visible change in JPMS based projects (compared to classic Java 1-8) is the requirement to provide module-info.java in src/main/java. This file should list all required packages (requires lines). In addition, a line with opens is required for accessing the FXML files and resources. The following code shows an example setup with four imported core JavaFX modules:

module fi.utu.tech.demo {
  requires transitive javafx.base;
  requires transitive javafx.graphics;
  requires transitive javafx.fxml;
  requires transitive javafx.controls;
  opens fi.utu.tech.demo;
}

Modern IDEs, such as the likes of IntelliJ IDEA, can help here by suggesting auto-completions for missing dependencies. A missing requires line will most likely lead to a compile or build time error.

Legacy build

If your application is not going to be used as a dependency anywhere, it's also possible to ship it without the module-info.java file. This will activate the legacy mode that allows implicit access to all included modules.

While this is not recommended in general, it still kind of works, but there is a small issue when launching the application: public static void main(String[]) class must be specified in a separate class that does not extend Application (see here why) Even if it first seems to work in a development environment, it will not work in production!

Be aware that this will expose both, the JavaFX and legacy Swing / AWT GUI classes, which can lead to incomprehensible problems when auto-importing GUI classes that share the same unqualified name (e.g. java.awt.Color & javafx.scene.paint.Color).

Maven

If you're not that familiar with Maven, please start by reading the build tool instructions.

Required steps

Assuming we have a simple Maven Java project template set up, one can use one of the three tools:

  1. Maven plugin for JavaFX
  2. Packaging Tool (external 3rd party instructions)
  3. maven-shade-plugin (discouraged since JavaFX 16)

In this tutorial, we will use the first approach for deploying JavaFX applications. In order to develop, execute, build, and deploy JavaFX applications with Maven, the following steps are required:

POM Configuration

First, locate the pom.xml file in the project root directory. If it does not exist, go back here.

Next, in the properties section of the pom.xml, set up the main class and the JavaFX version (the latest version is listed here):

<properties>
  <project.mainclass>fi.utu.tech.demo.Main</project.mainclass>
  <project.mainmodule>fi.utu.tech.demo</project.mainmodule>
  <project.launcher>myapp</project.launcher>
  <javafx.version>19</javafx.version>
</properties>

Then, add the required list of JavaFX module dependencies (one typically needs at least javafx-base, javafx-controls, maybe also the rest):

<dependencies>
  <dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-base</artifactId>
    <version>${javafx.version}</version>
  </dependency>
  <dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-controls</artifactId>
    <version>${javafx.version}</version>
  </dependency>
  <dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-fxml</artifactId>
    <version>${javafx.version}</version>
  </dependency>
  <dependency>
    <groupId>org.openjfx</groupId>
    <artifactId>javafx-graphics</artifactId>
    <version>${javafx.version}</version>
  </dependency>
</dependencies>

Next, configure the javafx-maven-plugin in the build section (usually no need to change anything!):

<plugin>
  <groupId>org.openjfx</groupId>
  <artifactId>javafx-maven-plugin</artifactId>
  <version>0.0.8</version>
  <configuration>
    <mainClass>${project.mainmodule}/${project.mainclass}</mainClass>
    <stripDebug>true</stripDebug>
    <compress>2</compress>
    <noHeaderFiles>true</noHeaderFiles>
    <noManPages>true</noManPages>
    <launcher>${project.launcher}</launcher>
  </configuration>
</plugin>

Any easier way?

Yes, there is. Just clone the prebuilt project template (git repository):

$ git clone https://gitlab.utu.fi/tech/education/gui/template-javafx

Basic usage

Now, the project can be built with (clean is not mandatory, but might help if the project is in a broken state):

$ mvn clean javafx:jlink

The resulting build can be launched by invoking:

$ ./target/image/bin/myapp

To quickly do a test run (!= unit testing) without building the whole jlink bundle:

$ mvn clean javafx:run

Note: the former build will include all resources and dependencies in the resulting .jar file, while the quick test build will use the resources from the src/main/resources folder!

Note: when deploying real world applications, knowledge of the other deployment methods disregarded here is highly appreciated.

Other build systems and languages

Advanced users may also wish to experiment with

Distribution applications

Old instructions (deprecated)

Previously instructions for building with maven-shade-plugin was provided. This approach still works, but has some issues with modular Java & JavaFX.

Instead of javafx-maven-plugin one needs to set up

  • pom.xml: exec-maven-plugin: for launching the app directly
  • pom.xml: maven-shade-plugin: for building and deploying the app

Also note that new JavaFX versions have trouble launching the application if the static main method is located in the Application class!

Run the project with:

$ mvn compile exec:java

Build the project with:

$ mvn package

Execute the resulting application with:

$ java -jar target/projectname-version.jar