Chromium

Binaries

Chromium binaries for each supported platform are located inside corresponding JxBrowser JARs:

• jxbrowser-win32-8.12.2.jar – Chromium binaries for Windows 32-bit.
• jxbrowser-win64-8.12.2.jar – Chromium binaries for Windows 64-bit.
• jxbrowser-mac-8.12.2.jar – Chromium binaries for macOS.
• jxbrowser-mac-arm-8.12.2.jar – Chromium binaries for macOS Apple Silicon.
• jxbrowser-linux64-8.12.2.jar – Chromium binaries for Linux 64-bit.
• jxbrowser-linux64-arm-8.12.2.jar – Chromium binaries for Linux ARM 64-bit.

Location

By default, JxBrowser extracts Chromium binaries to the user’s temp directory on Linux and macOS, and to AppData\Local\JxBrowser directory on Windows.

Here is how to change the directory where JxBrowser will extract the binaries:

1. Using the jxbrowser.chromium.dir system property.

   It can be done either by System.setProperty() method:

   Java

   Kotlin

   System.setProperty("jxbrowser.chromium.dir", "Users/Me/.jxbrowser");
   

   System.setProperty("jxbrowser.chromium.dir", "Users/Me/.jxbrowser")
   

   or through a JVM parameter:

   -Djxbrowser.chromium.dir="Users/Me/.jxbrowser"
   

2. Via the EngineOptions when constructing the Engine:

   Java

   Kotlin

   var engine = Engine.newInstance(
           EngineOptions.newBuilder(renderingMode)
                   .chromiumDir(Paths.get("Users/Me/.jxbrowser"))
                   .build()
   );
   

   val engine = Engine(renderingMode) {
       chromiumDir = Path("Users/Me/.jxbrowser")
   }
   

The directory path can be either relative or absolute.

Verification

Each JxBrowser version is compatible only with the same version of the binaries. For example, JxBrowser 8.12.2.1 will not work with the binaries from JxBrowser 8.12.2.

To make sure that the Chromium binaries are compatible with the current JxBrowser version, the library verifies the binaries.

Extraction

By default, JxBrowser extracts binaries from a corresponding JAR file when Engine is first created. If you need to extract binaries earlier, use this code:

// Use the default directory.
ChromiumBinaries.deliverToDefaultDirectory();
// Or use an arbitrary directory.
ChromiumBinaries.deliverTo(Paths.get("/path/to/binaries"));

// Use the default directory.
ChromiumBinaries.deliverToDefaultDirectory()
// Or use an arbitrary directory.
ChromiumBinaries.deliverTo(Path("/path/to/binaries"))

If the compatible binaries are already extracted, JxBrowser will not extract them again. Otherwise, JxBrowser will extract the binaries again and override the existing files.

Custom binaries delivery

Starting with JxBrowser 7.35, developers can get the full control of delivering Chromium binaries to the environment. This feature is for advanced tasks, like downloading binary files from the internet or using a custom compression method:

// Use the default directory.
ChromiumBinaries.deliverToDefaultDirectory(new MyDelivery());

// Or use an arbitrary directory.
ChromiumBinaries.deliverTo(chromiumDir, new MyDelivery());

// Use the default directory.
ChromiumBinaries.deliverToDefaultDirectory(MyDelivery())

// Or use an arbitrary directory.
ChromiumBinaries.deliverTo(chromiumDir, MyDelivery())

Preparing the binaries

In this section, we explain how to prepare an archive with binaries for the custom delivery. Repeat this process for every platform supported by your application.

First, extract the binaries from the JxBrowser distribution:

1. Clone a Quick Start project.

2. Run the project with a custom Chromium directory:

   ./gradlew run -Djxbrowser.chromium.dir=/path/to/chromium -Djxbrowser.license.key=...
   

   This command will extract Chromium binaries for the current platform into the specified directory:

   > ls /path/to/chromium
   Chromium.app    chromium.version    libawt_toolkit.dylib    libipc.dylib    ...
   

Second, pack up the binaries. In this example, we will use ZIP:

Compress-Archive -Path C:\path\to\chromium\* -DestinationPath binaries.zip

cd /path/to/chromium/
# The -y parameter preserves symlinks, which are used in the binaries.
zip -r -y ../binaries.zip .

Finally, upload the binaries.zip file to a place where your application can download it.

Delivering the binaries

In this section, we give you a simplistic example of the custom delivery that downloads the prepared archive with binaries:

import static com.teamdev.jxbrowser.os.Environment.isWindows;
...
class MyDelivery implements BinariesDelivery {

    private static final String URL = "http://.../binaries.zip";

    @Override
    public void deliverTo(Path chromiumDir) {
        var tempZip = download(URL);
        unpack(tempZip, chromiumDir);
    }

    private Path download(String url) {
        var client = HttpClient.newHttpClient();
        var request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .GET()
                .build();
        try {
            var tempZip = createTempFile("chromium-", ".zip");
            client.send(request, HttpResponse.BodyHandlers.ofFile(tempZip));
            return tempZip;
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }

    private void unpack(Path archive, Path directory) {
        var command = isWindows()
                ? new String[]{
                "powershell", "-Command", "Expand-Archive",
                "-Path", archive.toString(),
                "-DestinationPath", directory.toString()}
                : new String[]{
                        "unzip", archive.toString(),
                        "-d", directory.toString()};
        try {
            var process = Runtime.getRuntime().exec(command);
            process.waitFor();
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }
}

import com.teamdev.jxbrowser.os.Environment.isWindows
...
class MyDelivery : BinariesDelivery {

    override fun deliverTo(chromiumDir: Path) {
        val tempZip = download(URL)
        unpack(tempZip.toString(), chromiumDir.toString())
    }

    private fun download(url: String): Path {
        val client = HttpClient.newHttpClient()
        val request = HttpRequest.newBuilder()
            .uri(URI.create(URL))
            .GET()
            .build()
        val tempZip = createTempFile(suffix = ".zip")
        client.send(request, HttpResponse.BodyHandlers.ofFile(tempZip))
        return tempZip
    }

    private fun unpack(archive: String, directory: String) {
        val command = if (isWindows()) {
            arrayOf(
                "powershell", "-Command", "Expand-Archive",
                "-Path", archive, "-DestinationPath", directory
            )
        } else {
            arrayOf("unzip", archive, "-d", directory)
        }
        val process = Runtime.getRuntime().exec(command)
        process.waitFor()
    }

    companion object {
        private const val URL = "http://.../binaries.zip"
    }
}

Sandbox

Windows and macOS

JxBrowser supports Chromium Sandbox on Windows and macOS. Sandbox is enabled by default, but you can disable it via the appropriate Engine option:

var engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                .disableSandbox()
                .build()
);

val engine = Engine(renderingMode) {
    sandboxDisabled = true
}

Linux

Currently, Sandbox is supported on Windows and macOS platforms only.

Traffic

Chromium is a complex software that consists of many components. Some components may perform background network activity for various purposes like sending statistic data, synchronization, optimization, data download, etc.

In this section we describe the components that might generate additional network traffic and explain how to disable them.

Optimization Guide Service

This component represents a Chromium service from Google. It’s designed to help developers improve the app performance and efficiency. It provides tailored optimization advice and runtime configuration data based on a device’s specific hardware, software, and user habits. This service is especially essential when developing apps for Android. When started this service fetches the optimization models from a Google web service.

JxBrowser disables this component, so it doesn’t fetch any data from the Google web service.

Spell checker

By default, this component doesn’t send any requests to external web servers. It uses the local dictionaries to check the spelling. However, it may send requests to the Google web service to fetch the dictionaries for the languages that are not available locally.

If you don’t need the spell checker functionality, and you want to suppress any network activity related to it, you can disable the spell checker using the approach described in the Spell Checker guide.

Translate Ranker

This component is used to determine whether a user should be given a translation prompt or not. Chromium downloads the ranker models required for language determination.

This component is disabled in JxBrowser, so it doesn’t fetch any data from external web servers.

Media casting

This component is responsible for media content casting to the media devices with Chromecast. When Chromium is started this component sends a multicast request in the local network to discover the devices available for casting.

By default, the Chromecast feature is disabled and no traffic is generated. The Chromecast feature can be enabled when initializing an Engine instance as described in the Media guide.

Component Updater

This component is responsible for updating other components in Chromium. By default, it’s disabled. If you enable proprietary codecs, the component updater will be enabled automatically to update the corresponding internal components. When this component is enabled, you might see requests to https://update.googleapis.com/service/update2/json.

DNS Over HTTPS (DoH)

DoH is the default DNS resolution protocol used in Chromium. Chromium checks whether the system DNS provider supports DoH and tries to recognize it. If the system DNS is configured to use Google Public DNS or another recognized provider that supports DoH, Chromium will automatically switch to that provider’s DoH service. Thus, Chromium will make requests to the trusted DoH servers such as google.dns to resolve DNS.

By default, DoH is enabled in JxBrowser. If you want to disable it, use the following code:

var engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                .disableDnsOverHttps()
                .build()
);

When DoH is disabled, Chromium will use the unencrypted system DNS over UDP or TCP as configured by the operating system for DNS resolution

Branding

JxBrowser uses its own Chromium build, which is shipped as part of the library distribution. Chromium is running in a separate native process named Chromium. The process has the default icon, version, description, and copyright information.

When you integrate JxBrowser into your Java desktop app, you may want to customize the Chromium process name, icon, version, etc. and use your own branding for a better user experience. When it’s customized to match your app’s branding, your users will not be worried about the strange Chromium processes in the Task Manager.

To customize Chromium process use the open-source Chromium Branding command line tool. The instruction on how to use this tool is available in the README.md guide.

To configure JxBrowser to use the branded Chromium binaries, specify the path to the branded Chromium binaries when initializing the Engine instance:

var engine = Engine.newInstance(
        EngineOptions.newBuilder(renderingMode)
                .chromiumDir(Paths.get("path/to/branded/Chromium"))
                .build()
);

val engine = Engine(renderingMode) {
    chromiumDir = Path("path/to/branded/Chromium")
}

In the Customizing Chromium process name and icon article you can find a step-by-step guide on how to customize the Chromium process name, icon, version, and other branding information on Windows.