Merge "Fix MediaBrowser.getItem() API inconsistencies." into mnc-dev

2 files changed, 48 insertions, 38 deletions

diff --git a/media/java/android/media/browse/MediaBrowser.java b/media/java/android/media/browse/MediaBrowser.java
index ef8d169..ba867e1 100644
--- a/media/java/android/media/browse/MediaBrowser.java
+++ b/media/java/android/media/browse/MediaBrowser.java
@@ -375,7 +375,7 @@ public final class MediaBrowser {
      * @param mediaId The id of the item to retrieve.
      * @param cb The callback to receive the result on.
      */
-    public void getMediaItem(@NonNull String mediaId, @NonNull final MediaItemCallback cb) {
+    public void getItem(final @NonNull String mediaId, @NonNull final ItemCallback cb) {
         if (TextUtils.isEmpty(mediaId)) {
             throw new IllegalArgumentException("mediaId is empty.");
         }
@@ -387,7 +387,7 @@ public final class MediaBrowser {
             mHandler.post(new Runnable() {
                 @Override
                 public void run() {
-                    cb.onError();
+                    cb.onError(mediaId);
                 }
             });
             return;
@@ -397,15 +397,15 @@ public final class MediaBrowser {
             protected void onReceiveResult(int resultCode, Bundle resultData) {
                 if (resultCode != 0 || resultData == null
                         || !resultData.containsKey(MediaBrowserService.KEY_MEDIA_ITEM)) {
-                    cb.onError();
+                    cb.onError(mediaId);
                     return;
                 }
                 Parcelable item = resultData.getParcelable(MediaBrowserService.KEY_MEDIA_ITEM);
                 if (!(item instanceof MediaItem)) {
-                    cb.onError();
+                    cb.onError(mediaId);
+                    return;
                 }
-                cb.onMediaItemLoaded((MediaItem) resultData.getParcelable(
-                        MediaBrowserService.KEY_MEDIA_ITEM));
+                cb.onItemLoaded((MediaItem)item);
             }
         };
         try {
@@ -415,7 +415,7 @@ public final class MediaBrowser {
             mHandler.post(new Runnable() {
                 @Override
                 public void run() {
-                    cb.onError();
+                    cb.onError(mediaId);
                 }
             });
         }
@@ -728,6 +728,9 @@ public final class MediaBrowser {
     public static abstract class SubscriptionCallback {
         /**
          * Called when the list of children is loaded or updated.
+         *
+         * @param parentId The media id of the parent media item.
+         * @param children The children which were loaded.
          */
         public void onChildrenLoaded(@NonNull String parentId,
                                      @NonNull List<MediaItem> children) {
@@ -739,29 +742,32 @@ public final class MediaBrowser {
          * If this is called, the subscription remains until {@link MediaBrowser#unsubscribe}
          * called, because some errors may heal themselves.
          * </p>
+         *
+         * @param parentId The media id of the parent media item whose children could
+         * not be loaded.
          */
-        public void onError(@NonNull String id) {
+        public void onError(@NonNull String parentId) {
         }
     }
 
     /**
-     * Callback for receiving the result of {@link #getMediaItem}.
+     * Callback for receiving the result of {@link #getItem}.
      */
-    public static abstract class MediaItemCallback {
-
+    public static abstract class ItemCallback {
         /**
          * Called when the item has been returned by the browser service.
          *
          * @param item The item that was returned or null if it doesn't exist.
          */
-        public void onMediaItemLoaded(MediaItem item) {
+        public void onItemLoaded(MediaItem item) {
         }
 
         /**
-         * Called when the id doesn't exist or there was an error retrieving the
-         * item.
+         * Called when the item doesn't exist or there was an error retrieving it.
+         *
+         * @param itemId The media id of the media item which could not be loaded.
          */
-        public void onError() {
+        public void onError(@NonNull String itemId) {
         }
     }
 
diff --git a/media/java/android/service/media/MediaBrowserService.java b/media/java/android/service/media/MediaBrowserService.java
index 41156cb..1bb99ff 100644
--- a/media/java/android/service/media/MediaBrowserService.java
+++ b/media/java/android/service/media/MediaBrowserService.java
@@ -76,7 +76,7 @@ public abstract class MediaBrowserService extends Service {
     public static final String SERVICE_INTERFACE = "android.media.browse.MediaBrowserService";
 
     /**
-     * A key for passing the MediaItem to the ResultReceiver in getMediaItem.
+     * A key for passing the MediaItem to the ResultReceiver in getItem.
      *
      * @hide
      */
@@ -109,6 +109,7 @@ public abstract class MediaBrowserService extends Service {
      * be thrown.
      *
      * @see MediaBrowserService#onLoadChildren
+     * @see MediaBrowserService#onGetMediaItem
      */
     public class Result<T> {
         private Object mDebug;
@@ -279,20 +280,7 @@ public abstract class MediaBrowserService extends Service {
             mHandler.post(new Runnable() {
                 @Override
                 public void run() {
-                    final Result<MediaBrowser.MediaItem> result
-                            = new Result<MediaBrowser.MediaItem>(mediaId) {
-                        @Override
-                        void onResultSent(MediaBrowser.MediaItem item) {
-                            Bundle bundle = new Bundle();
-                            bundle.putParcelable(KEY_MEDIA_ITEM, item);
-                            receiver.send(0, bundle);
-                        }
-                    };
-                    try {
-                        MediaBrowserService.this.getMediaItem(mediaId, result);
-                    } catch (UnsupportedOperationException e) {
-                        receiver.send(-1, null);
-                    }
+                    performLoadItem(mediaId, receiver);
                 }
             });
         }
@@ -357,8 +345,7 @@ public abstract class MediaBrowserService extends Service {
             @NonNull Result<List<MediaBrowser.MediaItem>> result);
 
     /**
-     * Called to get a specific media item. The mediaId should be the same id
-     * that would be returned for this item when it is in a list of child items.
+     * Called to get information about a specific media item.
      * <p>
      * Implementations must call {@link Result#sendResult result.sendResult}. If
      * loading the item will be an expensive operation {@link Result#detach
@@ -366,17 +353,15 @@ public abstract class MediaBrowserService extends Service {
      * then {@link Result#sendResult result.sendResult} called when the item has
      * been loaded.
      * <p>
-     * The default implementation throws an exception.
+     * The default implementation sends a null result.
      *
-     * @param mediaId The id for the specific
+     * @param itemId The id for the specific
      *            {@link android.media.browse.MediaBrowser.MediaItem}.
      * @param result The Result to send the item to, or null if the id is
      *            invalid.
-     * @throws UnsupportedOperationException
      */
-    public void getMediaItem(String mediaId, Result<MediaBrowser.MediaItem> result)
-            throws UnsupportedOperationException {
-        throw new UnsupportedOperationException("getMediaItem is not supported.");
+    public void onLoadItem(String itemId, Result<MediaBrowser.MediaItem> result) {
+        result.sendResult(null);
     }
 
     /**
@@ -515,6 +500,25 @@ public abstract class MediaBrowserService extends Service {
         }
     }
 
+    private void performLoadItem(String itemId, final ResultReceiver receiver) {
+        final Result<MediaBrowser.MediaItem> result =
+                new Result<MediaBrowser.MediaItem>(itemId) {
+            @Override
+            void onResultSent(MediaBrowser.MediaItem item) {
+                Bundle bundle = new Bundle();
+                bundle.putParcelable(KEY_MEDIA_ITEM, item);
+                receiver.send(0, bundle);
+            }
+        };
+
+        MediaBrowserService.this.onLoadItem(itemId, result);
+
+        if (!result.isDone()) {
+            throw new IllegalStateException("onLoadItem must call detach() or sendResult()"
+                    + " before returning for id=" + itemId);
+        }
+    }
+
     /**
      * Contains information that the browser service needs to send to the client
      * when first connected.