Merge "Update the javadoc around FGS" into sc-dev

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.

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