How Jolt works

The few ideas behind every Jolt app in plain terms: application, window, the UI thread, and the ways to show a page and talk to it.

You can build a lot with Jolt knowing only five ideas. This page explains them in plain terms, with no code you have to type. Later pages go deep on each one.

The big picture

 one process (your Java app)
+---------------------------------------------------+
|  Your Java code                                   |
|    Application  ->  WebWindow  <---- messages ----+--+
|                        |                          |  |
|                  native window                    |  |
|                +----------------+                 |  |
|                |    web view    |  your page      |  |
|                | (WebView2 or   | (HTML/CSS/JS) <-+--+
|                |  WebKitGTK)    |                 |
|                +----------------+                 |
+---------------------------------------------------+

Your Java code, the window and the page all live in one process. There is no separate server to start and no ports to pick. The page is drawn by the web view that comes with the operating system: WebView2 (Chromium) on Windows and WebKitGTK on Linux.

Application: the program

An Application is your running program. You create one, call run, and it stays in that call until the app ends. Only one application can run per process.

• Application.create(AppOptions.of("com.example.app")) builds it. The id should be unique to your app; Jolt uses it for the data folder, notifications and the autostart entry.
• app.run(() -> { ... }) runs the event loop. The function runs once at the start: create your windows there.
• The app ends when the last window closes (the default) or when something calls app.quit().

WebWindow: one window with one page

Each app.createWindow(options) gives you a WebWindow. You configure it with WindowOptions (title, size, icon and more), tell it what to show, and exchange messages with its page. You can open as many windows as you like.

Three ways to show a page

Three ways for Java and the page to talk

Start with messages. They are enough for most apps, and the other two are there when you need them.

The UI thread

A window system works on one thread, called the UI thread. app.run makes the thread that calls it the UI thread. Two rules cover nearly everything:

1. Every method of Application and WebWindow is safe to call from any thread. Jolt moves the call to the UI thread for you.
2. Never block the UI thread. Message listeners and the run callback run on it. If one of them waits (a slow query, a network call, .get() on a future), the whole window freezes. Do slow work on another thread and send the answer when it is ready.

When you need to run something on the UI thread yourself, use app.dispatch(Runnable), or app.submit(supplier) to get the result back as a future. app.isUiThread() tells you where you are.

Trust

Whatever your page can do, it can ask your Java code to do through messages. So every window has a SecurityPolicy: by default the window only shows your own content and origins you list, and only those can send messages to Java. You do not have to configure anything to be safe in the common case; the security page explains the switches.

Words used in these docs

Next: messaging between Java and the page.