Concepção

Este documento dá uma visão geral da concepção da biblioteca e especifica as regras gerais para ajudá-lo a compreender a como trabalhar com ela.

Objetos

Todos os objetos da biblioteca podem ser divididos em duas categorias: objetos de serviço e objetos de dados imutáveis. Os objetos de serviço permitem realizar algumas operações quando os objetos de dados apenas guardam os dados. Os objetos de serviço podem utilizar os objetos de dados.

Os objetos como Engine, Profile, Browser, BrowserSettings, Frame, Document, JsObject são objetos de serviço. Os objetos como EngineOptions, Size, Rect são objetos de dados imutáveis.

Instanciação

Para criar um objeto de dados imutável ou um objeto de serviço, utilize um dos seus métodos estáticos. Por exemplo:

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)

Destruição

Todo objeto de serviço que deve ser descartado manualmente implementa a interface Closable. Para descartar um objeto de serviço e liberar toda a memória e recursos alocados, chame o método Closable.close(). Por exemplo:

engine.close();

engine.close()

Alguns objetos de serviço, tais como Frame podem ser eliminados automaticamente, por exemplo, quando a página Web é descarregada.

Qualquer tentativa de utilizar um objeto já fechado conduzirá à IllegalStateException.

Relacionamento

O ciclo de vida de um objeto de serviço pode depender do ciclo de vida de outro objeto. Quando um objeto de serviço é descartado, todos os objetos de serviço que dependem dele são descartados automaticamente.

Por exemplo, quando se fecha o Engine, todas as suas instâncias Browser são fechadas automaticamente. E quando se fecha o Browser, todas as suas instâncias Frame são fechadas automaticamente.

Métodos

Os métodos que não devolvem qualquer valor são executados de forma assíncrona. Se o método devolver algum valor, será executado de forma síncrona, bloqueando a execução da thread atual até que o valor de retorno seja recebido.

Se o método pode retornar null, o seu valor de retorno é envolvido em java.util.Optional. Por exemplo:

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

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

Argumentos

Todos os parâmetros de entrada são não-nulos. Se passar null como parâmetro de entrada para um método, o método lançará NullPointerException. Por exemplo:

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

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

Eventos

Um objeto de serviço que permite registar observadores de eventos, implementa a interface com.teamdev.jxbrowser.event.Observable. Para registar um observador de eventos utilize o método on(Class<E> eventClass, Observer<E> observer). Este método devolve Subscription. Utilize esta instância para cancelar a subscrição da recepção dos eventos necessários. Por exemplo:

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

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

Chamadas de retorno

Cada objeto que permite o registo de callbacks implementa a interface com.teamdev.jxbrowser.callback.Advisable. Para registar e anular o registo de um callback, devem ser utilizados os métodos set(Class<C> callbackClass, C callback) e remove(Class<C> callbackClass).

As chamadas de retorno podem ser assíncronas e síncronas.

Assíncrono

O exemplo a seguir demonstra como registrar e cancelar o registro de um retorno de chamada assíncrono que retorna a resposta de forma assíncrona através do argumento tell fornecido:

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)

A resposta pode ser fornecida de forma assíncrona a partir de uma thread diferente ou antes do retorno do método.

Não se esqueça de fornecer uma response através do argumento tell, caso contrário o Engine aguardará a resposta até o término.

A response só pode ser dada uma vez.

Sincronizar

O exemplo seguinte demonstra como registar e anular o registo de um retorno de chamada síncrono que devolve a resposta através de um valor de retorno:

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)

Exceções

A biblioteca lança apenas exceções de tempo de execução e não lança exceções verificadas. Consulte Javadoc para cada método para saber que exceções e em que situações podem ser lançadas.

Segurança de Thread

A biblioteca é thread safe: é possível utilizar com segurança objetos JxBrowser em diferentes threads.