JavaScriptIsolate

close

public void close()

Closes the JavaScriptIsolate object and renders it unusable. Once closed, no more method calls should be made. Pending evaluations resolve with IsolateTerminatedException immediately.

If isFeatureSupported is true for JS_FEATURE_ISOLATE_TERMINATION, then any pending evaluation is immediately terminated and memory is freed. If it is false, the isolate will not get cleaned up until the pending evaluations have run to completion and will consume resources until then.

evaluateJavaScriptAsync

public @NonNull ListenableFuture<String> evaluateJavaScriptAsync(@NonNull String code)

Evaluates the given JavaScript code and returns the result. There are 3 possible behaviors based on the output of the expression:

• If the JS expression returns a JS String, then the Java Future resolves to Java String.
• If the JS expression returns a JS Promise, and if isFeatureSupported for JS_FEATURE_PROMISE_RETURN returns true, Java Future resolves to Java String once the promise resolves. If it returns false, then the Future resolves to an empty string.
• If the JS expression returns another data type, then Java Future resolves to empty Java String.

The environment uses a single JS global object for all the calls to evaluateJavaScriptAsync and provideNamedData methods. These calls are queued up and are run one at a time in sequence, using the single JS environment for the isolate. The global variables set by one evaluation are visible for later evaluations. This is similar to adding multiple <script> tags in HTML. The behavior is also similar to evaluateJavascript.

Size of the expression to be evaluated and the result are both limited by the binder transaction limit. Refer android.os.TransactionTooLargeException for more details.

provideNamedData

@RequiresFeature(name = JavaScriptSandbox.JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER, enforcement = "androidx.javascriptengine.JavaScriptSandbox#isFeatureSupported")
public boolean provideNamedData(@NonNull String name, @NonNull byte[] inputBytes)

Provides a byte array for consumption from the JavaScript environment. This method provides an efficient way to pass in data from Java into the JavaScript environment which can be referred to from JavaScript. This is more efficient than including data in the JS expression, and allows large data to be sent.

This data can be consumed in the JS environment using android.consumeNamedDataAsArrayBuffer(String) by referring to the data with the name that was used when calling this method. This is a one-time transfer and the calls should be paired.

A single name can only be used once in a particular JavaScriptIsolate. Clients can generate unique names for each call if they need to use this method multiple times. The same name should be included into the JS code.

This API can be used to pass a WASM module into the JS environment for compilation if isFeatureSupported returns true for JS_FEATURE_WASM_COMPILATION. In Java,

    jsIsolate.provideNamedData("id-1", byteArray);

In JS,

    android.consumeNamedDataAsArrayBuffer("id-1").then((value) => {
      return WebAssembly.compile(value).then((module) => {
         ...
      });
    });

The environment uses a single JS global object for all the calls to evaluateJavaScriptAsync and provideNamedData methods.

This method should only be called if isFeatureSupported returns true for JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER.

finalize

protected void finalize()