This guide describes how to create, use, and close Engine.

Please consider reading the Architecture guide to better understand how JxBrowser architecture is designed, how it works and what main components it provides.

Creating Engine

To create a new Engine instance please use the Engine.newInstance(EngineOptions) static method. This method initializes and runs the Chromium engine with the passed options.

Engine engine = Engine.newInstance(engineOptions);

Depending on the hardware performance, the initialization process might take several seconds. We recommend that you do not call this method in the application UI thread because it might freeze the whole application for a while. Please use the approach described in the example.

When you create a new Engine instance, JxBrowser performs the following actions:

  1. Checks the environment and makes sure that it is supported.
  2. Finds the Chromium binaries and extracts them to the required directory if necessary.
  3. Runs the main process of the Chromium engine.
  4. Sets up the IPC connection between Java and the Chromium main process.

Engine Options

Rendering Mode

This option indicates how the content of a web page will be rendered.

The rendering mode option is a required option. If you do not specify the rendering mode an exception with an appropriate error message will be thrown during the Engine construction.

JxBrowser supports the following rendering modes.

Hardware Accelerated

In this rendering mode Chromium renders content using GPU and displays it directly on a surface. The following example demonstrates how to enable the hardware accelerated rendering mode:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setRenderingMode(RenderingMode.HARDWARE_ACCELERATED)
        .build());

Read more about the hardware accelerated rendering mode, its performance, and limitations.

Off-Screen

In this mode Chromium renders the content using GPU and copies the pixels to RAM. The following example demonstrates how to enable the off-screen rendering mode:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setRenderingMode(RenderingMode.OFF_SCREEN)
        .build());

Read more about the off-screen rendering mode, its performance, and limitations.

Language

This option configures the language used on the default error pages and the message dialogs. By default the language is dynamically configured according to the default locale of your Java application. If the list of supported languages does not contain the language obtained from the Java application locale, the US English language is used.

Current option allows you to override the default behavior and configure the Chromium engine with the given language. For example:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setLanguage(Language.GERMAN)
        ...
        .build());

In the code above we configure the Engine with the German language. If JxBrowser fails to load a web page, the error page in German will be displayed:

Error Page

User Data Directory

Represents an absolute path to the directory where the data such as cache, cookies, history, GPU cache, local storage, visited links, web data, spell checking dictionary files, etc. is stored. For example:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setUserDataDir("/users/me/.jxbrowser")
        ...
        .build());

The same user data directory cannot be used at the same time by multiple Engine instances running in a single or different Java applications. The Engine creation will fail if the directory is already used by another Engine.

If you do not provide the user data directory path, JxBrowser will create and use a temp directory in the user’s temp folder.

Incognito

This option indicates whether the Incognito mode for the Engine instance is enabled. In this mode the user data such as browsing history, cookies, site data, and the information entered in the forms on the web pages is stored in the memory and released once you close the Engine.

By default the Incognito mode is disabled.

The following example demonstrates how to enable the Incognito mode:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setIncognito(true)
        ...
        .build());

User Agent

Using this option you can configure the default user agent string. For example:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setUserAgent("<user-agent>")
        ...
        .build());

You can override the default user agent string in each Browser instance.

Remote Debugging Port

This option allows you to enable the Chrome Developer Tools (or DevTools) remote debugging. The following example demonstrates how to use this feature:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setRemoteDebuggingPort(9222)
        ...
        .build());

Now you can load the http://localhost:9222 web page in a Browser instance to open the Chrome DevTools page that allows inspecting HTML, debugging JavaScript etc.

Remote Debugging Port

You should not open the remote debugging URL in other web browser applications such as Mozilla Firefox, Microsoft Internet Explorer, Safari, Opera, etc. This will lead to a native crash in Chromium DevTools web server.

The remote debugging feature is compatible only with the Chromium version that equals to the version used by JxBrowser library. For example, if you use JxBrowser 7.0 based on Chromium 64.0.3282.24, you can open the remote debugging URL in Google Chrome/Chromium 64.0.3282.24 only.

We recommend to always load the remote debugging URL in a Browser instance instead of Google Chrome.

Chromium Binaries Directory

Use this option to define an absolute or relative path to the directory where the Chromium binaries are located or should be extracted to. For example:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setChromiumDir("/users/me/.jxbrowser/chromium")
        ...
        .build());

See also Chromium Binaries Location.

Chromium Switches

Use this option to define the Chromium switches that will be passed to the Chromium main process. For example:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .addSwitch("--<switch-name>")
        .addSwitch("--<switch-name>=<switch-value>")
        ...
        .build());

We don not recommend that you configure Chromium through the switches. Please configure Chromium through the EngineOptions.

Google APIs

Some Chromium features such as Geolocation, Spelling, Speech, etc. use Google APIs, and to access those APIs, an API Key, OAuth 2.0 client ID, and client secret are required. To acquire the API Key please follow this instruction.

To provide the API Key, client ID, and client secret use the following code:

Engine engine = Engine.newInstance(EngineOptions.newBuilder()
        .setGoogleApiKey("<api-key>")
        .setGoogleDefaultClientId("<client-id>")
        .setGoogleDefaultClientSecret("<client-secret>")
        ...
        .build());

Setting up API keys is optional. If you do not do it, some APIs using Google services will not work.

Closing Engine

The Engine allocates memory and system resources that must be released. So, when the Engine is no longer needed, it must be closed through the Engine.close() method to shutdown the native Chromium process and free all the allocated memory and system resources. For example:

Engine engine = Engine.newInstance(engineOptions);
...
engine.close();

Any attempt to use an already closed Engine will lead to the IllegalStateException.

To check whether the Engine is closed use the following method:

boolean closed = engine.isClosed();

Engine Events

Engine Closed

To get notifications when the Engine has been closed please use the EngineClosed event:

engine.on(EngineClosed.class, event -> {});

Engine Crashed

To get notifications when the Engine has been unexpectedly crashed due to an error inside the Chromium engine please use the EngineCrashed event:

engine.on(EngineCrashed.class, event -> {
    int exitCode = event.getExitCode();
});
Go Top