ProcessGlobalConfig

public class ProcessGlobalConfig


Process Global Configuration for WebView. WebView has some process-global configuration parameters that cannot be changed once WebView has been loaded. This class allows apps to set these parameters.

If it is used, the configuration should be set and apply should be called prior to loading WebView into the calling process. Most of the methods in android.webkit and androidx.webkit packages load WebView, so the configuration should be applied before calling any of these methods.

The following code configures the data directory suffix that WebView uses and then applies the configuration. WebView uses this configuration when it is loaded.

ProcessGlobalConfig config = new ProcessGlobalConfig();
config.setDataDirectorySuffix("random_suffix")
ProcessGlobalConfig.apply(config);

apply can only be called once.

Only a single thread should access this class at a given time.

The configuration should be set up as early as possible during application startup, to ensure that it happens before any other thread can call a method that loads WebView.

Summary

Public constructors

Creates a ProcessGlobalConfig object.

Public methods

static void

Applies the configuration to be used by WebView on loading.

@NonNull ProcessGlobalConfig
@RequiresFeature(name = WebViewFeature.STARTUP_FEATURE_SET_DATA_DIRECTORY_SUFFIX, enforcement = "androidx.webkit.WebViewFeature#isConfigFeatureSupported(String, Context)")
setDataDirectorySuffix(@NonNull Context context, @NonNull String suffix)

Define the directory used to store WebView data for the current process.

@NonNull ProcessGlobalConfig
@RequiresFeature(name = WebViewFeature.STARTUP_FEATURE_SET_DIRECTORY_BASE_PATHS, enforcement = "androidx.webkit.WebViewFeature#isConfigFeatureSupported(String, Context)")
setDirectoryBasePaths(
    @NonNull Context context,
    @NonNull File dataDirectoryBasePath,
    @NonNull File cacheDirectoryBasePath
)

Set the base directories that WebView will use for the current process.

Public constructors

ProcessGlobalConfig

Added in 1.6.0
public ProcessGlobalConfig()

Creates a ProcessGlobalConfig object.

Public methods

apply

Added in 1.6.0
public static void apply(@NonNull ProcessGlobalConfig config)

Applies the configuration to be used by WebView on loading. This method can only be called once.

Calling this method will not cause WebView to be loaded and will not block the calling thread.

Parameters
@NonNull ProcessGlobalConfig config

the config to be applied

Throws
java.lang.IllegalStateException

if WebView has already been initialized in the current process or if this method was called before

setDataDirectorySuffix

Added in 1.6.0
@RequiresFeature(name = WebViewFeature.STARTUP_FEATURE_SET_DATA_DIRECTORY_SUFFIX, enforcement = "androidx.webkit.WebViewFeature#isConfigFeatureSupported(String, Context)")
public @NonNull ProcessGlobalConfig setDataDirectorySuffix(@NonNull Context context, @NonNull String suffix)

Define the directory used to store WebView data for the current process. The provided suffix will be used when constructing data and cache directory paths. If this API is not called, no suffix will be used. Each directory can be used by only one process in the application. If more than one process in an app wishes to use WebView, only one process can use the default directory, and other processes must call this API to define a unique suffix.

This means that different processes in the same application cannot directly share WebView-related data, since the data directories must be distinct. Applications that use this API may have to explicitly pass data between processes. For example, login cookies may have to be copied from one process's cookie jar to the other using android.webkit.CookieManager if both processes' WebViews are intended to be logged in.

Most applications should simply ensure that all components of the app that rely on WebView are in the same process, to avoid needing multiple data directories. The disableWebView method can be used to ensure that the other processes do not use WebView by accident in this case.

This is a compatibility method for setDataDirectorySuffix

Parameters
@NonNull Context context

a Context to access application assets This value cannot be null.

@NonNull String suffix

The directory name suffix to be used for the current process. Must not contain a path separator and should not be empty.

Returns
@NonNull ProcessGlobalConfig

the ProcessGlobalConfig that has the value set to allow chaining of setters

Throws
java.lang.UnsupportedOperationException

if underlying WebView does not support the use of the method.

java.lang.IllegalArgumentException

if the suffix contains a path separator or is empty.

setDirectoryBasePaths

Added in 1.7.0
@RequiresFeature(name = WebViewFeature.STARTUP_FEATURE_SET_DIRECTORY_BASE_PATHS, enforcement = "androidx.webkit.WebViewFeature#isConfigFeatureSupported(String, Context)")
public @NonNull ProcessGlobalConfig setDirectoryBasePaths(
    @NonNull Context context,
    @NonNull File dataDirectoryBasePath,
    @NonNull File cacheDirectoryBasePath
)

Set the base directories that WebView will use for the current process. If this method is not used, WebView uses the default base paths defined by the Android framework.

WebView will create and use a subdirectory under each of the base paths supplied to this method.

This method can be used in conjunction with setDataDirectorySuffix. A different subdirectory is created for each suffix.

The base paths must be absolute paths.

The data directory must not be under the Android cache directory, as Android may delete cache files when disk space is low and WebView may not function properly if this occurs. Refer to this link.

If the specified directories already exist then they must be readable and writable by the current process. If they do not already exist, WebView will attempt to create them during initialization, along with any missing parent directories. In such a case, the directory in which WebView creates missing directories must be readable and writable by the current process.

Parameters
@NonNull Context context

a Context to access application assets. This value cannot be null.

@NonNull File dataDirectoryBasePath

the absolute base path for the WebView data directory.

@NonNull File cacheDirectoryBasePath

the absolute base path for the WebView cache directory.

Returns
@NonNull ProcessGlobalConfig

the ProcessGlobalConfig that has the value set to allow chaining of setters

Throws
java.lang.UnsupportedOperationException

if underlying WebView does not support the use of the method.

java.lang.IllegalArgumentException

if the paths supplied do not have the right permissions