org.mozilla.geckoview

Class GeckoRuntime

Object

org.mozilla.geckoview.GeckoRuntime

All Implemented Interfaces:

Parcelable

public final class GeckoRuntime
extends Object
implements Parcelable

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	GeckoRuntime.Delegate
static interface	GeckoRuntime.ServiceWorkerDelegate

Nested classes/interfaces inherited from interface android.os.Parcelable

Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACTION_CRASHED Intent action sent to the crash handler when a crash is encountered.
static Parcelable.Creator<GeckoRuntime>	CREATOR
static String	EXTRA_CRASH_FATAL This is a key for extra data sent with ACTION_CRASHED.
static String	EXTRA_EXTRAS_PATH This is a key for extra data sent with ACTION_CRASHED.
static String	EXTRA_MINIDUMP_PATH This is a key for extra data sent with ACTION_CRASHED.

Fields inherited from interface android.os.Parcelable

CONTENTS_FILE_DESCRIPTOR, PARCELABLE_WRITE_RETURN_VALUE

Method Summary

Modifier and Type	Method and Description
void	attachTo(Context context) Attach the runtime to the given context.
void	configurationChanged(Configuration newConfig) Notify Gecko that the device configuration has changed.
static GeckoRuntime	create(Context context) Create a new runtime with default settings and attach it to the given context.
static GeckoRuntime	create(Context context, GeckoRuntimeSettings settings) Create a new runtime with the given settings and attach it to the given context.
int	describeContents()
ContentBlockingController	getContentBlockingController() Returns the ContentBlockingController for this GeckoRuntime.
static GeckoRuntime	getDefault(Context context) Get the default runtime for the given context.
GeckoRuntime.Delegate	getDelegate() Returns the current delegate, if any.
File	getProfileDir() Get the profile directory for this runtime.
GeckoRuntimeSettings	getSettings()
StorageController	getStorageController() Get the storage controller for this runtime.
RuntimeTelemetry	getTelemetry() Return the telemetry object for this runtime.
WebExtensionController	getWebExtensionController() Returns a WebExtensionController for this GeckoRuntime.
WebNotificationDelegate	getWebNotificationDelegate() Returns the current WebNotificationDelegate, if any
WebPushController	getWebPushController() Get the Web Push controller for this runtime.
void	orientationChanged() Notify Gecko that the screen orientation has changed.
void	orientationChanged(int newOrientation) Notify Gecko that the screen orientation has changed.
void	readFromParcel(Parcel source)
GeckoResult<Void>	registerWebExtension(WebExtension webExtension) Register a WebExtension that will be run with this GeckoRuntime.
void	setDelegate(GeckoRuntime.Delegate delegate) Set a delegate for receiving callbacks relevant to to this GeckoRuntime.
void	setServiceWorkerDelegate(GeckoRuntime.ServiceWorkerDelegate serviceWorkerDelegate) Sets the GeckoRuntime.ServiceWorkerDelegate to be used for Service Worker requests.
void	setWebNotificationDelegate(WebNotificationDelegate delegate) Sets the delegate to be used for handling Web Notifications.
void	shutdown() Shutdown the runtime.
GeckoResult<Void>	unregisterWebExtension(WebExtension webExtension) Unregisters this WebExtension.
void	writeToParcel(Parcel out, int flags)

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ACTION_CRASHED

public static final String ACTION_CRASHED

Intent action sent to the crash handler when a crash is encountered.

See Also:

GeckoRuntimeSettings.Builder.crashHandler(Class), Constant Field Values

EXTRA_MINIDUMP_PATH

public static final String EXTRA_MINIDUMP_PATH

This is a key for extra data sent with ACTION_CRASHED. It refers to a String with the path to a Breakpad minidump file containing information about the crash. Several crash reporters are able to ingest this in a crash report, including Sentry and Mozilla's Socorro.

Be aware, the minidump can contain personally identifiable information. Ensure you are obeying all applicable laws and policies before sending this to a remote server.

See Also:

GeckoRuntimeSettings.Builder.crashHandler(Class), Constant Field Values

EXTRA_EXTRAS_PATH

public static final String EXTRA_EXTRAS_PATH

This is a key for extra data sent with ACTION_CRASHED. It refers to a string with the path to a file containing extra metadata about the crash. The file contains key-value pairs in the form

Key=Value

Be aware, it may contain sensitive data such as the URI that was loaded at the time of the crash.

See Also:

Constant Field Values

EXTRA_CRASH_FATAL

public static final String EXTRA_CRASH_FATAL

This is a key for extra data sent with ACTION_CRASHED. The value is a boolean indicating whether or not the crash was fatal or not. If true, the main application process was affected by the crash. If false, only an internal process used by Gecko has crashed and the application may be able to recover.

See Also:

GeckoSession.ContentDelegate.onCrash(GeckoSession), Constant Field Values

CREATOR

public static final Parcelable.Creator<GeckoRuntime> CREATOR

Method Detail

getDefault

@UiThread
 @NonNull
public static GeckoRuntime getDefault(@NonNull
                                                          Context context)

Get the default runtime for the given context. This will create and initialize the runtime with the default settings. Note: Only use this for session-less apps. For regular apps, use create() instead.

Parameters:

context - An application context for the default runtime.

Returns:

The (static) default runtime for the context.

attachTo

@UiThread
public void attachTo(@NonNull
                               Context context)

Attach the runtime to the given context.

Parameters:

context - The new context to attach to.

create

@UiThread
 @NonNull
public static GeckoRuntime create(@NonNull
                                                      Context context)

Create a new runtime with default settings and attach it to the given context. Create will throw if there is already an active Gecko instance running, to prevent that, bind the runtime to the process lifetime instead of the activity lifetime.

Parameters:

context - The context of the runtime.

Returns:

An initialized runtime.

getWebExtensionController

@UiThread
 @NonNull
public WebExtensionController getWebExtensionController()

Returns a WebExtensionController for this GeckoRuntime.

Returns:

an instance of WebExtensionController.

getContentBlockingController

@UiThread
 @NonNull
public ContentBlockingController getContentBlockingController()

Returns the ContentBlockingController for this GeckoRuntime.

Returns:

An instance of ContentBlockingController.

registerWebExtension

@UiThread
 @NonNull
public GeckoResult<Void> registerWebExtension(@NonNull
                                                                  WebExtension webExtension)

Register a WebExtension that will be run with this GeckoRuntime.

At this time, WebExtensions don't have access to any UI element and cannot communicate with the application. Any UI element will be ignored.

Example:

     runtime.registerWebExtension(new WebExtension(
              "resource://android/assets/web_extensions/my_webextension/"))
           .exceptionally(ex -> {
               Log.e("MyActivity", "Could not register WebExtension", ex);
               return null;
           });

     runtime.registerWebExtension(new WebExtension(
              "file:///path/to/web_extension/my_webextension2.xpi",
              "mywebextension2@example.com"));
 

To learn more about WebExtensions refer to Mozilla/Add-ons/WebExtensions .

Parameters:

webExtension - WebExtension to register

Returns:

A GeckoResult that will complete when the WebExtension has been installed.

unregisterWebExtension

@UiThread
 @NonNull
public GeckoResult<Void> unregisterWebExtension(@NonNull
                                                                    WebExtension webExtension)

Unregisters this WebExtension. After a WebExtension is unregistered all scripts associated with it stop running.

Parameters:

webExtension - WebExtension to unregister

Returns:

A GeckoResult that will complete when the WebExtension has been unregistered.

create

@UiThread
 @NonNull
public static GeckoRuntime create(@NonNull
                                                      Context context,
                                                      @NonNull
                                                      GeckoRuntimeSettings settings)

Create a new runtime with the given settings and attach it to the given context. Create will throw if there is already an active Gecko instance running, to prevent that, bind the runtime to the process lifetime instead of the activity lifetime.

Parameters:

context - The context of the runtime.

settings - The settings for the runtime.

Returns:

An initialized runtime.

shutdown

@AnyThread
public void shutdown()

Shutdown the runtime. This will invalidate all attached sessions.

setDelegate

@UiThread
public void setDelegate(@Nullable
                                  GeckoRuntime.Delegate delegate)

Set a delegate for receiving callbacks relevant to to this GeckoRuntime.

Parameters:

delegate - an implementation of GeckoRuntime.Delegate.

getDelegate

@UiThread
 @Nullable
public GeckoRuntime.Delegate getDelegate()

Returns the current delegate, if any.

Returns:

an instance of GeckoRuntime.Delegate or null if no delegate has been set.

setServiceWorkerDelegate

@UiThread
public void setServiceWorkerDelegate(@Nullable
                                               GeckoRuntime.ServiceWorkerDelegate serviceWorkerDelegate)

Sets the GeckoRuntime.ServiceWorkerDelegate to be used for Service Worker requests.

Parameters:

serviceWorkerDelegate - An instance of GeckoRuntime.ServiceWorkerDelegate.

See Also:

Service Worker API

setWebNotificationDelegate

@UiThread
public void setWebNotificationDelegate(@Nullable
                                                 WebNotificationDelegate delegate)

Sets the delegate to be used for handling Web Notifications.

Parameters:

delegate - An instance of WebNotificationDelegate.

See Also:

Web Notifications

getWebNotificationDelegate

@UiThread
 @Nullable
public WebNotificationDelegate getWebNotificationDelegate()

Returns the current WebNotificationDelegate, if any

Returns:

an instance of WebNotificationDelegate or null if no delegate has been set

getSettings

@AnyThread
 @NonNull
public GeckoRuntimeSettings getSettings()

getTelemetry

@UiThread
 @NonNull
public RuntimeTelemetry getTelemetry()

Return the telemetry object for this runtime.

Returns:

The telemetry object.

getProfileDir

@UiThread
 @Nullable
public File getProfileDir()

Get the profile directory for this runtime. This is where Gecko stores internal data.

Returns:

Profile directory

orientationChanged

@UiThread
public void orientationChanged()

Notify Gecko that the screen orientation has changed.

configurationChanged

@UiThread
public void configurationChanged(@NonNull
                                           Configuration newConfig)

Notify Gecko that the device configuration has changed.

Parameters:

newConfig - The new Configuration object, Configuration.

orientationChanged

@UiThread
public void orientationChanged(int newOrientation)

Notify Gecko that the screen orientation has changed.

Parameters:

newOrientation - The new screen orientation, as retrieved e.g. from the current Configuration.

getStorageController

@UiThread
 @NonNull
public StorageController getStorageController()

Get the storage controller for this runtime. The storage controller can be used to manage persistent storage data accumulated by GeckoSession.

Returns:

The StorageController for this instance.

getWebPushController

@UiThread
 @NonNull
public WebPushController getWebPushController()

Get the Web Push controller for this runtime. The Web Push controller can be used to allow content to use the Web Push API.

Returns:

The WebPushController for this instance.

describeContents

@AnyThread
public int describeContents()

Specified by:

describeContents in interface Parcelable

writeToParcel

@AnyThread
public void writeToParcel(Parcel out,
                                     int flags)

Specified by:

writeToParcel in interface Parcelable

readFromParcel

@AnyThread
public void readFromParcel(@NonNull
                                      Parcel source)