From 226923465cab552ef67407d2e6517855e5d4b3a9 Mon Sep 17 00:00:00 2001
From: Makoto Onuki <omakoto@google.com>
Date: Wed, 9 Jun 2021 12:23:50 -0700
Subject: [PATCH] Update the javadoc around FGS

Fix: 182901904
Test: build
Test: m offline-sdk-docs && \
  cd /android/sc-dev/out/target/common/docs/offline-sdk/ && \
  python3 -m http.server 8000 && \
  google-chrome http://localhost:8000/
  and check the content

Change-Id: Ic9964c929c8b7d4caf1706d2398d0eb8eaddc70a
---
 core/java/android/app/Service.java     | 24 ++++++++++++++++++
 core/java/android/content/Context.java | 35 +++++++++++++++++++++++++-
 2 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/core/java/android/app/Service.java b/core/java/android/app/Service.java
index 0ab3f2f4be463..7cb1d89aa9543 100644
--- a/core/java/android/app/Service.java
+++ b/core/java/android/app/Service.java
@@ -697,6 +697,18 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
      * service element of manifest file. The value of attribute
      * {@link android.R.attr#foregroundServiceType} can be multiple flags ORed together.</p>
      *
+     * <div class="caution">
+     * <p><strong>Note:</strong>
+     * Beginning with SDK Version {@link android.os.Build.VERSION_CODES#S},
+     * apps targeting SDK Version {@link android.os.Build.VERSION_CODES#S}
+     * or higher are not allowed to start foreground services from the background.
+     * See
+     * <a href="{@docRoot}/about/versions/12/behavior-changes-12">
+     * Behavior changes: Apps targeting Android 12
+     * </a>
+     * for more details.
+     * </div>
+     *
      * @throws ForegroundServiceStartNotAllowedException
      * If the app targeting API is
      * {@link android.os.Build.VERSION_CODES#S} or later, and the service is restricted from
@@ -733,6 +745,18 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
    * {@link android.content.pm.ServiceInfo#FOREGROUND_SERVICE_TYPE_MANIFEST} to use all flags that
    * is specified in manifest attribute foregroundServiceType.</p>
    *
+   * <div class="caution">
+   * <p><strong>Note:</strong>
+   * Beginning with SDK Version {@link android.os.Build.VERSION_CODES#S},
+   * apps targeting SDK Version {@link android.os.Build.VERSION_CODES#S}
+   * or higher are not allowed to start foreground services from the background.
+   * See
+   * <a href="{@docRoot}/about/versions/12/behavior-changes-12">
+   * Behavior changes: Apps targeting Android 12
+   * </a>
+   * for more details.
+   * </div>
+   *
    * @param id The identifier for this notification as per
    * {@link NotificationManager#notify(int, Notification)
    * NotificationManager.notify(int, Notification)}; must not be 0.
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index ea0e321377c87..9c60f431b06e3 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -3182,7 +3182,8 @@ public abstract class Context {
      * <p>This function will throw {@link SecurityException} if you do not
      * have permission to start the given service.
      *
-     * <p class="note"><strong>Note:</strong> Each call to startService()
+     * <div class="caution">
+     * <p><strong>Note:</strong> Each call to startService()
      * results in significant work done by the system to manage service
      * lifecycle surrounding the processing of the intent, which can take
      * multiple milliseconds of CPU time. Due to this cost, startService()
@@ -3191,6 +3192,25 @@ public abstract class Context {
      * for high frequency calls.
      * </p>
      *
+     * Beginning with SDK Version {@link android.os.Build.VERSION_CODES#O},
+     * apps targeting SDK Version {@link android.os.Build.VERSION_CODES#O}
+     * or higher are not allowed to start background services from the background.
+     * See
+     * <a href="{@docRoot}/about/versions/oreo/background">
+     * Background Execution Limits</a>
+     * for more details.
+     *
+     * <p><strong>Note:</strong>
+     * Beginning with SDK Version {@link android.os.Build.VERSION_CODES#S},
+     * apps targeting SDK Version {@link android.os.Build.VERSION_CODES#S}
+     * or higher are not allowed to start foreground services from the background.
+     * See
+     * <a href="{@docRoot}/about/versions/12/behavior-changes-12">
+     * Behavior changes: Apps targeting Android 12
+     * </a>
+     * for more details.
+     * </div>
+     *
      * @param service Identifies the service to be started.  The Intent must be
      *      fully explicit (supplying a component name).  Additional values
      *      may be included in the Intent extras to supply arguments along with
@@ -3215,6 +3235,7 @@ public abstract class Context {
      * This excemption extends {@link IllegalStateException}, so apps can
      * use {@code catch (IllegalStateException)} to catch both.
      *
+     * @see #startForegroundService(Intent)
      * @see #stopService
      * @see #bindService
      */
@@ -3232,6 +3253,18 @@ public abstract class Context {
      * at any time, regardless of whether the app hosting the service is in a foreground
      * state.
      *
+     * <div class="caution">
+     * <p><strong>Note:</strong>
+     * Beginning with SDK Version {@link android.os.Build.VERSION_CODES#S},
+     * apps targeting SDK Version {@link android.os.Build.VERSION_CODES#S}
+     * or higher are not allowed to start foreground services from the background.
+     * See
+     * <a href="{@docRoot}/about/versions/12/behavior-changes-12">
+     * Behavior changes: Apps targeting Android 12
+     * </a>
+     * for more details.
+     * </div>
+     *
      * @param service Identifies the service to be started.  The Intent must be
      *      fully explicit (supplying a component name).  Additional values
      *      may be included in the Intent extras to supply arguments along with