Design

Objects

All the library objects can be divided into two categories: service objects and immutable data objects. The service objects allow performing some operations when the data objects just hold the data. The service objects may use the data objects.

The objects like Engine, Profile, Browser, BrowserSettings, Frame, Document, JsObject are service objects. The objects like EngineOptions, Size, Rect are immutable data objects.

Instantiation

To create an immutable data object or a service object please use one of its static methods. For example:

EngineOptions options = 
        EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
                .language(Language.ENGLISH_US)
                .build();
Engine engine = Engine.newInstance(options);

val options = EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
        .language(Language.ENGLISH_US)
        .build()
val engine = Engine.newInstance(options)

Destruction

Every service object that must be disposed manually implements the Closable interface. To dispose a service object and release all allocated memory and resources please call the Closable.close() method. For example:

engine.close();

engine.close()

Some service objects such as Frame can be disposed automatically, e.g. when the web page is unloaded.

Relationship

The life cycle of a service object might depend on the life cycle of another object. When you dispose a service object, all the service objects that depend on it are disposed automatically.

For example, when you close the Engine, all its Browser instances are closed automatically. And when you close the Browser, all its Frame instances are closed automatically.

Methods

The methods that do not return any value are executed asynchronously. If the method returns some value, then it will be executed synchronously blocking the current thread execution until the return value is received.

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

Optional<Frame> mainFrame = browser.mainFrame();

val mainFrame: Optional<Frame> = browser.mainFrame()

Arguments

All input parameters are non-nullable. If you pass null as an input parameter to a method, the method will throw NullPointerException. For example:

Engine engine = Engine.newInstance(null); // <- NullPointerException

val engine = Engine.newInstance(null) // <- NullPointerException

Events

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

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 must be used.

Callbacks can be asynchronous and synchronous.

Async

The following example demonstrates how to register and unregister an asynchronous callback that returns response asynchronously through the given tell argument:

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)

The response can be provided asynchronously from a different thread or before the method returns.

Sync

The following example demonstrates how to register and unregister a synchronous callback that returns response through a return value:

browser.set(CreatePopupCallback.class, params -> 
        CreatePopupCallback.Response.create());
browser.remove(CreatePopupCallback.class);

browser.set(CreatePopupCallback::class.java, CreatePopupCallback { 
        CreatePopupCallback.Response.create() 
})
browser.remove(CreatePopupCallback::class.java)

Exceptions

The library throws only runtime exceptions and does not throw checked exceptions. Please see the API specification for Java and Kotlin for each method to find out what exceptions in what situations it might throw.

Thread safety

The library is thread safe: one can safely use JxBrowser objects in different threads.