设计

本文件概述了该库的设计并指定了一般规则,以帮助您了解如何使用该库。

对象

所有库对象可以分为两类:服务对象和不可变数据对象。 当数据对象只保存数据时,服务对象允许执行一些操作。 服务对象可以使用数据对象。

Engine, Profile, Browser, BrowserSettings, Frame, Document, JsObject 这样的对象是服务对象。像 EngineOptions, Size, Rect 这样的对象是不可变数据对象。

实例化

要创建不可变数据对象或服务对象,请使用其静态方法之一。 例如:

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)

解构

每个必须手动处理的服务对象都实现了 Closable 接口。 要处理服务对象并释放所有分配的内存和资源,请调用Closable.close()方法。 例如:

engine.close();
engine.close()

一些服务对象如 Frame 可以自动处理,例如,当网页被卸载时。

任何使用已关闭对象的尝试都将导致 IllegalStateException

关联

服务对象的生命周期可能取决于另一个对象的生命周期。 当您处理一个服务对象时,所有依赖它的服务对象都会自动处理。

例如,当您关闭 Engine 时,它的所有 Browser 实例都会自动关闭。 当您关闭 Browser 时,它的所有 Frame 实例都会自动关闭。

方法

不返回任何值的方法是异步执行的。 如果该方法返回某个值,则它将同步执行,阻塞当前线程执行,直到收到返回值。

如果该方法可以返回 null,那么它的返回值将被包装成 java.util.Optional。比如说。

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

参数

所有输入参数都不可为空。 如果将 null 作为输入参数传递给方法,该方法将抛出 NullPointerException。 例如:

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

事件

一个允许注册事件观察者的服务对象实现了com.teamdev.jxbrowser.event.Observable接口。 要注册一个事件观察者,可以使用on(Class<E> eventClass, Observer<E> observer)方法。 此方法返回Subscription。 使用此实例来退订接收所需的事件。 例如:

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

回调

每个允许注册回调的对象都实现了com.teamdev.jxbrowser.callback.Advisable 接口。 要注册和注销回调,必须使用 set(Class<C> callbackClass, C callback)remove(Class<C> callbackClass) 方法。

Callbacks can be asynchronous and synchronous.

异步

以下示例演示了如何注册和注销一个异步回调,该回调通过给定的 tell 参数异步返回响应:

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)

响应可以从不同的线程异步提供或在方法返回之前提供。

不要忘记通过给定的 tell 参数提供响应,否则 Engine 将等待响应直到终止。

该响应只能提供一次。

同步

以下示例演示了如何注册和注销通过返回值返回响应的同步回调:

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)

异常

该库仅抛出运行时异常,不抛出已检查异常。 请查看每个方法的 Javadoc 以找出它在什么情况下可能抛出的异常。

线程安全性

该库是线程安全的:可以在不同线程中安全地使用 JxBrowser 对象。

Go Top