Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/edvin/fxlauncher

Auto updating launcher for JavaFX Applications
https://github.com/edvin/fxlauncher

Last synced: 3 months ago
JSON representation

Auto updating launcher for JavaFX Applications

Awesome Lists containing this project

README

        

# FXLauncher

[![Maven Central](https://maven-badges.herokuapp.com/maven-central/no.tornado/fxlauncher/badge.svg?cacheBust=true)](https://search.maven.org/#search|ga|1|no.tornado.fxlauncher)
[![Apache License](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)

Auto updating launcher for JavaFX Applications. Combined with JavaFX native packaging, you get
a native installer with automatic app updates.

You can see the launcher in action in this [Demo Application](http://fxldemo.tornado.no).

### QuickStart projects

- [Maven Example](https://github.com/edvin/fxldemo) with [pom.xml](https://github.com/edvin/fxldemo/blob/master/pom.xml)
- [Gradle Example](https://github.com/edvin/fxldemo-gradle) with [build.gradle](https://github.com/edvin/fxldemo-gradle/blob/master/build.gradle)

### Changelog

Check out [the changelog](https://github.com/edvin/fxlauncher/blob/master/CHANGELOG.md) for a list of all updates to the project.

### Video demonstration

See the launcher in action in this short [screencast](https://www.youtube.com/watch?v=NCP9wjRPQ14). There is also a [video](https://www.youtube.com/watch?v=-6PlFVUgntU) about customizing the update user interface.

## How does it work?

FXLauncher is a 18Kb jar that can be used to boot your application. It knows the location
of your application repository where you host all the app resources.

See a manifest [example here](http://fxldemo.tornado.no/app.xml). FXLauncher will look up the
remote repository to check for a newer version of the manifest on each startup.

After the manifest is retrieved, FXLauncher synchronizes every file mentioned in the manifest while
providing the user with a progress indicator. After all resources are in sync, a classloader is
initialized with all the resources from the manifest.

Lastly, the application entry point retrieved from the manifest is invoked. Everything happens in-JVM, no restarts needed.

Before each run, the launcher will synchronize all resources and seamlessly launch an always updated application.

## How to use FXLauncher

See the QuickStart projects at the top of the README for information on integrating FXLauncher in your build system.

### Adhoc usage

FXLauncher can also be used to launch an application at an arbitrary url by specifying the `--app` parameter at startup:

```bash
java -jar fxlauncher.jar --app=http://remote/location/app.xml
```

Alternatively (or in combination with `--app...`), you can override the uri attribute in the manifest (`app.xml`) so that both `app.xml` and all resources are loaded from the specified uri. This is especially useful for testing the complete setup locally or from a staging environment.

```bash
java -jar fxlauncher.jar --uri=http://remote/location/
```

The two parameters also work in tandem, allowing you to load a specified manifest from one URL and override its uri.

```bash
java -jar fxlauncher.jar --app=http://remote/location/app.xml --uri=http://remote/location/
```

Note: All parameters (including these) are passed on to your application. So please ensure that your parameters have a different name if they carry different data.

#### Include other artifacts

`--include-extensions` accepts a comma separated list of filename extensions to include of other resources from the build dir. By default it always includes jar, war.

#### Class-Loader issues

To load the application FXLauncher creates a new classloader fed with the classes of your manifest. This works as long as none of the
classes uses the system classloader to load one of your classes or resources which is not aware of the application classes then.

One example is Java's `java.net.URL` class which uses `Class.forName` to load a custom handler, which uses the classloader of
the callee which is the system classloader then.

To workaround that problem you could setup a special FXLauncher classloader which allows a different strategy how to feed the classpath
with additional classpath entries.

```bash
java -Djava.system.class.loader=fxlauncher.FxlauncherClassCloader -jar fxlauncher.jar --app=http://remote/location/app.xml
```

### Headless

FXLauncher allows you to run in headless mode and thus be used not only for JavaFX applications, but also for e.g. services which run
without any gui at all.

For this to work you could use `fxlauncher.HeadlessMainLauncher`

```bash
java -classpath fxlauncher.jar fxlauncher.HeadlessMainLauncher --app=http://remote/location/app.xml
```

Notice: `WhatsNew` is not supported.

### File based deployment

The app uri can be a `file://` based url instead of a web uri if your application is hosted on a common network location for your users.

#### UNC Paths
FXLauncher can deal with [UNC paths], if you ask it nicely. Instead of `\\server\share\myapp` use `file:////server/share/myapp`.
Yes, that's four forward slashes; two for the `file://` protocol and two for the UNC path.

[UNC paths]: https://www.lifewire.com/unc-universal-naming-convention-818230

### Native installers

The native installer does not contain any application code, only the launcher. There is
no need to rebuild your native installer when you update your project, simply run the `deploy-app` goal
and all users will run the newest version on their next startup. Point users to the `fxlauncher.jar` or
to a native installer if you wish.

### Try a native installer

Check out these prebuilt installers for a more complex demo application

- [MacOSX](http://fxldemo.tornado.no/FxlDemo-2.0.dmg)
- [Windows](http://fxldemo.tornado.no/FxlDemo-2.0.exe)
- [Linux](http://fxldemo.tornado.no/fxldemo-2.0.deb)

## Specify cache directory

By default, the artifacts are downloaded to the current working directory. This is usually fine for per-user native
installers, but if you distribute your application via a system-wide native installer, or just the launcher
jar, you might want to specify where the downloaded artifacts land. See the
[cache dir documentation] for more information.

[cache dir documentation]: https://github.com/edvin/fxlauncher/wiki/Optional-Cache-Directory

## Installation location

It's worth noting that the two package alternatives for Windows, (EXE and MSI) have different default install locations.
While EXE will default to [`%LocalAppData%`], the MSI installer will default to `%ProgramFiles%`. To write to
`%ProgramFiles%` one definitely does need admin privileges—that poses a problem for FXLauncher which, by default,
downloads updates to where it was installed.

If you use the MSI installer you will therefore need to tell FXLauncher to cache artifacts somewhere it is allowed
to put them. For an OS-independent answer to this problem, look no further than the
[two magical strings][cache dir documentation], `USERLIB` and `ALLUSERS`.

[`%LocalAppData%`]: https://www.howtogeek.com/318177/what-is-the-appdata-folder-in-windows/

Read more about Java Packager in the official documentation:

https://docs.oracle.com/javase/8/docs/technotes/guides/deploy/self-contained-packaging.html

## Accept downgrades

FXLauncher will not download a remote version if the local version is newer. This is controlled
by comparing a timestamp in the manifest. Specifying `--accept-downgrades=true` as the last argument to CreateManifest will
allow you to make sure that the version you have published will always be used by your clients even if they have a newer version installed.
This option is also available in the Gradle plugin as `acceptDowngrades`.

## Ignore ssl errors.

If you are behind a proxy that does a _man in the middle attack_ to snoop on ssl connections, you can use the
```--ignoressl``` commandline option to ignore the ssl errors this will generate.

## Stop after update errors.

Normally FXlauncher will try to launch the application even if there were errors
during the update of the files from the server. Often this will work using the files
already in the local cache. You can change this behavior by specifying
`--stop-on-update-errors=true`. The error will be shown and the launcher will exit.
Specifying `--stopOnUpdateErrors` will result in the same behavior, but this variant
is deprecated and will be removed in future versions. If both options are specified
the value of `--stop-on-update-errors` will be used.

## Show what's new dialog.

You can have FXLauncher show a whats new dialog. This dialog will
only be shown when FXLauncher has to download new files from the server. The html will be shown in a `WebView`. Specify `--whats-new=https://whatsnewurl/here`

### Applications with no default UI

By default the update screen will remain visible until the primary stage is shown. If your application does not show anything on the primary
stage at startup, the update screen will stay visible until it does. You can pass in `--lingering-update-screen=false` to hide it immediately
after the update process has completed.

## A slimmer alternative

Instead of using javapackager to create an installer, you can embed the fxlauncher jar in a native installer system like Advanced Installer—same approach as above,
but without using javapackager. With this approach, you can choose whether to include a JRE or have the installer software preinstall it.
Again, you are only distributing the launcher with the native installer, the rest is pulled down on demand.

### A note on classloaders

FXLauncher uses a custom classloader to dynamically load the synchronized resources. This classloader is
then made available to the `FXMLLoader`. You can access it via `FXMLLoader.getDefaultClassLoader()`.

### Platform specific resources

FXLauncher supports filtering of resources for the running platform. Any resource
that ends with `-[mac|win|linux].jar` will only be downloaded and put on the classpath on the corresponding
platform. The manifest enforces this though the `os` attribute in `app.xml`.

### Native libraries

If you need to load native libraries before the custom class loader kicks inn, specify the `--preload-native-libraries=` parameter
to CreateManifest. It supports a comma separated list of libraries to load. Remember: No extensions, just the library name.

### Custom UI

There are two ways to customize the appearance of the update UI. Either you can configure the
supported style properties in the manifest, or you can provide a custom implementation of the
[UIProvider](https://github.com/edvin/fxlauncher/blob/master/src/main/java/fxlauncher/UIProvider.java)
to completely customize the UI. Have a look at this [Custom UI Demo Project](https://github.com/edvin/fxlauncher-custom-ui) for
more information about customizing the updater.