Merge "[WebView] Update ServiceWorker related documentation." into nyc-dev

core/java/android/webkit/ServiceWorkerClient.java

@@ -16,7 +16,10 @@
 
 package android.webkit;
 
-
+/**
+ * Base class for clients to capture Service Worker related callbacks,
+ * see {@link ServiceWorkerController} for usage example.
+ */
 public class ServiceWorkerClient {
 
     /**
@@ -32,7 +35,7 @@ public class ServiceWorkerClient {
      * @return A {@link android.webkit.WebResourceResponse} containing the
      *         response information or null if the WebView should load the
      *         resource itself.
-     * @see {@link WebViewClient#shouldInterceptRequest()}
+     * @see WebViewClient#shouldInterceptRequest(WebView, WebResourceRequest)
      */
     public WebResourceResponse shouldInterceptRequest(WebResourceRequest request) {
         return null;

core/java/android/webkit/ServiceWorkerController.java

@@ -21,6 +21,19 @@ import android.annotation.Nullable;
 
 /**
  * Manages Service Workers used by WebView.
+ *
+ * <p>Example usage:
+ * <pre class="prettyprint">
+ * ServiceWorkerController swController = ServiceWorkerController.getInstance();
+ * swController.setServiceWorkerClient(new ServiceWorkerClient() {
+ *   {@literal @}Override
+ *   public WebResourceResponse shouldInterceptRequest(WebResourceRequest request) {
+ *     // Capture request here and generate response or allow pass-through
+ *     // by returning null.
+ *     return null;
+ *   }
+ * });
+ * </pre></p>
  */
 public abstract class ServiceWorkerController {
 
@@ -29,7 +42,7 @@ public abstract class ServiceWorkerController {
      * only one ServiceWorkerController instance for all WebView instances,
      * however this restriction may be relaxed in the future.
      *
-     * @return The default ServiceWorkerController instance.
+     * @return the default ServiceWorkerController instance
      */
      @NonNull
      public static ServiceWorkerController getInstance() {
@@ -39,13 +52,17 @@ public abstract class ServiceWorkerController {
     /**
      * Gets the settings for all service workers.
      *
-     * @return The current ServiceWorkerWebSettings
+     * @return the current ServiceWorkerWebSettings
      */
     @NonNull
     public abstract ServiceWorkerWebSettings getServiceWorkerWebSettings();
 
     /**
      * Sets the client to capture service worker related callbacks.
+     *
+     * A {@link ServiceWorkerClient} should be set before any service workers are
+     * active, e.g. a safe place is before any WebView instances are created or
+     * pages loaded.
      */
     public abstract void setServiceWorkerClient(@Nullable ServiceWorkerClient client);
 }

core/java/android/webkit/ServiceWorkerWebSettings.java

@@ -30,9 +30,12 @@ public abstract class ServiceWorkerWebSettings {
     /**
      * Overrides the way the cache is used, see {@link WebSettings#setCacheMode}.
      *
-     * @param mode the mode to use
+     * @param mode the mode to use. One of {@link WebSettings#LOAD_DEFAULT},
+     *     {@link WebSettings#LOAD_CACHE_ELSE_NETWORK}, {@link WebSettings#LOAD_NO_CACHE}
+     *     or {@link WebSettings#LOAD_CACHE_ONLY}. The default value is
+     *     {@link WebSettings#LOAD_DEFAULT}.
      */
-    public abstract void setCacheMode(int mode);
+    public abstract void setCacheMode(@WebSettings.CacheMode int mode);
 
     /**
      * Gets the current setting for overriding the cache mode.
@@ -40,6 +43,7 @@ public abstract class ServiceWorkerWebSettings {
      * @return the current setting for overriding the cache mode
      * @see #setCacheMode
      */
+    @WebSettings.CacheMode
     public abstract int getCacheMode();
 
     /**
@@ -69,11 +73,10 @@ public abstract class ServiceWorkerWebSettings {
     public abstract boolean getAllowFileAccess();
 
     /**
-     * Sets whether the Service Workers should not load resources from the network,
+     * Sets whether Service Workers should not load resources from the network,
      * see {@link WebSettings#setBlockNetworkLoads}.
      *
-     * @param flag whether the Service Workers should not load any resources from the
-     *             network
+     * @param flag true means block network loads by the Service Workers
      */
     public abstract void setBlockNetworkLoads(boolean flag);
 

core/java/android/webkit/WebSettings.java

@@ -119,6 +119,11 @@ public abstract class WebSettings {
         int value;
     }
 
+    /** @hide */
+    @IntDef({LOAD_DEFAULT, LOAD_NORMAL, LOAD_CACHE_ELSE_NETWORK, LOAD_NO_CACHE, LOAD_CACHE_ONLY})
+    @Retention(RetentionPolicy.SOURCE)
+    public @interface CacheMode {}
+
     /**
      * Default cache usage mode. If the navigation type doesn't impose any
      * specific behavior, use cached resources when they are available
@@ -876,8 +881,7 @@ public abstract class WebSettings {
      * {@link android.Manifest.permission#INTERNET} permission, otherwise it is
      * true.
      *
-     * @param flag whether the WebView should not load any resources from the
-     *             network
+     * @param flag true means block network loads by the WebView
      * @see android.webkit.WebView#reload
      */
     public abstract void setBlockNetworkLoads(boolean flag);
@@ -1275,7 +1279,7 @@ public abstract class WebSettings {
      *
      * @param mode the mode to use
      */
-    public abstract void setCacheMode(int mode);
+    public abstract void setCacheMode(@CacheMode int mode);
 
     /**
      * Gets the current setting for overriding the cache mode.
@@ -1283,6 +1287,7 @@ public abstract class WebSettings {
      * @return the current setting for overriding the cache mode
      * @see #setCacheMode
      */
+    @CacheMode
     public abstract int getCacheMode();
 
     /**