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

4 files changed, 64 insertions, 54 deletions

diff --git a/api/current.txt b/api/current.txt
index 3032b2d..9f59a20 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -17211,7 +17211,7 @@ package android.media.browse {
     method public void connect();
     method public void disconnect();
     method public android.os.Bundle getExtras();
-    method public void getMediaItem(java.lang.String, android.media.browse.MediaBrowser.MediaItemCallback);
+    method public void getItem(java.lang.String, android.media.browse.MediaBrowser.ItemCallback);
     method public java.lang.String getRoot();
     method public android.content.ComponentName getServiceComponent();
     method public android.media.session.MediaSession.Token getSessionToken();
@@ -17227,6 +17227,12 @@ package android.media.browse {
     method public void onConnectionSuspended();
   }
 
+  public static abstract class MediaBrowser.ItemCallback {
+    ctor public MediaBrowser.ItemCallback();
+    method public void onError(java.lang.String);
+    method public void onItemLoaded(android.media.browse.MediaBrowser.MediaItem);
+  }
+
   public static class MediaBrowser.MediaItem implements android.os.Parcelable {
     ctor public MediaBrowser.MediaItem(android.media.MediaDescription, int);
     method public int describeContents();
@@ -17241,12 +17247,6 @@ package android.media.browse {
     field public static final int FLAG_PLAYABLE = 2; // 0x2
   }
 
-  public static abstract class MediaBrowser.MediaItemCallback {
-    ctor public MediaBrowser.MediaItemCallback();
-    method public void onError();
-    method public void onMediaItemLoaded(android.media.browse.MediaBrowser.MediaItem);
-  }
-
   public static abstract class MediaBrowser.SubscriptionCallback {
     ctor public MediaBrowser.SubscriptionCallback();
     method public void onChildrenLoaded(java.lang.String, java.util.List<android.media.browse.MediaBrowser.MediaItem>);
@@ -28788,12 +28788,12 @@ package android.service.media {
   public abstract class MediaBrowserService extends android.app.Service {
     ctor public MediaBrowserService();
     method public void dump(java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[]);
-    method public void getMediaItem(java.lang.String, android.service.media.MediaBrowserService.Result<android.media.browse.MediaBrowser.MediaItem>) throws java.lang.UnsupportedOperationException;
     method public android.media.session.MediaSession.Token getSessionToken();
     method public void notifyChildrenChanged(java.lang.String);
     method public android.os.IBinder onBind(android.content.Intent);
     method public abstract android.service.media.MediaBrowserService.BrowserRoot onGetRoot(java.lang.String, int, android.os.Bundle);
     method public abstract void onLoadChildren(java.lang.String, android.service.media.MediaBrowserService.Result<java.util.List<android.media.browse.MediaBrowser.MediaItem>>);
+    method public void onLoadItem(java.lang.String, android.service.media.MediaBrowserService.Result<android.media.browse.MediaBrowser.MediaItem>) throws java.lang.UnsupportedOperationException;
     method public void setSessionToken(android.media.session.MediaSession.Token);
     field public static final java.lang.String SERVICE_INTERFACE = "android.media.browse.MediaBrowserService";
   }
diff --git a/api/system-current.txt b/api/system-current.txt
index 2727caa..fc67e2d 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -18523,7 +18523,7 @@ package android.media.browse {
     method public void connect();
     method public void disconnect();
     method public android.os.Bundle getExtras();
-    method public void getMediaItem(java.lang.String, android.media.browse.MediaBrowser.MediaItemCallback);
+    method public void getItem(java.lang.String, android.media.browse.MediaBrowser.ItemCallback);
     method public java.lang.String getRoot();
     method public android.content.ComponentName getServiceComponent();
     method public android.media.session.MediaSession.Token getSessionToken();
@@ -18539,6 +18539,12 @@ package android.media.browse {
     method public void onConnectionSuspended();
   }
 
+  public static abstract class MediaBrowser.ItemCallback {
+    ctor public MediaBrowser.ItemCallback();
+    method public void onError(java.lang.String);
+    method public void onItemLoaded(android.media.browse.MediaBrowser.MediaItem);
+  }
+
   public static class MediaBrowser.MediaItem implements android.os.Parcelable {
     ctor public MediaBrowser.MediaItem(android.media.MediaDescription, int);
     method public int describeContents();
@@ -18553,12 +18559,6 @@ package android.media.browse {
     field public static final int FLAG_PLAYABLE = 2; // 0x2
   }
 
-  public static abstract class MediaBrowser.MediaItemCallback {
-    ctor public MediaBrowser.MediaItemCallback();
-    method public void onError();
-    method public void onMediaItemLoaded(android.media.browse.MediaBrowser.MediaItem);
-  }
-
   public static abstract class MediaBrowser.SubscriptionCallback {
     ctor public MediaBrowser.SubscriptionCallback();
     method public void onChildrenLoaded(java.lang.String, java.util.List<android.media.browse.MediaBrowser.MediaItem>);
@@ -30821,12 +30821,12 @@ package android.service.media {
   public abstract class MediaBrowserService extends android.app.Service {
     ctor public MediaBrowserService();
     method public void dump(java.io.FileDescriptor, java.io.PrintWriter, java.lang.String[]);
-    method public void getMediaItem(java.lang.String, android.service.media.MediaBrowserService.Result<android.media.browse.MediaBrowser.MediaItem>) throws java.lang.UnsupportedOperationException;
     method public android.media.session.MediaSession.Token getSessionToken();
     method public void notifyChildrenChanged(java.lang.String);
     method public android.os.IBinder onBind(android.content.Intent);
     method public abstract android.service.media.MediaBrowserService.BrowserRoot onGetRoot(java.lang.String, int, android.os.Bundle);
     method public abstract void onLoadChildren(java.lang.String, android.service.media.MediaBrowserService.Result<java.util.List<android.media.browse.MediaBrowser.MediaItem>>);
+    method public void onLoadItem(java.lang.String, android.service.media.MediaBrowserService.Result<android.media.browse.MediaBrowser.MediaItem>) throws java.lang.UnsupportedOperationException;
     method public void setSessionToken(android.media.session.MediaSession.Token);
     field public static final java.lang.String SERVICE_INTERFACE = "android.media.browse.MediaBrowserService";
   }
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.