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, Browser, BrowserSettings, Frame, Document, JsObject are service objects. The objects like EngineId, BrowserId, EngineOptions, ProxyConfig are immutable data objects.


To create an immutable data object please use its Builder. For example:

EngineOptions engineOptions = EngineOptions.newBuilder()

To create a service object please use its newInstance() static method. For example:

Engine engine = Engine.newInstance(engineOptions);


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.


Some service objects can be identified by a unique ID. To find an object with the required ID please use the with() static method. For example:

Browser.with(browserId).ifPresent(browser -> {});


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.getMainFrame();


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


A service object that allows registering an event listener implements the Observable interface. To register and unregister an event listener please use its on(Class<E> eventClass, EventListener<E> listener) and remove(EventListener<E> listener) methods. For example:

EventListener<TitleChanged> titleListener = event -> {};
browser.on(TitleChanged.class, titleListener);

If you do not want to receive the event notifications, unregister the event listener using the following method:



A service object that allows registering callbacks implements the Advisable interface. To register and unregister a callback please use its set(Class<C> callbackClass, C callback) and remove(Class<C> callbackClass) methods. For example:

browser.set(ConfirmCallback.class, (params, callback) -> callback.yes());

The Engine is blocked until you return the result through the given callback parameter. Do not forget to return the result through the given callback parameter, otherwise the Engine will wait for the result until termination.


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.


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

Go Top