设计

本文档概述了库的设计，并说明了通用规则，以帮助您理解如何使用它。

对象

所有库对象分为两类：服务对象（service objects）和数据对象（data objects）。服务对象用于执行操作，数据对象仅用于存储信息。服务对象可以使用数据对象。

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

实例化

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

Java
Kotlin
EngineOptions options = 
        EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
                .language(Language.CHINESE_CN)
                .build();
Engine engine = Engine.newInstance(options);
val options = EngineOptions.newBuilder(RenderingMode.HARDWARE_ACCELERATED)
        .language(Language.CHINESE_CN)
        .build()
val engine = Engine.newInstance(options)

释放

所有需要手动释放的服务对象都会实现 Closable 接口。要释放服务对象并释放所有分配的内存和资源，请调用 Closable.close() 方法。例如：

Java
Kotlin
engine.close();
engine.close()

部分服务对象（例如 Frame）可以自动释放，例如当网页被卸载时。

任何对已关闭对象的访问都会导致 IllegalStateException。

关系

服务对象的生命周期可能依赖于其他对象的生命周期。当你释放一个服务对象时，所有依赖于它的服务对象也会自动释放。

例如，当你关闭 Engine 时，其所有 Browser 实例会自动关闭。当你关闭 Browser 时，其所有 Frame 实例会自动关闭。

方法

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

如果方法可能返回 null，其返回值会被包装到 java.util.Optional 中。例如：

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

参数

所有输入参数都是非空的。如果将 null 作为输入参数传递给方法，该方法将抛出 NullPointerException。例如：

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

事件

允许注册事件观察者的服务对象会实现 tech.fuzio.event.Observable 接口。要注册事件观察者，请使用 on(Class<E> eventClass, Observer<E> observer) 方法。该方法返回 Subscription。使用该实例可以取消订阅相关事件。例如：

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

回调

每个允许注册回调的对象都会实现 tech.fuzio.callback.Advisable 接口。要注册和取消注册回调，必须使用 set(Class<C> callbackClass, C callback) 和 remove(Class<C> callbackClass) 方法。

回调可以是异步的，也可以是同步的。

异步

以下示例展示如何注册和取消注册一个异步回调，该回调通过给定的 tell 参数异步返回响应：

Java
Kotlin
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 将一直等待响应直到终止。

响应只能提供一次。

同步

以下示例演示如何注册和注销一个同步回调，该回调通过返回值来提供响应：

Java
Kotlin
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)

异常

该库仅抛出运行时异常，不抛出受检异常。请参阅 Java 和 Kotlin 的 API 规范，以了解每个方法在何种情况下可能抛出何种异常。

线程安全

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

架构

许可