Package com.teamdev.jxbrowser.engine

Interface Engine

All Superinterfaces:
AutoCloseable, Closeable, Observable<EngineEvent>
public interface Engine extends Closeable, Observable<EngineEvent>
Provides access to the Chromium engine functionality.

To perform operations with the engine, a license key is required. The license key represents a string that can be set via the "jxbrowser.license.key" system property or individually for every Engine using the EngineOptions.Builder.licenseKey(String) method. If you set the license key via the system property, then please make sure that you set it before creating an Engine instance.

The Chromium engine is running in a separate native process. Communication between the native and Java process is done through the Inter-Process Communication (IPC) layer that allows transferring data between two processes on a local machine.

The native process allocates memory and system resources that must be released. So, when the engine is no longer needed, it must be closed through the Closeable.close() method to shutdown the native 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 get notifications that the Engine instance has been closed subscribe to the following event: 


 engine.on(EngineClosed.class, event -> {
     // The engine has been closed.
 });
To get notifications that the Engine instance has been unexpectedly terminated use: 

 engine.on(EngineCrashed.class, event -> {
     // The engine has been unexpectedly terminated.
 });

  • Method Details

    • newInstance

      static Engine newInstance(RenderingMode renderingMode)
      Initializes and runs the Chromium engine in the given renderingMode.

      Depending on the hardware performance, the initialization process might take several seconds. So, do not call this method in the application UI thread.

      The method performs the following actions:

      1. Checks the environment and makes sure that it is supported.
      2. Locates the Chromium binaries and extracts them if it is necessary.
      3. Runs the main native process and initializes the Chromium engine.
      4. Setup IPC connection between Java and the main native process.
      Parameters:
      renderingMode - the rendering mode indicating how the content of the web pages will be rendered
      Returns:
      a new instance of the Engine
      Throws:
      EnvironmentException - when the current environment is not supported
      UserDataDirectoryCreationException - when the given user data directory does not exist and cannot be created
      UserDataDirectoryAlreadyInUseException - when the given user data directory is already in use.
      IpcSetupFailureException - when Inter-Process Communication (IPC) setup has been failed
      ChromiumProcessStartupFailureException - when startup of the Chromium process has been failed
      NoLicenseException - when no license found
      InvalidLicenseException - when no valid license found
      ChromiumBinariesDeliveryException - when the verification of the Chromium binary files has failed and the binaries cannot be extracted from the resources
      MissingDependencyException - when Chromium fails to find the required system libraries. This exception can only be thrown on Linux
      SandboxNotSupportedException - when the current environment does not support running the engine in sandbox mode

    • newInstance

      static Engine newInstance(EngineOptions options)
      Initializes and runs the Chromium engine with the given options.

      Depending on the hardware performance, the initialization process might take several seconds. So, do not call this method in the application UI thread.

      The method performs the following actions:

      1. Checks the environment and makes sure that it is supported.
      2. Locates the Chromium binaries and extracts them if it is necessary.
      3. Runs the main native process and initializes the Chromium engine.
      4. Setup IPC connection between Java and the main native process.
      Parameters:
      options - the engine options
      Returns:
      a new instance of the Engine
      Throws:
      EnvironmentException - when the current environment is not supported
      UserDataDirectoryCreationException - when the given user data directory does not exist and cannot be created
      UserDataDirectoryAlreadyInUseException - when the given user data directory is already in use.
      IpcSetupFailureException - when Inter-Process Communication (IPC) setup has been failed
      ChromiumProcessStartupFailureException - when startup of the Chromium process has been failed
      NoLicenseException - when no license found
      InvalidLicenseException - when no valid license found
      ChromiumBinariesDeliveryException - when the verification of the Chromium binary files has failed and the binaries cannot be extracted from the resources
      MissingDependencyException - when Chromium fails to find the required system libraries. This exception can only be thrown on Linux
      SandboxNotSupportedException - when the current environment does not support running the engine in sandbox mode

    • options

      EngineOptions options()
      Returns the options the current engine was initialized with.

    • newBrowser

      Browser newBrowser()
      Creates a new Browser instance under the default profile and navigates it to the "about:blank" web page within the Navigation.defaultTimeout().
      Returns:
      a new Browser instance
      Throws:
      TimeoutException - when the engine failed to create a browser instance within the timeout
      NavigationException - when the navigation to the "about:blank" has failed
      ObjectClosedException - when the engine is already closed

    • browsers

      List<Browser> browsers()
      Returns an immutable list of alive Browser instances including child popup browsers for the default profile.

      Returns an empty list if the profile does not have any alive Browser.

      Returns:
      the list of alive Browser instances for the default profile of this engine

    • zoomLevels

      ZoomLevels zoomLevels()
      Returns a service that allows working with zoom.

    • proxy

      Proxy proxy()
      Returns a service that allows working with proxy.

    • network

      Network network()
      Returns a service that allows working with network.

    • spellChecker

      SpellChecker spellChecker()
      Returns a service that allows working with spell checking functionality.

    • cookieStore

      CookieStore cookieStore()
      Returns the cookie store that allows managing cookies.

    • httpCache

      HttpCache httpCache()
      Returns a service for working with HTTP cache.

    • httpAuthCache

      HttpAuthCache httpAuthCache()
      Returns a service for working with HTTP authentication cache.

    • mediaDevices

      MediaDevices mediaDevices()
      Returns a service that allows managing media stream devices.

    • plugins

      Plugins plugins()
      Returns a service that allows configuring plugins.

    • downloads

      Downloads downloads()
      Returns a service that allows managing downloads.

    • permissions

      Permissions permissions()
      Returns a service that allows managing permissions.

    • profiles

      Profiles profiles()
      Returns a service for managing profiles.

    • setTheme

      void setTheme(Theme theme)
      Updates the Chromium theme.

      This affects the appearance of web-pages and their contents, as well as Chromium dialogs, such as Print Preview and DevTools.

      In the incognito mode, this method does not change the appearance of the page, but does change the value returned by theme().

      Parameters:
      theme - the new Chromium theme
      Since:
      7.41.0

    • theme

      Theme theme()
      Returns the current Chromium theme.
      Since:
      7.41.0

    • widevine

      Widevine widevine()
      Returns a service that allows working with Widevine DRM.
      Since:
      8.9.0