Skip to content

Latest commit

 

History

History
166 lines (123 loc) · 7.78 KB

README.adoc

File metadata and controls

166 lines (123 loc) · 7.78 KB
Raw

Supernaut.FX

Build Status pipeline

Supernaut.FX is a lightweight dependency injection framework for JavaFX applications. It is a wrapper above the core dependency injection capability of Micronaut® framework (provided by the micronaut-inject JAR.) It enables the use of dependency injection in application, controller, and service objects.

Features

  • JavaFX-compatible Dependency Injection

    • Main application class is dependency-injected

    • JavaFX FXML controllers are dependency-injected

    • Service object dependency injection

  • Your main application class need not extend javafx.application.Application

  • BrowserService abstraction for opening links in Web Browser (abstraction of JavaFX HostServices)

    Simple

    Supernaut.FX aspires to be a component library for your application with the sole concern of enabling dependency injection.

    Modern

    Supernaut.Fx is designed for modern JavaFX applications that use the latest version of JavaFX (currently 17) and are built for distribution using either the jpackage tool of JDK 17 or as native images using GraalVM JDK 11 (using native-image and Gluon Substrate)

    Lightweight

    Supernaut.FX introduces no new dependencies beyond what is required for JavaFX and the micronaut-inject component of Micronaut® framework.

Getting Started

See the Getting Started section in the Supernaut.FX User’s Guide.

A sample, "hello world"-style project is available for cloning in both Maven and Gradle flavors.

API Documentation

Supernaut.FX JavaDoc is available on GitHub Pages.

Binaries

Although the API may change, binary packages are available on GitLab.com. You can download JARs or use the provided Maven coordinates to link to them directly from your pom.xml or build.gradle.

Maven

To access our GitLab Maven repository, add the following to your pom.xml:

<repositories>
  <repository>
    <id>gitlab-supernaut-maven</id>
    <url>https://gitlab.com/api/v4/projects/26584840/packages/maven</url>
  </repository>
</repositories>

See the Maven sample application for the details of setting up your pom.xml.

Gradle

To access our GitLab Maven repository, add the following to the repositories section of your build.gradle:

maven {
    url 'https://gitlab.com/api/v4/projects/26584840/packages/maven'
}

See the Gradle sample application for the details of setting up your build.gradle.

Modules

Supernaut.FX currently consists of 3 Java modules (JARs)

Module name Purpose Dependencies

app.supernaut

Interfaces for background components (no JavaFX)

No dependencies!

app.supernaut.fx

JavaFX application dependency injection support

  • app.supernaut

  • JavaFX

  • slf4j-api

app.supernaut.fx.micronaut

App Launcher with dependency injection provided by Micronaut framework

  • app.supernaut.fx

  • micronaut-inject

Typical applications will have a compile-time dependency on app.supernaut.fx and a runtime dependency on app.supernaut.fx.micronaut.

You may also develop library modules for services depending only on app.supernaut.

Building Supernaut

  1. Clone the repository

  2. Make sure your JAVA_HOME points to a JDK 17 or newer

  3. ./gradlew -PbaseModuleJavaCompatibility=8 buildCI buildJPackages

To test one of the included sample apps:

  1. Run the sample Hello app

    1. ./gradlew :apps:supernaut-fx-sample-hello:run

  2. Build a jpackage-ed Hello app

    1. ./gradlew :apps:supernaut-fx-sample-hello:jpackage

    2. Open the apps/supernaut-fx-sample-hello/build/jpackage directory and launch the native application for your platform

Inspired By

Supernaut.FX was inspired by two existing JavaFX DI frameworks, but is focused on JavaFX 11 and later, Java Module System, jlink, jpackage, and Micronaut framework. Thanks Adam Bien and Gluon for the inspiration.

Design Goals

We have researched existing JavaFX frameworks and haven’t found anything that seems well-suited for the following criteria:

  • Simple

    • Minimizes abstraction and inheritance

    • Avoids imposing architectural patterns (as much as possible with DI)

    • Try to be more of a library than a framework

  • Fast application launch

  • Provides support for compile-time dependency injection (e.g. via Micronaut framework)

    • Initial releases are for Micronaut framework only

    • Possibly in the future could use an abstraction to allow other similar DI frameworks (help wanted with this issue)

  • Designed for Java apps shipped with a bundled runtime

  • Aggressively tracks the latest JDK and JavaFX, recent Android versions

    • JDK 11 or later for JavaFX components

    • JDK 9 (maybe JDK 8 multi-release JARs?) for base interfaces and possible Android support

  • Minimal dependencies, minimal transitive dependencies

    • Core components in pure Java (no additional language runtime libraries)

    • Keep packaged/bundled apps as small as possible

    • Minimal dependencies simplifies security review

    • Potential for use by other frameworks

  • Compatible with Ahead-of-Time Compile tools

    • Avoids use of dynamic runtime features

    • Support popular Ahead-of-Time (AOT) compilation platforms

  • Support for first-class native-looking apps (via optional, add-on components)

    • Follows each platform’s UI guidelines

    • First-class platform integration

    • macOS integration

    • May use additional libraries (e.g. NSMenuFX) on a specific platform

  • Non-goal: reusable UI on desktop and mobile

    • Android apps have option to use custom UI written with Android SDK

    • iOS should have option to use UIKit