de.espirit.firstspirit.client.gui.applications.browser

Interface BrowserApplication

public interface BrowserApplication

Browser application interface to open and control an integrated browser instance.

Example:

 appService = servicesBroker.getService(ApplicationService.class);
 browser = appService.openApplication(BrowserApplication.TYPE,  null).getApplication().getApplication();
 browser.openUrl("www.e-spirit.de");
 

Since:

4.2.416

Example:

Example how to create a browser application

Field Summary

Fields

Modifier and Type	Field and Description
static ApplicationType<BrowserApplication,BrowserApplicationConfiguration>	TYPE Application type to open this browser application.

Method Summary

Methods

Modifier and Type	Method and Description
void	addBrowserListener(BrowserListener listener) Adds the given browser listener to be notified on browser change events.
String	convertToScript(Object object) Converts specified java object into JavaScript code.
<T> BrowserNodeHandlerBuilder<T>	createNodeHandlerBuilder() Provides a builder for constructing and binding a BrowserNodeHandler.
Object	evaluateScript(String script) Executes given JavaScript code and evaluates return value.
Object	evaluateScriptMethod(String methodIdentifier, Object... arguments) Generates JavaScript code for the specified JavaScript method call, executes it in currently opened document and evaluates the return value of the method call.
void	executeScript(String script) Executes given JavaScript code in the currently opened document.
void	executeScriptMethod(String methodIdentifier, Object... arguments) Generates JavaScript code for the specified JavaScript method call and executes it in currently opened document.
void	focus() Requests that the related browser component get the input focus.
Document	getCurrentDocument() Returns accessor for the document in the currently loaded page.
EngineType	getEngineType() Returns the type of the browser engine that is currently used by this BrowserApplication.
String	getEngineVersion() Returns the version string of the browser engine that is currently used by this BrowserApplication.
String	getUrl() Returns the url of this browser application or null if no url requested yet.
void	inject(Object object, String name) Creates a javascript proxy for the given object instance.
void	openUrl(String url) Opens the given url.
void	removeBrowserListener(BrowserListener listener) Removes the given browser listener.
void	saveTo(String url, File file, ProgressListener listener) Requests the specified url and save content to specified file.
void	setHtmlContent(String html) Sets the specified HTML content to the current Browser document.

Field Detail

TYPE

static final ApplicationType<BrowserApplication,BrowserApplicationConfiguration> TYPE

Application type to open this browser application.

Example:

  openApplication(BrowserApplication.TYPE, config).getApplication();

Since:

4.2.416

Method Detail

getEngineVersion

@Nullable
String getEngineVersion()

Returns the version string of the browser engine that is currently used by this BrowserApplication.

Returns:

the version string of browser engine.

Since:

5.0.100

getEngineType

EngineType getEngineType()

Returns the type of the browser engine that is currently used by this BrowserApplication.

Returns:

the type of browser engine.

Since:

5.0.100

openUrl

void openUrl(String url)

Opens the given url.
Attenttion: This call will be executed asynchronous. Register a browser listener before calling this method, if you need to be informed of the location change calling this method will lead to.

Parameters:

url - to open

Since:

4.2.416

See Also:

addBrowserListener(BrowserListener)

getUrl

@Nullable
String getUrl()

Returns the url of this browser application or null if no url requested yet.
If necessary to ensure, that the url is completly loaded use browser listener.

Returns:

the current url of this browser application or null if no url requested yet.

Since:

4.2.416

See Also:

addBrowserListener(BrowserListener)

addBrowserListener

void addBrowserListener(@NotNull
                      BrowserListener listener)

Adds the given browser listener to be notified on browser change events.

Parameters:

listener - the listener to be notified

Since:

4.2.416

See Also:

removeBrowserListener(BrowserListener)

removeBrowserListener

void removeBrowserListener(@NotNull
                         BrowserListener listener)

Removes the given browser listener.

Parameters:

listener - the listener to be removed.

Since:

4.2.416

saveTo

void saveTo(String url,
          File file,
          ProgressListener listener)
            throws IOException

Requests the specified url and save content to specified file. Based on the current engine type the progress listening may not be supported.

Parameters:

url - url to load

file - the target file

listener - a listener for download progress or null

Throws:

IOException - when an error occurs during download process

Since:

4.2.436

See Also:

Browser.saveTo(String,File,ProgressListener)

focus

void focus()

Requests that the related browser component get the input focus.

Since:

4.2.436

See Also:

Browser.focus()

setHtmlContent

void setHtmlContent(String html)

Sets the specified HTML content to the current Browser document. This method is executing asynchronously. To make sure that the new HTML content was applied to the document completely register a browser listener.

Parameters:

html - a string that represents HTML content to set to the current document.

Since:

4.2.416

getCurrentDocument

Document getCurrentDocument()

Returns accessor for the document in the currently loaded page. Each node of type Element of the returned document will also be of type BrowserNode.
Ensure document is loaded completely before calling this method.
During accessing elements of the returned elements a DocumentGoneExceptionwill be thrown if the belonging nodes aren't accessible any more (e.g. cause browser navigated to a different url)

Returns:

accessor for browser dom document

Since:

4.2.416

See Also:

BrowserNode

executeScript

void executeScript(String script)

Executes given JavaScript code in the currently opened document.
Ensure document is loaded completely before calling this method.

Parameters:

script - script code to execute

Since:

4.2.416

executeScriptMethod

void executeScriptMethod(String methodIdentifier,
                       Object... arguments)

Generates JavaScript code for the specified JavaScript method call and executes it in currently opened document.
Ensure document is loaded completely before calling this method.

Parameters:

methodIdentifier - method identifier (for example: "window.methodName")

arguments - arguments the javascript method should be called with

Since:

4.2.426

See Also:

executeScript(String)

evaluateScript

@Nullable
Object evaluateScript(String script)

Executes given JavaScript code and evaluates return value.
Ensure document is loaded completely before calling this method.

The evaluation of the return value is based upon some basic java/javascript object conversion mechanism:

JavaScript	Java
number	Double
string	String
boolean	Boolean
array	List<Object>
object	Map<String,Object>

Parameters:

script - script code to be executed

Returns:

the evaluated return value of the script execution.

Since:

4.2.416

evaluateScriptMethod

@Nullable
Object evaluateScriptMethod(String methodIdentifier,
                                   Object... arguments)

Generates JavaScript code for the specified JavaScript method call, executes it in currently opened document and evaluates the return value of the method call.
Ensure document is loaded completely before calling this method.

Parameters:

methodIdentifier - method identifier (for example: "window.methodName")

arguments - arguments the javascript method should be called with

Returns:

the evaluated return value of the script execution.

Since:

4.2.426

See Also:

evaluateScript(String)

convertToScript

@Nullable
String convertToScript(Object object)

Converts specified java object into JavaScript code.

The conversion of the given object is based upon some basic java/javascript object conversion mechanism:

Java	JavaScript
Number, Boolean	(related toString mechanism)
String	"stringcontent"(escapes newline and ")
List<Object>	[entry0,entry1,entry2,...]
Map<String,Object>	{'key0':value0,'key1':value1,...}

Parameters:

object - javaobject that should be converted to JavaScript code

Returns:

the generated javascript code. returns null if object is null or unsupported

Since:

4.2.426

inject

void inject(Object object,
          String name)

Creates a javascript proxy for the given object instance. The new javascript object would be injected into the current web page with given name as an attribute of the window object. (Usage: window.{name})
Ensure document is loaded completely before calling this method.

Example:

public class Test {
public void call() {...}
public void set(String parameter) {...}
public String get() {...}
}

browserApp.inject(new Test(), "myTest");


Methods can be called in javascript like the following (Object registered with name 'myTest'):

window.myTest.call();
window.myTest.set("value");
window.Test.get(function(value){alert(value);});

The execution of related object methods is done asynchronously. Because of that any return value is given to an additional javascript callback function at the end of parameters.

Like evaluateScript(String) the method parameters and return values are converted under the same conversion pattern.

Bear in mind that all types of Number are equal in javascript and would be converted to javascript type 'number'.

Parameters:

object - the object that should be injected into web page

name - the name of the new javascript proxy object

Since:

4.2.416

createNodeHandlerBuilder

<T> BrowserNodeHandlerBuilder<T> createNodeHandlerBuilder()

Provides a builder for constructing and binding a BrowserNodeHandler.

Returns:

A builder on a node handler.

Since:

4.2.426