net.java.html.js

Annotation Type JavaScriptBody

@Retention(value=CLASS)
 @Target(value={METHOD,CONSTRUCTOR})
public @interface JavaScriptBody

Put this annotation on a method to provide its special implementation in JavaScript. This is a way to define native methods that interact with the surrounding JavaScript environment. Check the list use-cases to see real world use of this annotation.

Visit an on-line demo to play with JavaScriptBody annotation for real.

Author:

Jaroslav Tulach

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
String[]	args Names of parameters for the method generated method that can be referenced from JavaScriptBody.body().
String	body The actual body of the method in JavaScript.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	javacall Should a special syntax for calling back into Java object be turned on?
boolean	keepAlive Controls garbage collection behavior of method parameters.
boolean	wait4js Should we wait before the JavaScript snippet execution finishes?

Element Detail

args

public abstract String[] args

Names of parameters for the method generated method that can be referenced from JavaScriptBody.body().

Returns:

array of the names of parameters for the method in JavaScript

body

public abstract String body

The actual body of the method in JavaScript. This string will be put into generated header (last character is '{') and footer (e.g. '}'). The body can reference provided arguments. In case of non-static instance method it may reference this.

Returns:

JavaScript body of a function which can access JavaScriptBody.args() and possibly this

javacall

public abstract boolean javacall

Should a special syntax for calling back into Java object be turned on? The syntax begins with @ followed by fully qualified package name of the class. Now followed by :: and a method in the class followed by its parameters enclosed inside (...). This is the syntax one can use to call run() method of Runnable:

r.@java.lang.Runnable::run()()

. One can also call static methods. Just use:

var ten = @java.lang.Integer::parseInt(Ljava/lang/String;)("10")

Returns:

true, if the script should be scanned for special callback syntax

Default:

false

wait4js

public abstract boolean wait4js

Should we wait before the JavaScript snippet execution finishes? Or not.

Some implementations that recognize the JavaScriptBody annotation need to reschedule the JavaScript execution into different thread and then it is easier for them to perform the execution asynchronously and not wait for the result of the execution. This may however be unexpected (for example when one awaits a callback into Java) and as such it has to be explicitly allowed by specifying wait4js = false. Such methods need to return void.

Implementations that execute the JavaScript synchronously may ignore this attribute.

Implementations that delay execution of JavaScript need to guarantee the order of snippets. Those that were submitted sooner, need to be executed sooner. Each snippet need to be executed in a timely manner (e.g. by a second, or so) even if there are no other calls made in the main program.

Returns:

false in case one allows asynchronous execution of the JavaScript snippet

Since:

0.7.6

Default:

true

keepAlive

public abstract boolean keepAlive

Controls garbage collection behavior of method parameters. In general JavaScript garbage collection system makes it close to impossible to find out whether an object is supposed to be still used or not. Some systems have an external hooks to find that out (like JavaFX WebView), in some systems this information is not important (like the Bck2Brwsr VM running all in JavaScript), but other execution systems just can't find that out. To prevent memory leaks on such systems and help them manage memory more effectively, those who define JavaScript interfacing methods may indicate whether the non-primitive parameters passed in should be hold only for the time of method invocation or for the whole application lifetime.

The default value is true as that is compatible with previous behavior and also prevents unwanted surprises when something garbage collects pre-maturaly. Framework developers are however encouraged to use keepAlive=false as much as possible.

Returns:

whether Java objects passed as parameters of the method should be made guaranteed to be available JavaScript even after the method invocation is over (e.g. prevent them to be garbage collected in Java until it is known they are not needed from JavaScript at all).

Since:

1.1

Default:

true