From 7c090d54e2c0eb5309d3f7dc131e137d9c986793 Mon Sep 17 00:00:00 2001 From: Insun Kang Date: Mon, 29 Feb 2016 10:51:24 +0900 Subject: [PATCH] Annotate Media section of framework/base Use @IntDef and @StringDef annotations where appropriate to ensure that IDEs can autocomplete to the correct set of constants. Bug: 22726900 Change-Id: I7626beb0634b754ffea9c012f42e6a21aa0faa51 --- media/java/android/media/MediaMetadata.java | 63 +++++++++++++++---- media/java/android/media/MediaRouter.java | 24 +++++-- media/java/android/media/Rating.java | 28 +++++++-- media/java/android/media/VolumeProvider.java | 17 ++++- .../android/media/session/MediaSession.java | 2 +- .../android/media/session/PlaybackState.java | 34 +++++++++- 6 files changed, 141 insertions(+), 27 deletions(-) diff --git a/media/java/android/media/MediaMetadata.java b/media/java/android/media/MediaMetadata.java index 39bcef508c0a8..722605f5d5448 100644 --- a/media/java/android/media/MediaMetadata.java +++ b/media/java/android/media/MediaMetadata.java @@ -16,6 +16,7 @@ package android.media; import android.annotation.NonNull; +import android.annotation.StringDef; import android.content.ContentResolver; import android.graphics.Bitmap; import android.graphics.BitmapFactory; @@ -30,6 +31,8 @@ import android.util.ArrayMap; import android.util.Log; import android.util.SparseArray; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; import java.util.Set; /** @@ -38,6 +41,40 @@ import java.util.Set; public final class MediaMetadata implements Parcelable { private static final String TAG = "MediaMetadata"; + /** + * @hide + */ + @StringDef({METADATA_KEY_TITLE, METADATA_KEY_ARTIST, METADATA_KEY_ALBUM, METADATA_KEY_AUTHOR, + METADATA_KEY_WRITER, METADATA_KEY_COMPOSER, METADATA_KEY_COMPILATION, + METADATA_KEY_DATE, METADATA_KEY_GENRE, METADATA_KEY_ALBUM_ARTIST, METADATA_KEY_ART_URI, + METADATA_KEY_ALBUM_ART_URI, METADATA_KEY_DISPLAY_TITLE, METADATA_KEY_DISPLAY_SUBTITLE, + METADATA_KEY_DISPLAY_DESCRIPTION, METADATA_KEY_DISPLAY_ICON_URI, + METADATA_KEY_MEDIA_ID}) + @Retention(RetentionPolicy.SOURCE) + public @interface TextKey {} + + /** + * @hide + */ + @StringDef({METADATA_KEY_DURATION, METADATA_KEY_YEAR, METADATA_KEY_TRACK_NUMBER, + METADATA_KEY_NUM_TRACKS, METADATA_KEY_DISC_NUMBER}) + @Retention(RetentionPolicy.SOURCE) + public @interface LongKey {} + + /** + * @hide + */ + @StringDef({METADATA_KEY_ART, METADATA_KEY_ALBUM_ART, METADATA_KEY_DISPLAY_ICON}) + @Retention(RetentionPolicy.SOURCE) + public @interface BitmapKey {} + + /** + * @hide + */ + @StringDef({METADATA_KEY_USER_RATING, METADATA_KEY_RATING}) + @Retention(RetentionPolicy.SOURCE) + public @interface RatingKey {} + /** * The title of the media. */ @@ -232,7 +269,7 @@ public final class MediaMetadata implements Parcelable { */ public static final String METADATA_KEY_MEDIA_ID = "android.media.metadata.MEDIA_ID"; - private static final String[] PREFERRED_DESCRIPTION_ORDER = { + private static final @TextKey String[] PREFERRED_DESCRIPTION_ORDER = { METADATA_KEY_TITLE, METADATA_KEY_ARTIST, METADATA_KEY_ALBUM, @@ -242,13 +279,13 @@ public final class MediaMetadata implements Parcelable { METADATA_KEY_COMPOSER }; - private static final String[] PREFERRED_BITMAP_ORDER = { + private static final @BitmapKey String[] PREFERRED_BITMAP_ORDER = { METADATA_KEY_DISPLAY_ICON, METADATA_KEY_ART, METADATA_KEY_ALBUM_ART }; - private static final String[] PREFERRED_URI_ORDER = { + private static final @TextKey String[] PREFERRED_URI_ORDER = { METADATA_KEY_DISPLAY_ICON_URI, METADATA_KEY_ART_URI, METADATA_KEY_ALBUM_ART_URI @@ -349,7 +386,7 @@ public final class MediaMetadata implements Parcelable { * @param key The key the value is stored under * @return a CharSequence value, or null */ - public CharSequence getText(String key) { + public CharSequence getText(@TextKey String key) { return mBundle.getCharSequence(key); } @@ -362,7 +399,7 @@ public final class MediaMetadata implements Parcelable { * @param key The key the value is stored under * @return a String value, or null */ - public String getString(String key) { + public String getString(@TextKey String key) { CharSequence text = getText(key); if (text != null) { return text.toString(); @@ -377,7 +414,7 @@ public final class MediaMetadata implements Parcelable { * @param key The key the value is stored under * @return a long value */ - public long getLong(String key) { + public long getLong(@LongKey String key) { return mBundle.getLong(key, 0); } @@ -388,7 +425,7 @@ public final class MediaMetadata implements Parcelable { * @param key The key the value is stored under * @return A {@link Rating} or null */ - public Rating getRating(String key) { + public Rating getRating(@RatingKey String key) { Rating rating = null; try { rating = mBundle.getParcelable(key); @@ -406,7 +443,7 @@ public final class MediaMetadata implements Parcelable { * @param key The key the value is stored under * @return A {@link Bitmap} or null */ - public Bitmap getBitmap(String key) { + public Bitmap getBitmap(@BitmapKey String key) { Bitmap bmp = null; try { bmp = mBundle.getParcelable(key); @@ -612,7 +649,7 @@ public final class MediaMetadata implements Parcelable { * @param value The CharSequence value to store * @return The Builder to allow chaining */ - public Builder putText(String key, CharSequence value) { + public Builder putText(@TextKey String key, CharSequence value) { if (METADATA_KEYS_TYPE.containsKey(key)) { if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_TEXT) { throw new IllegalArgumentException("The " + key @@ -654,7 +691,7 @@ public final class MediaMetadata implements Parcelable { * @param value The String value to store * @return The Builder to allow chaining */ - public Builder putString(String key, String value) { + public Builder putString(@TextKey String key, String value) { if (METADATA_KEYS_TYPE.containsKey(key)) { if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_TEXT) { throw new IllegalArgumentException("The " + key @@ -681,7 +718,7 @@ public final class MediaMetadata implements Parcelable { * @param value The long value to store * @return The Builder to allow chaining */ - public Builder putLong(String key, long value) { + public Builder putLong(@LongKey String key, long value) { if (METADATA_KEYS_TYPE.containsKey(key)) { if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_LONG) { throw new IllegalArgumentException("The " + key @@ -705,7 +742,7 @@ public final class MediaMetadata implements Parcelable { * @param value The Rating value to store * @return The Builder to allow chaining */ - public Builder putRating(String key, Rating value) { + public Builder putRating(@RatingKey String key, Rating value) { if (METADATA_KEYS_TYPE.containsKey(key)) { if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_RATING) { throw new IllegalArgumentException("The " + key @@ -734,7 +771,7 @@ public final class MediaMetadata implements Parcelable { * @param value The Bitmap to store * @return The Builder to allow chaining */ - public Builder putBitmap(String key, Bitmap value) { + public Builder putBitmap(@BitmapKey String key, Bitmap value) { if (METADATA_KEYS_TYPE.containsKey(key)) { if (METADATA_KEYS_TYPE.get(key) != METADATA_TYPE_BITMAP) { throw new IllegalArgumentException("The " + key diff --git a/media/java/android/media/MediaRouter.java b/media/java/android/media/MediaRouter.java index bcc2b40643be5..d8e0d6dca9e6a 100644 --- a/media/java/android/media/MediaRouter.java +++ b/media/java/android/media/MediaRouter.java @@ -1547,18 +1547,30 @@ public class MediaRouter { private Object mTag; + /** @hide */ + @IntDef({PLAYBACK_TYPE_LOCAL, PLAYBACK_TYPE_REMOTE}) + @Retention(RetentionPolicy.SOURCE) + public @interface PlaybackType {} + /** * The default playback type, "local", indicating the presentation of the media is happening * on the same device (e.g. a phone, a tablet) as where it is controlled from. * @see #getPlaybackType() */ public final static int PLAYBACK_TYPE_LOCAL = 0; + /** * A playback type indicating the presentation of the media is happening on * a different device (i.e. the remote device) than where it is controlled from. * @see #getPlaybackType() */ public final static int PLAYBACK_TYPE_REMOTE = 1; + + /** @hide */ + @IntDef({PLAYBACK_VOLUME_FIXED,PLAYBACK_VOLUME_VARIABLE}) + @Retention(RetentionPolicy.SOURCE) + private @interface PlaybackVolume {} + /** * Playback information indicating the playback volume is fixed, i.e. it cannot be * controlled from this object. An example of fixed playback volume is a remote player, @@ -1783,6 +1795,7 @@ public class MediaRouter { * @return the type of playback associated with this route * @see UserRouteInfo#setPlaybackType(int) */ + @PlaybackType public int getPlaybackType() { return mPlaybackType; } @@ -1874,6 +1887,7 @@ public class MediaRouter { * @return how volume is handling on the route * @see UserRouteInfo#setVolumeHandling(int) */ + @PlaybackVolume public int getVolumeHandling() { return mVolumeHandling; } @@ -2164,7 +2178,7 @@ public class MediaRouter { * ({@link RouteInfo#PLAYBACK_TYPE_REMOTE}). * @param type */ - public void setPlaybackType(int type) { + public void setPlaybackType(@RouteInfo.PlaybackType int type) { if (mPlaybackType != type) { mPlaybackType = type; configureSessionVolume(); @@ -2177,7 +2191,7 @@ public class MediaRouter { * ({@link RouteInfo#PLAYBACK_VOLUME_VARIABLE}). * @param volumeHandling */ - public void setVolumeHandling(int volumeHandling) { + public void setVolumeHandling(@RouteInfo.PlaybackVolume int volumeHandling) { if (mVolumeHandling != volumeHandling) { mVolumeHandling = volumeHandling; configureSessionVolume(); @@ -2268,7 +2282,8 @@ public class MediaRouter { return; } if (mPlaybackType == RemoteControlClient.PLAYBACK_TYPE_REMOTE) { - int volumeControl = VolumeProvider.VOLUME_CONTROL_FIXED; + @VolumeProvider.ControlType int volumeControl = + VolumeProvider.VOLUME_CONTROL_FIXED; switch (mVolumeHandling) { case RemoteControlClient.PLAYBACK_VOLUME_VARIABLE: volumeControl = VolumeProvider.VOLUME_CONTROL_ABSOLUTE; @@ -2294,7 +2309,8 @@ public class MediaRouter { class SessionVolumeProvider extends VolumeProvider { - public SessionVolumeProvider(int volumeControl, int maxVolume, int currentVolume) { + public SessionVolumeProvider(@VolumeProvider.ControlType int volumeControl, + int maxVolume, int currentVolume) { super(volumeControl, maxVolume, currentVolume); } diff --git a/media/java/android/media/Rating.java b/media/java/android/media/Rating.java index a518bb4552d32..04d5364f7c819 100644 --- a/media/java/android/media/Rating.java +++ b/media/java/android/media/Rating.java @@ -16,10 +16,14 @@ package android.media; +import android.annotation.IntDef; import android.os.Parcel; import android.os.Parcelable; import android.util.Log; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + /** * A class to encapsulate rating information used as content metadata. * A rating is defined by its rating style (see {@link #RATING_HEART}, @@ -31,6 +35,21 @@ import android.util.Log; public final class Rating implements Parcelable { private final static String TAG = "Rating"; + /** + * @hide + */ + @IntDef({RATING_NONE, RATING_HEART, RATING_THUMB_UP_DOWN, RATING_3_STARS, RATING_4_STARS, + RATING_5_STARS, RATING_PERCENTAGE}) + @Retention(RetentionPolicy.SOURCE) + public @interface Style {} + + /** + * @hide + */ + @IntDef({RATING_3_STARS, RATING_4_STARS, RATING_5_STARS}) + @Retention(RetentionPolicy.SOURCE) + public @interface StarStyle {} + /** * Indicates a rating style is not supported. A Rating will never have this * type, but can be used by other classes to indicate they do not support @@ -75,7 +94,7 @@ public final class Rating implements Parcelable { private final float mRatingValue; - private Rating(int ratingStyle, float rating) { + private Rating(@Style int ratingStyle, float rating) { mRatingStyle = ratingStyle; mRatingValue = rating; } @@ -124,7 +143,7 @@ public final class Rating implements Parcelable { * or {@link #RATING_PERCENTAGE}. * @return null if an invalid rating style is passed, a new Rating instance otherwise. */ - public static Rating newUnratedRating(int ratingStyle) { + public static Rating newUnratedRating(@Style int ratingStyle) { switch(ratingStyle) { case RATING_HEART: case RATING_THUMB_UP_DOWN: @@ -172,7 +191,7 @@ public final class Rating implements Parcelable { * @return null if the rating style is invalid, or the rating is out of range, * a new Rating instance otherwise. */ - public static Rating newStarRating(int starRatingStyle, float starRating) { + public static Rating newStarRating(@StarStyle int starRatingStyle, float starRating) { float maxRating = -1.0f; switch(starRatingStyle) { case RATING_3_STARS: @@ -225,6 +244,7 @@ public final class Rating implements Parcelable { * {@link #RATING_3_STARS}, {@link #RATING_4_STARS}, {@link #RATING_5_STARS}, * or {@link #RATING_PERCENTAGE}. */ + @Style public int getRatingStyle() { return mRatingStyle; } @@ -285,4 +305,4 @@ public final class Rating implements Parcelable { return mRatingValue; } } -} \ No newline at end of file +} diff --git a/media/java/android/media/VolumeProvider.java b/media/java/android/media/VolumeProvider.java index 5d1e0041585c3..1c017c564b43e 100644 --- a/media/java/android/media/VolumeProvider.java +++ b/media/java/android/media/VolumeProvider.java @@ -15,8 +15,12 @@ */ package android.media; +import android.annotation.IntDef; import android.media.session.MediaSession; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + /** * Handles requests to adjust or set the volume on a session. This is also used * to push volume updates back to the session. The provider must call @@ -26,6 +30,14 @@ import android.media.session.MediaSession; * {@link MediaSession#setPlaybackToRemote}. */ public abstract class VolumeProvider { + + /** + * @hide + */ + @IntDef({VOLUME_CONTROL_FIXED, VOLUME_CONTROL_RELATIVE, VOLUME_CONTROL_ABSOLUTE}) + @Retention(RetentionPolicy.SOURCE) + public @interface ControlType {} + /** * The volume is fixed and can not be modified. Requests to change volume * should be ignored. @@ -61,7 +73,7 @@ public abstract class VolumeProvider { * @param maxVolume The maximum allowed volume. * @param currentVolume The current volume on the output. */ - public VolumeProvider(int volumeControl, int maxVolume, int currentVolume) { + public VolumeProvider(@ControlType int volumeControl, int maxVolume, int currentVolume) { mControlType = volumeControl; mMaxVolume = maxVolume; mCurrentVolume = currentVolume; @@ -72,6 +84,7 @@ public abstract class VolumeProvider { * * @return The volume control type for this volume provider */ + @ControlType public final int getVolumeControl() { return mControlType; } @@ -145,4 +158,4 @@ public abstract class VolumeProvider { public static abstract class Callback { public abstract void onVolumeChanged(VolumeProvider volumeProvider); } -} \ No newline at end of file +} diff --git a/media/java/android/media/session/MediaSession.java b/media/java/android/media/session/MediaSession.java index 0bd1713c4a343..7f9653d336dff 100644 --- a/media/java/android/media/session/MediaSession.java +++ b/media/java/android/media/session/MediaSession.java @@ -469,7 +469,7 @@ public final class MediaSession { *
  • {@link Rating#RATING_THUMB_UP_DOWN}
    • * */ - public void setRatingType(int type) { + public void setRatingType(@Rating.Style int type) { try { mBinder.setRatingType(type); } catch (RemoteException e) { diff --git a/media/java/android/media/session/PlaybackState.java b/media/java/android/media/session/PlaybackState.java index 1485cd782605a..8283c8b967e80 100644 --- a/media/java/android/media/session/PlaybackState.java +++ b/media/java/android/media/session/PlaybackState.java @@ -16,6 +16,7 @@ package android.media.session; import android.annotation.DrawableRes; +import android.annotation.IntDef; import android.annotation.Nullable; import android.media.RemoteControlClient; import android.os.Bundle; @@ -26,6 +27,9 @@ import android.text.TextUtils; import java.util.ArrayList; import java.util.List; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + /** * Playback state for a {@link MediaSession}. This includes a state like * {@link PlaybackState#STATE_PLAYING}, the current playback position, @@ -34,6 +38,17 @@ import java.util.List; public final class PlaybackState implements Parcelable { private static final String TAG = "PlaybackState"; + /** + * @hide + */ + @IntDef(flag=true, value={ACTION_STOP, ACTION_PAUSE, ACTION_PLAY, ACTION_REWIND, + ACTION_SKIP_TO_PREVIOUS, ACTION_SKIP_TO_NEXT, ACTION_FAST_FORWARD, ACTION_SET_RATING, + ACTION_SEEK_TO, ACTION_PLAY_PAUSE, ACTION_PLAY_FROM_MEDIA_ID, ACTION_PLAY_FROM_SEARCH, + ACTION_SKIP_TO_QUEUE_ITEM, ACTION_PLAY_FROM_URI, ACTION_PREPARE, + ACTION_PREPARE_FROM_MEDIA_ID, ACTION_PREPARE_FROM_SEARCH, ACTION_PREPARE_FROM_URI}) + @Retention(RetentionPolicy.SOURCE) + public @interface Actions {} + /** * Indicates this session supports the stop command. * @@ -160,6 +175,15 @@ public final class PlaybackState implements Parcelable { */ public static final long ACTION_PREPARE_FROM_URI = 1 << 17; + /** + * @hide + */ + @IntDef({STATE_NONE, STATE_STOPPED, STATE_PAUSED, STATE_PLAYING, STATE_FAST_FORWARDING, + STATE_REWINDING, STATE_BUFFERING, STATE_ERROR, STATE_CONNECTING, + STATE_SKIPPING_TO_PREVIOUS, STATE_SKIPPING_TO_NEXT, STATE_SKIPPING_TO_QUEUE_ITEM}) + @Retention(RetentionPolicy.SOURCE) + public @interface State {} + /** * This is the default playback state and indicates that no media has been * added yet, or the performer has been reset and has no content to play. @@ -349,9 +373,11 @@ public final class PlaybackState implements Parcelable { *
  • {@link PlaybackState#STATE_SKIPPING_TO_QUEUE_ITEM}
    • * */ + @State public int getState() { return mState; } + /** * Get the current playback position in ms. */ @@ -403,6 +429,7 @@ public final class PlaybackState implements Parcelable { *
  • {@link PlaybackState#ACTION_PREPARE_FROM_URI}
    • * */ + @Actions public long getActions() { return mActions; } @@ -866,7 +893,8 @@ public final class PlaybackState implements Parcelable { * timebase that the position was updated at. * @return this */ - public Builder setState(int state, long position, float playbackSpeed, long updateTime) { + public Builder setState(@State int state, long position, float playbackSpeed, + long updateTime) { mState = state; mPosition = position; mUpdateTime = updateTime; @@ -907,7 +935,7 @@ public final class PlaybackState implements Parcelable { * normal playback. * @return this */ - public Builder setState(int state, long position, float playbackSpeed) { + public Builder setState(@State int state, long position, float playbackSpeed) { return setState(state, position, playbackSpeed, SystemClock.elapsedRealtime()); } @@ -938,7 +966,7 @@ public final class PlaybackState implements Parcelable { * @param actions The set of actions allowed. * @return this */ - public Builder setActions(long actions) { + public Builder setActions(@Actions long actions) { mActions = actions; return this; }