JavaScriptSandbox


@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.

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.

A JavaScriptSandbox is normally obtained via createSharedSandboxAsync or createDedicatedSandboxAsync.

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_MESSAGE_PORTS = "JS_FEATURE_MESSAGE_PORTS"

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

Closes the JavaScriptSandbox object and renders it unusable.

static @NonNull ListenableFuture<JavaScriptSandbox>

Asynchronously create and connect to a legacy sandbox process.

static @NonNull ListenableFuture<JavaScriptSandbox>

Asynchronously create and connect to a dedicated sandbox process.

@NonNull JavaScriptIsolate

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

@NonNull JavaScriptIsolate

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

static @NonNull ListenableFuture<JavaScriptSandbox>

Asynchronously connect to a shared sandbox process, creating it if needed.

boolean

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

boolean

Returns true if this JavaScriptSandbox is (or was) using a shared service process.

static boolean

Check if JavaScriptSandbox is supported on the system.

Protected methods

void

Constants

JS_FEATURE_CONSOLE_MESSAGING

Added in 1.0.0
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
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
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
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
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 closes 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 for a legacy or dedicated sandbox terminates all JavaScriptIsolate objects (and the isolated process) immediately and all pending evaluateJavaScriptAsync futures resolve with IsolateTerminatedException. Shared sandboxes may not terminate isolates as reliably if there are other shared sandboxes in use, but will attempt to terminate their isolates if possible.

JS_FEATURE_MESSAGE_PORTS

Added in 1.1.0
public static final String JS_FEATURE_MESSAGE_PORTS = "JS_FEATURE_MESSAGE_PORTS"

Feature for isFeatureSupported

When this feature is present, message ports can be sent to JavaScript isolates using createMessageChannel and be used to send and receive messages between the embedder and the JavaScript isolate.

JS_FEATURE_PROMISE_RETURN

Added in 1.0.0
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
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
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
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 unless stated by the method documentation.

For legacy and dedicated sandboxes, closing terminates the isolated process immediately and all pending evaluations are immediately terminated.

For shared sandboxes, the process is only terminated once all shared JavaScriptSandbox instances are closed. Note that isolates associated with this JavaScriptSandbox will still become unusable once the sandbox is closed.

For legacy sandboxes, 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 legacy sandbox.

createConnectedInstanceAsync

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

Asynchronously create and connect to a legacy sandbox process.

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

Using this method is discouraged. Prefer to use createSharedSandboxAsync or createDedicatedSandboxAsync instead, as these allow the creation of multiple concurrent JavaScriptSandbox instances.

You should only fall back to using createConnectedInstanceAsync if you are sure that your code is (and will always be) the only possible caller of this method. If you cannot guarantee this, you should either accept not being able to run JavaScript, or fall back to using an alternative such as evaluating scripts via a android.webkit.WebView, but be aware of the significant differences between JavaScriptEngine and WebView JavaScript environments and their security/isolation properties.

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 the service fails.

createDedicatedSandboxAsync

Added in 1.2.0-alpha01
@RequiresApi(value = Build.VERSION_CODES.Q)
public static @NonNull ListenableFuture<JavaScriptSandbox> createDedicatedSandboxAsync(@NonNull Context context)

Asynchronously create and connect to a dedicated sandbox process.

Each call to this method resolves to a distinct JavaScriptSandbox instance with a dedicated sandbox process.

This offers a higher level of security and stability compared to shared sandboxes, but may incur additional startup overhead and consume additional system resources. Generally, you should prefer using a shared sandbox unless you require the stronger isolation properties of a dedicated sandbox.

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 the service fails.

createIsolate

Added in 1.0.0
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
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

createSharedSandboxAsync

Added in 1.2.0-alpha01
@RequiresApi(value = Build.VERSION_CODES.Q)
public static @NonNull ListenableFuture<JavaScriptSandbox> createSharedSandboxAsync(@NonNull Context context)

Asynchronously connect to a shared sandbox process, creating it if needed.

Each call to this method resolves to a distinct JavaScriptSandbox instance, but a common underlying sandbox service process will be used. The lifecycle of the shared process is managed automatically.

For most use cases, using a shared sandbox is preferred over using a dedicated sandbox, as shared sandboxes use fewer system resources and avoid repeated startup overheads.

Note that this does not provide any process-level isolation between the returned shared sandboxes. This may result in decreased stability and security compared to using dedicated sandboxes.

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 the service fails.

isFeatureSupported

Added in 1.0.0
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

isShared

Added in 1.2.0-alpha01
public boolean isShared()

Returns true if this JavaScriptSandbox is (or was) using a shared service process.

This may be called even after the sandbox has been closed.

isSupported

Added in 1.0.0
public static boolean isSupported()

Check if JavaScriptSandbox is supported on the system.

This method should be used to check for sandbox support before attempting to create a sandbox.

Returns
boolean

true if JavaScriptSandbox is supported and false otherwise.

Protected methods

finalize

protected void finalize()