Architecture

Overview 

The architecture of the JxBrowser library consists of multiple processes such as Java application process and different Chromium processes:

The following sections provide details for each of the processes, the main components of the library, and describe how it all works.

Processes 

Java 

This is a standard Java process where your Java/Kotlin application runs. Here you work with the JxBrowser API to initialize Engine, access the default Profile, create the Browser instances, load web pages, access Frame’s DOM, execute JavaScript, embed BrowserView into your Java Swing, JavaFX, or SWT desktop application to display content of the loaded web pages, etc.

Chromium 

Chromium uses a Multi-Process Architecture and runs multiple processes. Each process has its own type and purpose. Below you can find description of the basic process types.

Main 

This process is started by JxBrowser when you create Engine. It is the main process that manages the life-cycle of other Chromium processes. If you terminate this process, all other Chromium processes produced by this one will be terminated as well.

Renderer 

In this process the Frame instances which manage DOM and JavaScript of the loaded web page are running. The process is started by the Chromium engine when you navigate Browser to a web page with a different domain.

By default, each Renderer process runs in Sandbox, so it cannot directly use your disk, network, or display.

GPU 

In this process the content of the web pages loaded in different Chromium Renderer processes is rendered by Chromium using the GPU.

Inter-process communication 

Communication between different processes is done via Inter-Process Communication (IPC). IPC transfers data between two processes on a local machine.

To transfer data between Java and Chromium processes JxBrowser uses its own IPC implementation based on sockets and shared memory. Communication between Chromium processes is done via Chromium IPC implementation.

Main components 

Engine 

Manages the life cycle of the Chromium Main process and provides access to the core Chromium functionality that allows managing profiles, accessing all the available media input devices, etc.

To work with the engine please use the Engine class. It is a top-level object in the objects’ hierarchy of the library. Working with the library begins with creation of an Engine instance.

For detailed instructions on creation and usage of the Engine instance see the Engine guide.

Profile 

Represents a Chromium profile. It allows keeping all browser data separately, like history, cookies, cache, proxy settings, spellchecker configurations, etc. Each Engine has a default profile that is created automatically during Engine initialization. The default profile cannot be deleted.

You can create new profiles and delete them if they are not required using the Profiles service.

The profile’s files for history, cookies, cache, etc. are stored in the user data directory. If you configure Engine with the user data directory and create a profile, it will be stored in the user data directory and be restored after application restart.

Read more about profiles in the Profile guide.

Browser 

This is a web browser control which is responsible for loading web pages or local HTML files, finding text on the loaded web page, modifying zoom, working with audio, getting notifications about loading progress, dispatching keyboard and mouse events, and more.

To work with this control use the Browser class. Each Browser instance belongs to Profile. The Browser instance is closed automatically if its Profile is deleted or its Engine instance is closed or crashed.

The Browser guide provides details on how to create and use the Browser.

Frame 

Each web page loaded in Browser has a main Frame. The Frame itself may have child frames. You can use Frame to access and work with DOM and JavaScript. When a web page is unloaded, its Frame and all child frames are closed automatically.

Isolation between components 

Your application can create multiple Engine instances. Each engine can host multiple Profile instances, and each profile can contain multiple Browser instances. When you create two or more browsers, the way you distribute them across Engine and Profile instances affects both JxBrowser’s CPU and memory usage and the level of data isolation between different parts of your application.

The sections below explain how to choose a structure that meets your performance and isolation requirements.

Engines 

Creating a new Engine instance starts an independent Chromium instance. Running multiple engines significantly increases CPU and RAM usage, but provides the strongest runtime isolation.

All profiles, browsers, and other objects created within one engine are fully isolated from those created in any other engine. They run in separate process hierarchies and store user data in different directories.

If an Engine crashes, only the objects created within that engine are closed. Other engines continue operating normally.

Use separate Engine instances when strong data isolation and stability are critical and the performance overhead is acceptable.

Profiles 

A Profile manages network settings, cookies, user data, storage, and other state shared with the Browser instances created within it. Creating and maintaining profiles is much cheaper than creating multiple engines.

Create browsers in separate profiles when you need to isolate user data and sessions between the browsers. Each profile stores its data in its own subdirectory within the user data directory.

Browsers 

Browsers within the same profile share cookies, cache, and other user data, effectively behaving like tabs in a single Chromium window.

Use multiple Browser instances in a single profile when you need to work with multiple pages simultaneously and data isolation is not required.

How it works 

Creating Engine 

When you create an Engine instance, the library performs the following actions:

1. Start the Chromium Main and GPU processes.
2. Initialize Chromium engine in the Chromium Main process.
3. Initialize the default profile.
4. Setup IPC connection between Java and the Chromium Main process.

If you create two Engine instances, separate Chromium Main and GPU processes will be started for each instance. For example:

Creating Browser 

When you create a Browser instance, the library automatically loads an about:blank web page. It leads to the creation of the Chromium Renderer process where the DOM and JavaScript of this web page are running:

Closing Browser 

When you close the Browser instance, the corresponding Chromium Renderer process is terminated automatically. It means that all the Frame instances running in the terminated process will be automatically closed as well:

Closing Engine 

When you close the Engine, the library performs the following actions:

1. Close IPC connection between Java and the Chromium Main processes.
2. Dispose Chromium engine in the Chromium Main process.
3. Terminate the Chromium Main and GPU processes.