AudioFocusRequest: more docs, listener without handler

Focus listener: follow platform pattern for setter of listener
  and handler (set(listener) and set(listener, handler) methods).
More docs.

Test: cts-tradefed run cts -m CtsMediaTestCases -t android.media.cts.AudioFocusTest
Bug: 30258418

Change-Id: Ib5d1fbc3cf92821b63ffc1b4ad4cf4384bb6ff54

api/current.txt

@@ -21006,6 +21006,7 @@ package android.media {
     method public android.media.AudioFocusRequest.Builder setAcceptsDelayedFocusGain(boolean);
     method public android.media.AudioFocusRequest.Builder setAudioAttributes(android.media.AudioAttributes);
     method public android.media.AudioFocusRequest.Builder setFocusGain(int);
+    method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener);
     method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener, android.os.Handler);
     method public android.media.AudioFocusRequest.Builder setWillPauseWhenDucked(boolean);
   }

api/system-current.txt

@@ -22814,6 +22814,7 @@ package android.media {
     method public android.media.AudioFocusRequest.Builder setAudioAttributes(android.media.AudioAttributes);
     method public android.media.AudioFocusRequest.Builder setFocusGain(int);
     method public android.media.AudioFocusRequest.Builder setLocksFocus(boolean);
+    method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener);
     method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener, android.os.Handler);
     method public android.media.AudioFocusRequest.Builder setWillPauseWhenDucked(boolean);
   }

api/test-current.txt

@@ -21114,6 +21114,7 @@ package android.media {
     method public android.media.AudioFocusRequest.Builder setAcceptsDelayedFocusGain(boolean);
     method public android.media.AudioFocusRequest.Builder setAudioAttributes(android.media.AudioAttributes);
     method public android.media.AudioFocusRequest.Builder setFocusGain(int);
+    method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener);
     method public android.media.AudioFocusRequest.Builder setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener, android.os.Handler);
     method public android.media.AudioFocusRequest.Builder setWillPauseWhenDucked(boolean);
   }

media/java/android/media/AudioFocusRequest.java

@@ -29,14 +29,104 @@ import android.os.Looper;
  * request and abandon audio focus, respectively
  * with {@link AudioManager#requestAudioFocus(AudioFocusRequest)} and
  * {@link AudioManager#abandonAudioFocusRequest(AudioFocusRequest)}.
- * <p>In the context of describing audio focus, the term "ducking" is used. It describes a temporary
- * lowering of the audio level of an application in response to another application playing audio
- * concurrently. An example is during the playback of driving directions,
- * a user listening to music expects the music to "duck" during the playback of the message
- * announcing directions.
+ *
+ * <h3>What is audio focus?</h3>
+ * <p>Audio focus is a concept introduced in API 8. It is used to convey the fact that a user can
+ * only focus on a single audio stream at a time, e.g. listening to music or a podcast, but not
+ * both at the same time. In some cases, multiple audio streams can be playing at the same time,
+ * but there is only one the user would really listen to (focus on), while the other plays in
+ * the background. An example of this is driving directions being spoken while music plays at
+ * a reduced volume (a.k.a. ducking).
+ * <p>When an application requests audio focus, it expresses its intention to “own” audio focus to
+ * play audio. Let’s review the different types of focus requests, the return value after a request,
+ * and the responses to a loss.
+ * <br><b>Note:<b> applications should not play anything until granted focus.
+ *
+ * <h3>The different types of focus requests</h3>
+ * <p>There are four focus request types. A successful focus request with each will yield different
+ * behaviors by the system and the other application that previously held audio focus.
+ * <ul>
+ * <li>{@link AudioManager#AUDIOFOCUS_GAIN} expresses the fact that your application is now the
+ * sole source of audio that the user is listening to. The duration of the audio playback is
+ * unknown, and is possibly very long: after the user finishes interacting with your application,
+ * (s)he doesn’t expect another audio stream to resume. Examples of uses of this focus gain are
+ * for music playback, for a game or a video player.</li>
+ *
+ * <li>{@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT} is for a situation when you know your
+ * application is temporarily grabbing focus from the current owner, but the user expects playback
+ * to go back to where it was once your application no longer requires audio focus. An example is
+ * for playing an alarm, or during a VoIP call. The playback is known to be finite: the alarm will
+ * time-out or be dismissed, the VoIP call has a beginning and an end. When any of those events
+ * ends, and if the user was listening to music when it started, the user expects music to resume,
+ * but didn’t wish to listen to both at the same time.</li>
+ *
+ * <li>{@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK}: this focus request type is similar
+ * to {@code AUDIOFOCUS_GAIN_TRANSIENT} for the temporary aspect of the focus request, but it also
+ * expresses the fact during the time you own focus, you allow another application to keep playing
+ * at a reduced volume, “ducked”. Examples are when playing driving directions or notifications,
+ * it’s ok for music to keep playing, but not loud enough that it would prevent the directions to
+ * be hard to understand. A typical attenuation by the “ducked” application is a factor of 0.2f
+ * (or -14dB), that can for instance be applied with {@code MediaPlayer.setVolume(0.2f)} when
+ * using this class for playback.</li>
+ *
+ * <li>{@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE} is also for a temporary request,
+ * but also expresses that your application expects the device to not play anything else. This is
+ * typically used if you are doing audio recording or speech recognition, and don’t want for
+ * examples notifications to be played by the system during that time.</li>
+ * </ul>
+ *
+ * <p>An {@code AudioFocusRequest} instance always contains one of the four types of requests
+ * explained above. It is passed when building an {@code AudioFocusRequest} instance with its
+ * builder in the {@link Builder} constructor {@link Builder#Builder(int)}, or with
+ * {@link Builder#setFocusGain(int)} after copying an existing instance with
+ * {@link Builder#Builder(AudioFocusRequest)}.
+ *
+ * <h3>Qualifying your focus request</h3>
+ * <h4>Use case requiring a focus request</h4>
+ * <p>Any focus request is qualified by the {@link AudioAttributes}
+ * (see {@link Builder#setAudioAttributes(AudioAttributes)}) that describe the audio use case that
+ * will follow the request (once it's successful or granted). It is recommended to use the
+ * same {@code AudioAttributes} for the request as the attributes you are using for audio/media
+ * playback.
+ * <br>If no attributes are set, default attributes of {@link AudioAttributes#USAGE_MEDIA} are used.
+ *
+ * <h4>Delayed focus</h4>
+ * <p>Audio focus can be "locked" by the system for a number of reasons: during a phone call, when
+ * the car to which the device is connected plays an emergency message... To support these
+ * situations, the application can request to be notified when its request is fulfilled, by flagging
+ * its request as accepting delayed focus, with {@link Builder#setAcceptsDelayedFocusGain(boolean)}.
+ * <br>If focus is requested while being locked by the system,
+ * {@link AudioManager#requestAudioFocus(AudioFocusRequest)} will return
+ * {@link AudioManager#AUDIOFOCUS_REQUEST_DELAYED}. When focus isn't locked anymore, the focus
+ * listener set with {@link Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener)}
+ * or with {@link Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener, Handler)} will
+ * be called to notify the application it now owns audio focus.
+ *
+ * <h4>Pausing vs ducking</h4>
+ * <p>When an application requested audio focus with
+ * {@link AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK}, the system will duck the current focus
+ * owner. Note that this behavior is <b>new for Android O<b>, whereas applications targeting SDK
+ * up to API 25, applications had to implement the ducking themselves when they received a focus
+ * loss of {@link AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK}.
+ * <br>But ducking is not always the behavior expected by the user. A typical example is when the
+ * device plays driving directions while the user is listening to an audio book or podcast, and
+ * expects the audio playback to pause, instead of duck, as it is hard to understand a navigation
+ * prompt and spoken content at the same time. Therefore the system will not automatically duck
+ * when it detects it would be ducking spoken content: such content is detected when the
+ * {@code AudioAttributes} of the player are qualified by
+ * {@link AudioAttributes#CONTENT_TYPE_SPEECH}. Refer for instance to
+ * {@link AudioAttributes.Builder#setContentType(int)} and
+ * {@link MediaPlayer#setAudioAttributes(AudioAttributes)} if you are writing a media playback
+ * application for audio book, podcasts... Since the system will not automatically duck applications
+ * that play speech, it calls their focus listener instead to notify them of
+ * {@link AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK}, so they can pause instead. Note that
+ * this behavior is independent of the use of {@code AudioFocusRequest}, but tied to the use
+ * of {@code AudioAttributes}.
+ * <p>If your application requires pausing instead of ducking for any other reason than playing
+ * speech, you can also declare so with {@link Builder#setWillPauseWhenDucked(boolean)}, which will
+ * cause the system to call your focus listener instead of automatically ducking.
+ *
  */
-// TODO use this class to provide more documentation about audio focus and the new behaviors
-//      describe up to N, and after.
 public final class AudioFocusRequest {
 
     // default attributes for the request when not specified
@@ -245,6 +335,27 @@ public final class AudioFocusRequest {
             return this;
         }
 
+        /**
+         * Sets the listener called when audio focus changes after being requested with
+         *   {@link AudioManager#requestAudioFocus(AudioFocusRequest)}, and until being abandoned
+         *   with {@link AudioManager#abandonAudioFocusRequest(AudioFocusRequest)}.
+         *   Note that only focus changes (gains and losses) affecting the focus owner are reported,
+         *   not gains and losses of other focus requesters in the system.<br>
+         *   Notifications are delivered on the main {@link Looper}.
+         * @param listener the listener receiving the focus change notifications.
+         * @return this {@code Builder} instance.
+         * @throws NullPointerException thrown when a null focus listener is used.
+         */
+        public @NonNull Builder setOnAudioFocusChangeListener(
+                @NonNull OnAudioFocusChangeListener listener) {
+            if (listener == null) {
+                throw new NullPointerException("Illegal null focus listener");
+            }
+            mFocusListener = listener;
+            mListenerHandler = null;
+            return this;
+        }
+
         /**
          * Sets the listener called when audio focus changes after being requested with
          *   {@link AudioManager#requestAudioFocus(AudioFocusRequest)}, and until being abandoned
@@ -253,17 +364,14 @@ public final class AudioFocusRequest {
          *   not gains and losses of other focus requesters in the system.
          * @param listener the listener receiving the focus change notifications.
          * @param handler the {@link Handler} for the thread on which to execute
-         *   the notifications. If {@code null}, the {@code Handler} associated with the main
-         *   {@link Looper} will be used.
+         *   the notifications.
          * @return this {@code Builder} instance.
-         * @throws IllegalArgumentException thrown when a non-null handler is used with a null
-         *   listener.
+         * @throws NullPointerException thrown when a null focus listener or handler is used.
          */
         public @NonNull Builder setOnAudioFocusChangeListener(
-                @Nullable OnAudioFocusChangeListener listener, @Nullable Handler handler) {
-            if (listener == null && handler != null) {
-                throw new IllegalArgumentException(
-                        "Illegal non-null handler without a focus listener");
+                @NonNull OnAudioFocusChangeListener listener, @NonNull Handler handler) {
+            if (listener == null || handler == null) {
+                throw new NullPointerException("Illegal null focus listener or handler");
             }
             mFocusListener = listener;
             mListenerHandler = handler;
@@ -272,7 +380,7 @@ public final class AudioFocusRequest {
 
         /**
          * Sets the {@link AudioAttributes} to be associated with the focus request, and which
-         * describe the use case describing why focus is requested.
+         * describe the use case for which focus is requested.
          * As the focus requests typically precede audio playback, this information is used on
          * certain platforms to declare the subsequent playback use case. It is therefore good
          * practice to use in this method the same {@code AudioAttributes} as used for