List icon Contents


This document gives an overview of the design of the library and specifies the general rules to help you understand how to work with it.


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.


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

EngineOptions options = 
Engine engine = Engine.newInstance(options);
val options = EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
val engine = Engine.newInstance(options)


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:


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

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


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.


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()


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


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 -> {});
val subscription = browser.on( { event -> }


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.


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.set(, ConfirmCallback { params, tell -> tell.ok() })

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

Do not forget provide a response through the given tell argument, otherwise the Engine will wait for the response until termination.

The response can be provided only once.


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

browser.set(CreatePopupCallback.class, params -> 
browser.set(, CreatePopupCallback { 


The library throws only runtime exceptions and does not throw checked exceptions. Please see the Javadoc 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.

Go Top