From b2da61f70bfb9b1fea13db63fd2ce6dac92dc3ad Mon Sep 17 00:00:00 2001 From: olly Date: Tue, 1 Aug 2017 07:50:12 -0700 Subject: [PATCH] Clean up MediaSessionExt documentation ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=163828712 --- .../DefaultPlaybackController.java | 42 +++--- .../mediasession/MediaSessionConnector.java | 126 ++++++++---------- .../RepeatModeActionProvider.java | 19 +-- .../mediasession/TimelineQueueNavigator.java | 25 ++-- .../exoplayer2/ui/PlaybackControlView.java | 16 ++- 5 files changed, 112 insertions(+), 116 deletions(-) diff --git a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/DefaultPlaybackController.java b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/DefaultPlaybackController.java index 231c1f1ea5..c3586b29e6 100644 --- a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/DefaultPlaybackController.java +++ b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/DefaultPlaybackController.java @@ -21,40 +21,50 @@ import com.google.android.exoplayer2.C; import com.google.android.exoplayer2.Player; /** - * A default implementation of the {@link MediaSessionConnector.PlaybackController}. You can safely - * override any method for instance to intercept calls for a given action. + * A default implementation of {@link MediaSessionConnector.PlaybackController}. + *

+ * Methods can be safely overridden by subclasses to intercept calls for given actions. */ public class DefaultPlaybackController implements MediaSessionConnector.PlaybackController { + /** + * The default fast forward increment, in milliseconds. + */ + public static final int DEFAULT_FAST_FORWARD_MS = 15000; + /** + * The default rewind increment, in milliseconds. + */ + public static final int DEFAULT_REWIND_MS = 5000; + private static final long BASE_ACTIONS = PlaybackStateCompat.ACTION_PLAY_PAUSE | PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE | PlaybackStateCompat.ACTION_STOP; - protected final long fastForwardIncrementMs; protected final long rewindIncrementMs; + protected final long fastForwardIncrementMs; /** - * Creates a new {@link DefaultPlaybackController}. This is equivalent to calling - * {@code DefaultPlaybackController(15000L, 5000L)}. + * Creates a new instance. + *

+ * Equivalent to {@code DefaultPlaybackController( + * DefaultPlaybackController.DEFAULT_REWIND_MS, + * DefaultPlaybackController.DEFAULT_FAST_FORWARD_MS)}. */ public DefaultPlaybackController() { - this(15000L, 5000L); + this(DEFAULT_REWIND_MS, DEFAULT_FAST_FORWARD_MS); } /** - * Creates a new {@link DefaultPlaybackController} and sets the fast forward and rewind increments - * in milliseconds. + * Creates a new instance with the given fast forward and rewind increments. * - * @param fastForwardIncrementMs A positive value will cause the - * {@link PlaybackStateCompat#ACTION_FAST_FORWARD} playback action to be added. A zero or a - * negative value will cause it to be removed. - * @param rewindIncrementMs A positive value will cause the - * {@link PlaybackStateCompat#ACTION_REWIND} playback action to be added. A zero or a - * negative value will cause it to be removed. + * @param rewindIncrementMs The rewind increment in milliseconds. A zero or negative value will + * cause the rewind action to be disabled. + * @param fastForwardIncrementMs The fast forward increment in milliseconds. A zero or negative + * value will cause the fast forward action to be removed. */ - public DefaultPlaybackController(long fastForwardIncrementMs, long rewindIncrementMs) { - this.fastForwardIncrementMs = fastForwardIncrementMs; + public DefaultPlaybackController(long rewindIncrementMs, long fastForwardIncrementMs) { this.rewindIncrementMs = rewindIncrementMs; + this.fastForwardIncrementMs = fastForwardIncrementMs; } @Override diff --git a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/MediaSessionConnector.java b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/MediaSessionConnector.java index a300acfffa..0e839b8083 100644 --- a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/MediaSessionConnector.java +++ b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/MediaSessionConnector.java @@ -44,30 +44,27 @@ import java.util.List; import java.util.Map; /** - * Mediates between a {@link MediaSessionCompat} and an {@link Player} instance set with - * {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}. + * Connects a {@link MediaSessionCompat} to a {@link Player}. *

- * The {@code MediaSessionConnector} listens for media actions sent by a media controller and - * realizes these actions by calling appropriate ExoPlayer methods. Further, the state of ExoPlayer - * will be synced automatically with the {@link PlaybackStateCompat} of the media session to - * broadcast state transitions to clients. You can optionally extend this behaviour by providing - * various collaborators. - *

- * Media actions to initiate media playback ({@code PlaybackStateCompat#ACTION_PREPARE_*} and - * {@code PlaybackStateCompat#ACTION_PLAY_*} need to be handled by a {@link PlaybackPreparer} which - * build a {@link com.google.android.exoplayer2.source.MediaSource} to prepare ExoPlayer. Deploy - * your preparer by calling {@link #setPlaybackPreparer(PlaybackPreparer)}. - *

- * To support a media session queue and navigation within this queue, you can set a - * {@link QueueNavigator} to maintain the queue yourself and implement queue navigation commands - * (like 'skip to next') sent by controllers. It's recommended to use the - * {@link TimelineQueueNavigator} to allow users navigating the windows of the ExoPlayer timeline. - *

- * If you want to allow media controllers to manipulate the queue, implement a {@link QueueEditor} - * and deploy it with {@link #setQueueEditor(QueueEditor)}. - *

- * Set an {@link ErrorMessageProvider} to provide an error code and a human readable error message - * to be broadcast to controllers. + * The connector listens for actions sent by the media session's controller and implements these + * actions by calling appropriate ExoPlayer methods. The playback state of the media session is + * automatically synced with the player. The connector can also be optionally extended by providing + * various collaborators: + *

*/ public final class MediaSessionConnector { @@ -78,12 +75,7 @@ public final class MediaSessionConnector { public static final String EXTRAS_PITCH = "EXO_PITCH"; /** - * Interface to which media controller commands regarding preparing playback for a given media - * clip are delegated to. - *

- * Normally preparing playback includes preparing the player with a - * {@link com.google.android.exoplayer2.source.MediaSource} and setting up the media session queue - * with a corresponding list of queue items. + * Interface to which playback preparation actions are delegated. */ public interface PlaybackPreparer { @@ -131,7 +123,7 @@ public final class MediaSessionConnector { } /** - * Controller to handle playback actions. + * Interface to which playback actions are delegated. */ public interface PlaybackController { @@ -178,8 +170,8 @@ public final class MediaSessionConnector { } /** - * Navigator to handle queue navigation actions and maintain the media session queue with - * {#link MediaSessionCompat#setQueue(List)} to provide the active queue item to the connector. + * Handles queue navigation actions, and updates the media session queue by calling + * {@code MediaSessionCompat.setQueue()}. */ public interface QueueNavigator { @@ -211,7 +203,7 @@ public final class MediaSessionConnector { */ void onCurrentWindowIndexChanged(Player player); /** - * Gets the id of the currently active queue item or + * Gets the id of the currently active queue item, or * {@link MediaSessionCompat.QueueItem#UNKNOWN_ID} if the active item is unknown. *

* To let the connector publish metadata for the active queue item, the queue item with the @@ -241,7 +233,7 @@ public final class MediaSessionConnector { } /** - * Editor to manipulate the queue. + * Handles media session queue edits. */ public interface QueueEditor { @@ -302,12 +294,12 @@ public final class MediaSessionConnector { } /** - * Provides an user readable error code and a message for {@link ExoPlaybackException}s. + * Converts an exception into an error code and a user readable error message. */ public interface ErrorMessageProvider { /** - * Returns a pair of an error code and a user readable error message for a given - * {@link ExoPlaybackException}. + * Returns a pair consisting of an error code and a user readable error message for a given + * exception. */ Pair getErrorMessage(ExoPlaybackException playbackException); } @@ -316,6 +308,7 @@ public final class MediaSessionConnector { * The wrapped {@link MediaSessionCompat}. */ public final MediaSessionCompat mediaSession; + private final MediaControllerCompat mediaController; private final Handler handler; private final boolean doMaintainMetadata; @@ -334,11 +327,10 @@ public final class MediaSessionConnector { private ExoPlaybackException playbackException; /** - * Creates a {@code MediaSessionConnector}. This is equivalent to calling - * {@code #MediaSessionConnector(mediaSession, new DefaultPlaybackController)}. + * Creates an instance. Must be called on the same thread that is used to construct the player + * instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}. *

- * Constructing the {@link MediaSessionConnector} needs to be done on the same thread as - * constructing the player instance. + * Equivalent to {@code MediaSessionConnector(mediaSession, new DefaultPlaybackController())}. * * @param mediaSession The {@link MediaSessionCompat} to connect to. */ @@ -347,14 +339,13 @@ public final class MediaSessionConnector { } /** - * Creates a {@code MediaSessionConnector}. This is equivalent to calling - * {@code #MediaSessionConnector(mediaSession, playbackController, true)}. + * Creates an instance. Must be called on the same thread that is used to construct the player + * instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}. *

- * Constructing the {@link MediaSessionConnector} needs to be done on the same thread as - * constructing the player instance. + * Equivalent to {@code MediaSessionConnector(mediaSession, playbackController, true)}. * * @param mediaSession The {@link MediaSessionCompat} to connect to. - * @param playbackController The {@link PlaybackController}. + * @param playbackController A {@link PlaybackController} for handling playback actions. */ public MediaSessionConnector(MediaSessionCompat mediaSession, PlaybackController playbackController) { @@ -362,19 +353,14 @@ public final class MediaSessionConnector { } /** - * Creates a {@code MediaSessionConnector} with {@link CustomActionProvider}s. - *

- * If you choose to pass {@code false} for {@code doMaintainMetadata} you need to maintain the - * metadata of the media session yourself (provide at least the duration to allow clients to show - * a progress bar). - *

- * Constructing the {@link MediaSessionConnector} needs to be done on the same thread as - * constructing the player instance. + * Creates an instance. Must be called on the same thread that is used to construct the player + * instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}. * * @param mediaSession The {@link MediaSessionCompat} to connect to. - * @param playbackController The {@link PlaybackController}. - * @param doMaintainMetadata Sets whether the connector should maintain the metadata of the - * session. + * @param playbackController A {@link PlaybackController} for handling playback actions. + * @param doMaintainMetadata Whether the connector should maintain the metadata of the session. If + * {@code false}, you need to maintain the metadata of the media session yourself (provide at + * least the duration to allow clients to show a progress bar). */ public MediaSessionConnector(MediaSessionCompat mediaSession, PlaybackController playbackController, boolean doMaintainMetadata) { @@ -392,17 +378,14 @@ public final class MediaSessionConnector { } /** - * Sets the player to which media commands sent by a media controller are delegated. - *

- * The media session callback is set if the {@code player} is not {@code null} and the callback is - * removed if the {@code player} is {@code null}. + * Sets the player to be connected to the media session. *

* The order in which any {@link CustomActionProvider}s are passed determines the order of the * actions published with the playback state of the session. * * @param player The player to be connected to the {@code MediaSession}. - * @param playbackPreparer The playback preparer for the player. - * @param customActionProviders Optional {@link CustomActionProvider}s to publish and handle + * @param playbackPreparer An optional {@link PlaybackPreparer} for preparing the player. + * @param customActionProviders An optional {@link CustomActionProvider}s to publish and handle * custom actions. */ public void setPlayer(Player player, PlaybackPreparer playbackPreparer, @@ -411,7 +394,7 @@ public final class MediaSessionConnector { this.player.removeListener(exoPlayerEventListener); mediaSession.setCallback(null); } - setPlaybackPreparer(playbackPreparer); + this.playbackPreparer = playbackPreparer; this.player = player; this.customActionProviders = (player != null && customActionProviders != null) ? customActionProviders : new CustomActionProvider[0]; @@ -424,9 +407,9 @@ public final class MediaSessionConnector { } /** - * Sets the optional {@link ErrorMessageProvider}. + * Sets the {@link ErrorMessageProvider}. * - * @param errorMessageProvider The {@link ErrorMessageProvider}. + * @param errorMessageProvider The error message provider. */ public void setErrorMessageProvider(ErrorMessageProvider errorMessageProvider) { this.errorMessageProvider = errorMessageProvider; @@ -437,25 +420,21 @@ public final class MediaSessionConnector { * {@code ACTION_SKIP_TO_PREVIOUS}, {@code ACTION_SKIP_TO_QUEUE_ITEM} and * {@code ACTION_SET_SHUFFLE_MODE_ENABLED}. * - * @param queueNavigator The navigator to handle queue navigation. + * @param queueNavigator The queue navigator. */ public void setQueueNavigator(QueueNavigator queueNavigator) { this.queueNavigator = queueNavigator; } /** - * Sets the queue editor to handle commands to manipulate the queue sent by a media controller. + * Sets the {@link QueueEditor} to handle queue edits sent by the media controller. * - * @param queueEditor The editor to handle queue manipulation actions. + * @param queueEditor The queue editor. */ public void setQueueEditor(QueueEditor queueEditor) { this.queueEditor = queueEditor; } - private void setPlaybackPreparer(PlaybackPreparer playbackPreparer) { - this.playbackPreparer = playbackPreparer; - } - private void updateMediaSessionPlaybackState() { PlaybackStateCompat.Builder builder = new PlaybackStateCompat.Builder(); if (player == null) { @@ -603,6 +582,7 @@ public final class MediaSessionConnector { } private class ExoPlayerEventListener implements Player.EventListener { + @Override public void onTimelineChanged(Timeline timeline, Object manifest) { if (queueNavigator != null) { diff --git a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/RepeatModeActionProvider.java b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/RepeatModeActionProvider.java index 1f33245059..abefe533ce 100644 --- a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/RepeatModeActionProvider.java +++ b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/RepeatModeActionProvider.java @@ -26,10 +26,13 @@ import com.google.android.exoplayer2.util.RepeatModeUtil; */ public final class RepeatModeActionProvider implements MediaSessionConnector.CustomActionProvider { + /** + * The default repeat toggle modes. + */ + public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES = + RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE | RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL; + private static final String ACTION_REPEAT_MODE = "ACTION_EXO_REPEAT_MODE"; - @RepeatModeUtil.RepeatToggleModes - private static final int DEFAULT_REPEAT_MODES = RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE - | RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL; private final Player player; @RepeatModeUtil.RepeatToggleModes @@ -39,20 +42,20 @@ public final class RepeatModeActionProvider implements MediaSessionConnector.Cus private final CharSequence repeatOffDescription; /** - * Creates a new {@link RepeatModeActionProvider}. + * Creates a new instance. *

- * This is equivalent to calling the two argument constructor with - * {@code RepeatModeUtil#REPEAT_TOGGLE_MODE_ONE | RepeatModeUtil#REPEAT_TOGGLE_MODE_ALL}. + * Equivalent to {@code RepeatModeActionProvider(context, player, + * RepeatModeActionProvider.DEFAULT_REPEAT_TOGGLE_MODES)}. * * @param context The context. * @param player The player on which to toggle the repeat mode. */ public RepeatModeActionProvider(Context context, Player player) { - this(context, player, DEFAULT_REPEAT_MODES); + this(context, player, DEFAULT_REPEAT_TOGGLE_MODES); } /** - * Creates a new {@link RepeatModeActionProvider} for the given repeat toggle modes. + * Creates a new instance enabling the given repeat toggle modes. * * @param context The context. * @param player The player on which to toggle the repeat mode. diff --git a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/TimelineQueueNavigator.java b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/TimelineQueueNavigator.java index 60aa5a5ba0..521b4cd6e3 100644 --- a/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/TimelineQueueNavigator.java +++ b/extensions/mediasession/src/main/java/com/google/android/exoplayer2/ext/mediasession/TimelineQueueNavigator.java @@ -29,9 +29,8 @@ import java.util.Collections; import java.util.List; /** - * An abstract implementation of the {@link MediaSessionConnector.QueueNavigator} that's based on an - * {@link Player}'s current {@link Timeline} and maps the timeline of the player to the media - * session queue. + * An abstract implementation of the {@link MediaSessionConnector.QueueNavigator} that maps the + * windows of a {@link Player}'s {@link Timeline} to the media session queue. */ public abstract class TimelineQueueNavigator implements MediaSessionConnector.QueueNavigator { @@ -44,10 +43,9 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu private long activeQueueItemId; /** - * Creates a new timeline queue navigator for a given {@link MediaSessionCompat}. + * Creates an instance for a given {@link MediaSessionCompat}. *

- * This is equivalent to calling - * {@code #TimelineQueueNavigator(mediaSession, DEFAULT_MAX_QUEUE_SIZE)}. + * Equivalent to {@code TimelineQueueNavigator(mediaSession, DEFAULT_MAX_QUEUE_SIZE)}. * * @param mediaSession The {@link MediaSessionCompat}. */ @@ -56,12 +54,11 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu } /** - * Creates a new timeline queue navigator for a given {@link MediaSessionCompat} and a maximum - * queue size of {@code maxQueueSize}. + * Creates an instance for a given {@link MediaSessionCompat} and maximum queue size. *

- * If the actual queue size is larger than {@code maxQueueSize} a floating window of - * {@code maxQueueSize} is applied and moved back and forth when the user is navigating within the - * queue. + * If the number of windows in the {@link Player}'s {@link Timeline} exceeds {@code maxQueueSize}, + * the media session queue will correspond to {@code maxQueueSize} windows centered on the one + * currently being played. * * @param mediaSession The {@link MediaSessionCompat}. * @param maxQueueSize The maximum queue size. @@ -80,12 +77,6 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu */ public abstract MediaDescriptionCompat getMediaDescription(int windowIndex); - /** - * Supports the following media actions: {@code PlaybackStateCompat.ACTION_SKIP_TO_NEXT | - * PlaybackStateCompat.ACTION_SKIP_TO_PREVIOUS | PlaybackStateCompat.ACTION_SKIP_TO_QUEUE_ITEM}. - * - * @return The bit mask of the supported media actions. - */ @Override public long getSupportedQueueNavigatorActions(Player player) { if (player == null || player.getCurrentTimeline().getWindowCount() < 2) { diff --git a/library/ui/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java b/library/ui/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java index a99c2dfde2..6ddbfed973 100644 --- a/library/ui/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java +++ b/library/ui/src/main/java/com/google/android/exoplayer2/ui/PlaybackControlView.java @@ -249,11 +249,23 @@ public class PlaybackControlView extends FrameLayout { }; + /** + * The default fast forward increment, in milliseconds. + */ public static final int DEFAULT_FAST_FORWARD_MS = 15000; + /** + * The default rewind increment, in milliseconds. + */ public static final int DEFAULT_REWIND_MS = 5000; + /** + * The default show timeout, in milliseconds. + */ public static final int DEFAULT_SHOW_TIMEOUT_MS = 5000; - public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES - = RepeatModeUtil.REPEAT_TOGGLE_MODE_NONE; + /** + * The default repeat toggle modes. + */ + public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES = + RepeatModeUtil.REPEAT_TOGGLE_MODE_NONE; /** * The maximum number of windows that can be shown in a multi-window time bar.