Design

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.

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.

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

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.

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.

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