JavaScriptSandbox

Artifact: androidx.javascriptengine:javascriptengine

Kotlin |Java

@ThreadSafe
public final class JavaScriptSandbox implements AutoCloseable

Sandbox that provides APIs for JavaScript evaluation in a restricted environment.

JavaScriptSandbox represents a connection to an isolated process. The isolated process is exclusive to the calling app (i.e. it doesn't share anything with, and can't be compromised by another app's isolated process).

Code that is run in a sandbox does not have any access to data belonging to the original app unless explicitly passed into it by using the methods of this class. This provides a security boundary between the calling app and the Javascript execution environment.

The calling app can have only one isolated process at a time, so only one instance of this class can be open at any given time.

It's safe to share a single JavaScriptSandbox object with multiple threads and use it from multiple threads at once. For example, JavaScriptSandbox can be stored at a global location and multiple threads can create their own JavaScriptIsolate objects from it but the JavaScriptIsolate object cannot be shared.

Summary

Constants
`static final String`	`JS_FEATURE_CONSOLE_MESSAGING = "JS_FEATURE_CONSOLE_MESSAGING"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_EVALUATE_FROM_FD = "JS_FEATURE_EVALUATE_FROM_FD"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT = "JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_ISOLATE_MAX_HEAP_SIZE = "JS_FEATURE_ISOLATE_MAX_HEAP_SIZE"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_ISOLATE_TERMINATION = "JS_FEATURE_ISOLATE_TERMINATION"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_PROMISE_RETURN = "JS_FEATURE_PROMISE_RETURN"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER = "JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER"` Feature for `isFeatureSupported`.
`static final String`	`JS_FEATURE_WASM_COMPILATION = "JS_FEATURE_WASM_COMPILATION"` Feature for `isFeatureSupported`.

Public methods
`void`	`close()` Closes the `JavaScriptSandbox` object and renders it unusable.
`static @NonNull ListenableFuture<JavaScriptSandbox>`	`createConnectedInstanceAsync(@NonNull Context context)` Asynchronously create and connect to the sandbox process.
`@NonNull JavaScriptIsolate`	`createIsolate()` Creates and returns a `JavaScriptIsolate` within which JS can be executed with default settings.
`@NonNull JavaScriptIsolate`	`createIsolate(@NonNull IsolateStartupParameters settings)` Creates and returns a `JavaScriptIsolate` within which JS can be executed with the specified settings.
`boolean`	`isFeatureSupported(@NonNull String feature)` Checks whether a given feature is supported by the JS Sandbox implementation.
`static boolean`	`isSupported()` Check if JavaScriptSandbox is supported on the system.

Protected methods
`void`	`finalize()`

Constants

JS_FEATURE_CONSOLE_MESSAGING

Added in 1.0.0-beta01

public static final String JS_FEATURE_CONSOLE_MESSAGING = "JS_FEATURE_CONSOLE_MESSAGING"

Feature for isFeatureSupported.

When this feature is present, setConsoleCallback can be used to set a JavaScriptConsoleCallback for processing console messages.

JS_FEATURE_EVALUATE_FROM_FD

Added in 1.0.0-beta01

public static final String JS_FEATURE_EVALUATE_FROM_FD = "JS_FEATURE_EVALUATE_FROM_FD"

Feature for isFeatureSupported.

When this feature is present, evaluateJavaScriptAsync and evaluateJavaScriptAsync can be used to evaluate JavaScript code of known and unknown length from file descriptors.

JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT

Added in 1.0.0-beta01

public static final String JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT = "JS_FEATURE_EVALUATE_WITHOUT_TRANSACTION_LIMIT"

Feature for isFeatureSupported.

When this feature is present, the script passed into evaluateJavaScriptAsync as well as the result/error is not limited by the Binder transaction buffer size.

JS_FEATURE_ISOLATE_MAX_HEAP_SIZE

Added in 1.0.0-beta01

public static final String JS_FEATURE_ISOLATE_MAX_HEAP_SIZE = "JS_FEATURE_ISOLATE_MAX_HEAP_SIZE"

Feature for isFeatureSupported.

When this feature is present, createIsolate can be used.

JS_FEATURE_ISOLATE_TERMINATION

Added in 1.0.0-beta01

public static final String JS_FEATURE_ISOLATE_TERMINATION = "JS_FEATURE_ISOLATE_TERMINATION"

Feature for isFeatureSupported.

When this feature is present, close terminates the currently running JS evaluation and close the isolate. If it is absent, close cannot terminate any running or queued evaluations in the background, so the isolate continues to consume resources until they complete.

Irrespective of this feature, calling close terminates all JavaScriptIsolate objects (and the isolated process) immediately and all pending evaluateJavaScriptAsync futures resolve with IsolateTerminatedException.

JS_FEATURE_PROMISE_RETURN

Added in 1.0.0-beta01

public static final String JS_FEATURE_PROMISE_RETURN = "JS_FEATURE_PROMISE_RETURN"

Feature for isFeatureSupported.

When this feature is present, JS expressions may return promises. The Future returned by evaluateJavaScriptAsync resolves to the promise's result, once the promise resolves.

JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER

Added in 1.0.0-beta01

public static final String JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER = "JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER"

Feature for isFeatureSupported. When this feature is present, provideNamedData can be used.

This also covers the JS API android.consumeNamedDataAsArrayBuffer(string).

JS_FEATURE_WASM_COMPILATION

Added in 1.0.0-beta01

public static final String JS_FEATURE_WASM_COMPILATION = "JS_FEATURE_WASM_COMPILATION"

Feature for isFeatureSupported.

This features provides additional behavior to evaluateJavaScriptAsync ()}. When this feature is present, the JS API WebAssembly.compile(ArrayBuffer) can be used.

Public methods

close

Added in 1.0.0-beta01

public void close()

Closes the JavaScriptSandbox object and renders it unusable.

The client is expected to call this method explicitly to terminate the isolated process.

Once closed, no more JavaScriptSandbox and JavaScriptIsolate method calls can be made. Closing terminates the isolated process immediately. All pending evaluations are immediately terminated. Once closed, the client may call createConnectedInstanceAsync to create another JavaScriptSandbox. You should still call close even if the sandbox has died, otherwise you will not be able to create a new one.

createConnectedInstanceAsync

Added in 1.0.0-beta01

public static @NonNull ListenableFuture<JavaScriptSandbox> createConnectedInstanceAsync(@NonNull Context context)

Asynchronously create and connect to the sandbox process.

Only one sandbox process can exist at a time. Attempting to create a new instance before the previous instance has been closed fails with an IllegalStateException.

Sandbox support should be checked using isSupported before attempting to create a sandbox via this method.

Parameters
`@NonNull Context context`	the Context for the sandbox. Use an application context if the connection is expected to outlive a single activity or service.

Returns
`@NonNull ListenableFuture<JavaScriptSandbox>`	a Future that evaluates to a connected `JavaScriptSandbox` instance or an exception if binding to service fails

createIsolate

Added in 1.0.0-beta01

public @NonNull JavaScriptIsolate createIsolate()

Creates and returns a JavaScriptIsolate within which JS can be executed with default settings.

Returns
`@NonNull JavaScriptIsolate`	a new JavaScriptIsolate

createIsolate

Added in 1.0.0-beta01

public @NonNull JavaScriptIsolate createIsolate(@NonNull IsolateStartupParameters settings)

Creates and returns a JavaScriptIsolate within which JS can be executed with the specified settings.

If the sandbox is dead, this will still return an isolate, but evaluations will fail with SandboxDeadException.

Parameters
`@NonNull IsolateStartupParameters settings`	the configuration for the isolate

Returns
`@NonNull JavaScriptIsolate`	a new JavaScriptIsolate

isFeatureSupported

Added in 1.0.0-beta01

public boolean isFeatureSupported(@NonNull String feature)

Checks whether a given feature is supported by the JS Sandbox implementation.

The sandbox implementation is provided by the version of WebView installed on the device. The app must use this method to check which library features are supported by the device's implementation before using them.

A feature check should be made prior to depending on certain features.

Parameters
`@NonNull String feature`	the feature to be checked

Returns
`boolean`	`true` if supported, `false` otherwise

isSupported

Added in 1.0.0-beta01

public static boolean isSupported()

Check if JavaScriptSandbox is supported on the system.

This method should be used to check for sandbox support before calling createConnectedInstanceAsync.

Returns
`boolean`	true if JavaScriptSandbox is supported and false otherwise

Protected methods

finalize

protected void finalize()

Throws
`java.lang.Throwable`