Migration

From 6.x to 7.0

Within 7.x.x

Key changes

API & architecture

In JxBrowser 7 the architecture of the library has been improved. Now JxBrowser allows you to create two absolutely independent Browser instances and control their life cycle. Along with this internal architecture change the public API has been improved and extended with the new features as well.

Please see the mapping section to find out how the main functionality of 6.x maps to 7.0.

System requirements

Starting with this version JxBrowser no longer supports Oracle JREs 1.6 and 1.7, Apple’s and IBM’s JREs, macOS 10.9, and OSGi. Current System Requirements are available here.

JARs

The structure of the library has changed. Now the library consists of the following JARs:

jxbrowser-7.38.2.jar — the core classes and interfaces;
jxbrowser-swing-7.38.2.jar — the classes and interfaces for embedding into a Swing app;
jxbrowser-javafx-7.38.2.jar — the classes and interfaces for embedding into a JavaFX app;
jxbrowser-win32-7.38.2.jar — the Chromium 32-bit binaries for Windows;
jxbrowser-win64-7.38.2.jar — the Chromium 64-bit binaries for Windows;
jxbrowser-linux64-7.38.2.jar — the Chromium 64-bit binaries for Linux;
jxbrowser-mac-7.38.2.jar — the Chromium binaries for macOS.

Basic concepts

The way to create and dispose the objects has changed in the new API.

To create a service object use the <ServiceObject>.newInstance() static method. For example:

      Engine engine = Engine.newInstance(options);

    

      val engine = Engine.newInstance(options)

    

To create an immutable data object use the Object.newBuilder() static method. For example:

      EngineOptions engineOptions = EngineOptions.newBuilder(...)
        .setLanguage(Language.ENGLISH_US)
        .build();

    

      val options = EngineOptions.newBuilder(...)
        .language(Language.ENGLISH_US)
        .build()

    

Every object that should be disposed manually implements the com.teamdev.jxbrowser.Closable interface, e.g. com.teamdev.jxbrowser.Browser. To dispose the object call the com.teamdev.jxbrowser.Closable.close() method. For example:

      browser.close();

    

      browser.close()

    

Please note that some service objects depend on the other service objects. When you dispose a service object, all the service objects depending on it will be disposed automatically, so you do not need to close them manually. Please see the architecture guide for more details about the key objects and their interaction principles.

If a method can return null, its return value is wrapped into the java.util.Optional. For example:

      browser.mainFrame().ifPresent(frame -> {});

    

      browser.mainFrame().ifPresent { frame -> }

    

Events

The way to register an event listener has changed.

v6.x

We use a classic Observer pattern that consists of the addXxxListener(XxxListener listener) and removeXxxListener(XxxListener listener) methods that allow you to register and unregister an event listener. For example:

      TitleListener titleListener = new TitleListener() {
    @Override
    public void onTitleChange(TitleEvent event) {}
};
browser.addTitleListener(titleListener);

    

      val titleListener = object: TitleListener { 
    override fun onTitleChanged(event: TitleEvent) {}
} 
browser.addTitleListener(titleListener)

    

The event listener should be unregistered using an appropriate method when you do not want to receive the event notifications:

      browser.removeTitleListener(titleListener);

    

      browser.removeTitleListener(titleListener)

    

v7.0

A service object that allows registering event observers implements the com.teamdev.jxbrowser.event.Observable interface. To register an event observer use the on(Class<E> eventClass, Observer<E> observer) method. This method returns Subscription. Use this instance to unsubscribe from receiving the required events. For example:

      Subscription subscription = browser.on(TitleChanged.class, event -> {});
...
subscription.unsubscribe();

    

      val subscription = browser.on(TitleChanged::class.java) { event -> }
...
subscription.unsubscribe()

    

Callbacks

The logic of registering event handlers (callbacks) has changed as well.

v6.x

To register an event handler use the setXxxHandler(XxxHandler handler) method to set and remove an event handler. For example:

      browser.setDialogHandler(new DialogHandler() {
    ...
    @Override
    public CloseStatus onConfirmation(DialogParams params) {
        return CloseStatus.OK;
    }
    ...
});
browser.setDialogHandler(null);

    

      browser.setDialogHandler(object: DialogHandler {  
    ...
    override fun onConfirmation(params: DialogParams): CloseStatus = CloseStatus.OK
    ...
})

    

v7.0

Event handlers are now named Callbacks. Each object that allows registering callbacks implements the com.teamdev.jxbrowser.callback.Advisable interface. To register and unregister a callback the set(Class<C> callbackClass, C callback) and remove(Class<C> callbackClass) methods should be used. For example:

      browser.set(ConfirmCallback.class, (params, tell) -> tell.ok());
browser.remove(ConfirmCallback.class);

      browser.set(ConfirmCallback::class.java, ConfirmCallback { params, tell -> tell.ok() })
browser.remove(ConfirmCallback::class.java)

Please do not forget to return the result through the given tell parameter, otherwise the engine will wait blocked until termination.

Thread safety

The library is not thread-safe, so please do not work with the library from different threads at the same time.

Licensing

In JxBrowser 7 the license format and the way how the library checks the license has been improved.

v6.x

In the previous version the license represents a JAR file (e.g. license.jar) with the teamdev.licenses text file inside. This text file contains the plain text of the license. To setup the license you must include this JAR file in your Java app classpath.

The Project license is tied to a fully qualified class name (e.g. com.company.product.MyClass). It can be any class of your application. The only requirement is that this class must be included in the classpath of your Java app where you use JxBrowser.

v7.0

Now, the library requires a license key that represents a string with combination of letters and digits. You can add the license to your project via the jxbrowser.license.key System Property or through the API.

The Project license is tied to a package name now. The package name is expected to be in the com.company.product.module format. It should be a top-level package for the classes where you create an Engine instance.

For example, if the Project license is tied to the com.company.product package name, then you can create Engine instances only in the classes located in the com.company.product.* packages.

The Engine was introduced in JxBrowser 7. We recommend that you check out the guide that describes the new architecture, how to create an Engine and manage multiple Browsers lifecycle.

You can work with the created Engine instance and make calls to the library’s API from the classes located in other packages without any restrictions.

Dropped functionality

Starting with this version JxBrowser no longer supports Oracle JREs 1.6 and 1.7, Apple’s and IBM’s JREs, macOS 10.9, and OSGi.

In the new version the following functionality has been temporarily dropped. We are going to provide alternatives in the next updates:

Taking screenshots of the loaded web page. Restored in 7.1.
Suppressing mouse and keyboard events. Restored in 7.1.
Displaying the BeforeUnload dialog when closing Browser. The possibility to display the dialog when closing Browser was restored in 7.6. Read more.
Transparent background in the off-screen rendering mode. Restored in 7.2.
IME, Accessibility, and “Pinch to zoom” on macOS in the hardware accelerated (heavyweight) rendering mode.
WebStorage API. Restored in 7.1.
The SWT_AWT and FXCanvas bridges that allow embedding Swing/JavaFX BrowserView into SWT UI. Instead, please use SWT BrowserView introduced in 7.7.

Go top