设计
本文档概述了该库的设计并指定了一般规则,以帮助您了解如何使用该库。
对象
所有的库对象可以分为两类:服务对象和不可变数据对象。服务对象允许执行一些操作,而数据对象只是存储数据。服务对象可能会使用数据对象。
像 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)
方法。
回调可以是异步的,也可以是同步的。
异步
以下示例演示了如何通过给定的 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 对象。