JavaScriptSandbox
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 only have only one isolated process at a time, so only one instance of this object can exist at a 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_ISOLATE_MAX_HEAP_SIZE = "JS_FEATURE_ISOLATE_MAX_HEAP_SIZE"Feature for |
static final String |
JS_FEATURE_ISOLATE_TERMINATION = "JS_FEATURE_ISOLATE_TERMINATION"Feature for |
static final String |
JS_FEATURE_PROMISE_RETURN = "JS_FEATURE_PROMISE_RETURN"Feature for |
static final String |
JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER = "JS_FEATURE_PROVIDE_CONSUME_ARRAY_BUFFER"Feature for |
static final String |
JS_FEATURE_WASM_COMPILATION = "JS_FEATURE_WASM_COMPILATION"Feature for |
Public methods |
|
|---|---|
void |
close()Closes the |
static @NonNull ListenableFuture<JavaScriptSandbox> |
createConnectedInstanceAsync(@NonNull Context context)Asynchronously create and connect to the sandbox process. |
@NonNull JavaScriptIsolate |
Creates and returns an |
@NonNull JavaScriptIsolate |
createIsolate(@NonNull IsolateStartupParameters settings)Creates and returns an |
boolean |
isFeatureSupported(@NonNull String feature)Checks whether a given feature is supported by the JS Sandbox implementation. |
static boolean |
Check if JavaScriptSandbox is supported on the system. |
Protected methods |
|
|---|---|
void |
finalize() |
Constants
JS_FEATURE_ISOLATE_MAX_HEAP_SIZE
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
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 .
JS_FEATURE_PROMISE_RETURN
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
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
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
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.
createConnectedInstanceAsync
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 |
When the context is destroyed, the connection is closed. Use an application context if the connection is expected to outlive a single activity or service. |
| Returns | |
|---|---|
@NonNull ListenableFuture<JavaScriptSandbox> |
Future that evaluates to a connected |
createIsolate
public @NonNull JavaScriptIsolate createIsolate()
Creates and returns an JavaScriptIsolate within which JS can be executed with default settings.
createIsolate
public @NonNull JavaScriptIsolate createIsolate(@NonNull IsolateStartupParameters settings)
Creates and returns an JavaScriptIsolate within which JS can be executed with the specified settings.
| Parameters | |
|---|---|
@NonNull IsolateStartupParameters settings |
configuration used to set up the isolate |
isFeatureSupported
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.
| Returns | |
|---|---|
boolean |
|
isSupported
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. |