From d277683657c374a7e2cf8a54fdfbc66d25edae64 Mon Sep 17 00:00:00 2001 From: Hyundo Moon Date: Mon, 5 Feb 2018 17:17:03 +0900 Subject: [PATCH] MediaBrowser2: Add search related methods This CL adds following APIs: - BrowserCallback#onSearchResultChanged - BrowserCallback#onSearchResultLoaded (previously onSearchResult) - MediaLibrarySessionCallback#onLoadSearchResult This CL also fixes conflicting @NonNull/@Nullable annotations in MediaItem2 methods. Bug: 72786724 Test: Builds successfully Change-Id: Ica90ca6b47f33cd3d457a28598a035a00d144dfa --- media/java/android/media/MediaBrowser2.java | 119 +++++++++++------- media/java/android/media/MediaItem2.java | 13 +- .../android/media/MediaLibraryService2.java | 74 ++++++----- .../media/update/MediaBrowser2Provider.java | 6 +- 4 files changed, 130 insertions(+), 82 deletions(-) diff --git a/media/java/android/media/MediaBrowser2.java b/media/java/android/media/MediaBrowser2.java index 62fe44f2d2b4f..32d31621aa27e 100644 --- a/media/java/android/media/MediaBrowser2.java +++ b/media/java/android/media/MediaBrowser2.java @@ -52,9 +52,33 @@ public class MediaBrowser2 extends MediaController2 { public void onGetRootResult(Bundle rootHints, @Nullable String rootMediaId, @Nullable Bundle rootExtra) { } + /** + * Called when there's change in the parent's children. + * + * @param parentId parent id that you've specified with {@link #subscribe(String, Bundle)} + * @param extras extra bundle that you've specified with {@link #subscribe(String, Bundle)} + */ + public void onChildrenChanged(@NonNull String parentId, @Nullable Bundle extras) { } + + /** + * Called when the list of items has been returned by the library service for the previous + * {@link MediaBrowser2#getChildren(String, int, int, Bundle)}. + * + * @param parentId parent id + * @param page page number that you've specified with + * {@link #getChildren(String, int, int, Bundle)} + * @param pageSize page size that you've specified with + * {@link #getChildren(String, int, int, Bundle)} + * @param extras extra bundle that you've specified with + * {@link #getChildren(String, int, int, Bundle)} + * @param result result. Can be {@code null} + */ + public void onChildrenLoaded(@NonNull String parentId, int page, int pageSize, + @Nullable Bundle extras, @Nullable List result) { } + /** * Called when the item has been returned by the library service for the previous - * {@link MediaBrowser2#getItem} call. + * {@link MediaBrowser2#getItem(String)} call. *

* Result can be null if there had been error. * @@ -64,40 +88,33 @@ public class MediaBrowser2 extends MediaController2 { public void onItemLoaded(@NonNull String mediaId, @Nullable MediaItem2 result) { } /** - * Called when the list of items has been returned by the library service for the previous - * {@link MediaBrowser2#getChildren(String, int, int, Bundle)}. + * Called when there's change in the search result. * - * @param parentId parent id - * @param page page number that you've specified - * @param pageSize page size that you've specified - * @param options optional bundle that you've specified - * @param result result. Can be {@code null} + * @param query search query that you've specified with {@link #search(String, Bundle)} + * @param extras extra bundle that you've specified with {@link #search(String, Bundle)} + * @param totalItemCount The total item count for the search result */ - public void onChildrenLoaded(@NonNull String parentId, int page, int pageSize, - @Nullable Bundle options, @Nullable List result) { } - - /** - * Called when there's change in the parent's children. - * - * @param parentId parent id that you've specified with subscribe - * @param options optional bundle that you've specified with subscribe - */ - public void onChildrenChanged(@NonNull String parentId, @Nullable Bundle options) { } + public void onSearchResultChanged(@NonNull String query, @Nullable Bundle extras, + int totalItemCount) { } /** * Called when the search result has been returned by the library service for the previous - * {@link MediaBrowser2#search(String, int, int, Bundle)}. + * {@link MediaBrowser2#getSearchResult(String, int, int, Bundle)}. *

* Result can be null if there had been error. * - * @param query query string that you've specified - * @param page page number that you've specified - * @param pageSize page size that you've specified - * @param options optional bundle that you've specified - * @param result result. Can be {@code null} + * @param query search query that you've specified with + * {@link #getSearchResult(String, int, int, Bundle)} + * @param page page number that you've specified with + * {@link #getSearchResult(String, int, int, Bundle)} + * @param pageSize page size that you've specified with + * {@link #getSearchResult(String, int, int, Bundle)} + * @param extras extra bundle that you've specified with + * {@link #getSearchResult(String, int, int, Bundle)} + * @param result result. Can be {@code null}. */ - public void onSearchResult(@NonNull String query, int page, int pageSize, - @Nullable Bundle options, @Nullable List result) { } + public void onSearchResultLoaded(@NonNull String query, int page, int pageSize, + @Nullable Bundle extras, @Nullable List result) { } } public MediaBrowser2(@NonNull Context context, @NonNull SessionToken2 token, @@ -131,10 +148,10 @@ public class MediaBrowser2 extends MediaController2 { * the actual contents for the parent. * * @param parentId parent id - * @param options optional bundle + * @param extras extra bundle */ - public void subscribe(String parentId, @Nullable Bundle options) { - mProvider.subscribe_impl(parentId, options); + public void subscribe(String parentId, @Nullable Bundle extras) { + mProvider.subscribe_impl(parentId, extras); } /** @@ -142,10 +159,23 @@ public class MediaBrowser2 extends MediaController2 { * {@link #subscribe(String, Bundle)}. * * @param parentId parent id - * @param options optional bundle + * @param extras extra bundle */ - public void unsubscribe(String parentId, @Nullable Bundle options) { - mProvider.unsubscribe_impl(parentId, options); + public void unsubscribe(String parentId, @Nullable Bundle extras) { + mProvider.unsubscribe_impl(parentId, extras); + } + + /** + * Get list of children under the parent. Result would be sent back asynchronously with the + * {@link BrowserCallback#onChildrenLoaded(String, int, int, Bundle, List)}. + * + * @param parentId parent id for getting the children. + * @param page page number to get the result. Starts from {@code 1} + * @param pageSize page size. Should be greater or equal to {@code 1} + * @param extras extra bundle + */ + public void getChildren(String parentId, int page, int pageSize, @Nullable Bundle extras) { + mProvider.getChildren_impl(parentId, page, pageSize, extras); } /** @@ -159,26 +189,29 @@ public class MediaBrowser2 extends MediaController2 { } /** - * Get list of children under the parent. Result would be sent back asynchronously with the - * {@link BrowserCallback#onChildrenLoaded(String, int, int, Bundle, List)}. + * Send a search request to the library service. When there's a change, + * {@link BrowserCallback#onSearchResultChanged(String, Bundle, int)} will be called with the + * bundle that you've specified. You should call + * {@link #getSearchResult(String, int, int, Bundle)} to get the actual search result. * - * @param parentId parent id for getting the children. - * @param page page number to get the result. Starts from {@code 1} - * @param pageSize page size. Should be greater or equal to {@code 1} - * @param options optional bundle + * @param query search query. Should not be an empty string. + * @param extras extra bundle */ - public void getChildren(String parentId, int page, int pageSize, @Nullable Bundle options) { - mProvider.getChildren_impl(parentId, page, pageSize, options); + public void search(@NonNull String query, @Nullable Bundle extras) { + mProvider.search_impl(query, extras); } /** + * Get the search result from lhe library service. Result would be sent back asynchronously with + * the {@link BrowserCallback#onSearchResultLoaded(String, int, int, Bundle, List)}. * - * @param query search query deliminated by string + * @param query search query that you've specified with {@link #search(String, Bundle)} * @param page page number to get search result. Starts from {@code 1} * @param pageSize page size. Should be greater or equal to {@code 1} * @param extras extra bundle */ - public void search(String query, int page, int pageSize, Bundle extras) { - mProvider.search_impl(query, page, pageSize, extras); + public void getSearchResult(@NonNull String query, int page, int pageSize, + @Nullable Bundle extras) { + mProvider.getSearchResult_impl(query, page, pageSize, extras); } } diff --git a/media/java/android/media/MediaItem2.java b/media/java/android/media/MediaItem2.java index eae4436cae788..667aac1b426a6 100644 --- a/media/java/android/media/MediaItem2.java +++ b/media/java/android/media/MediaItem2.java @@ -123,27 +123,26 @@ public class MediaItem2 { } /** - * Set a metadata. Metadata shouldn't be {@code null} and its id should be match - * with this instance's id. + * Set a metadata. If the metadata is not null, its id should be matched with this instance's + * media id. * * @param metadata metadata to update */ - public void setMetadata(@NonNull MediaMetadata2 metadata) { + public void setMetadata(@Nullable MediaMetadata2 metadata) { mProvider.setMetadata_impl(metadata); } /** * Returns the metadata of the media. */ - public @NonNull MediaMetadata2 getMetadata() { + public @Nullable MediaMetadata2 getMetadata() { return mProvider.getMetadata_impl(); } /** - * Returns the media id in the {@link MediaMetadata2} for this item. - * @see MediaMetadata2#METADATA_KEY_MEDIA_ID + * Returns the media id for this item. */ - public @Nullable String getMediaId() { + public @NonNull String getMediaId() { return mProvider.getMediaId_impl(); } diff --git a/media/java/android/media/MediaLibraryService2.java b/media/java/android/media/MediaLibraryService2.java index f49710de0a008..7a05d3c0724a1 100644 --- a/media/java/android/media/MediaLibraryService2.java +++ b/media/java/android/media/MediaLibraryService2.java @@ -82,22 +82,22 @@ public abstract class MediaLibraryService2 extends MediaSessionService2 { * * @param controller controller to notify * @param parentId - * @param options + * @param extras */ public void notifyChildrenChanged(@NonNull ControllerInfo controller, - @NonNull String parentId, @NonNull Bundle options) { - mProvider.notifyChildrenChanged_impl(controller, parentId, options); + @NonNull String parentId, @NonNull Bundle extras) { + mProvider.notifyChildrenChanged_impl(controller, parentId, extras); } /** * Notify subscribed controller about change in a parent's children. * * @param parentId parent id - * @param options optional bundle + * @param extras extra bundle */ // This is for the backward compatibility. - public void notifyChildrenChanged(@NonNull String parentId, @Nullable Bundle options) { - mProvider.notifyChildrenChanged_impl(parentId, options); + public void notifyChildrenChanged(@NonNull String parentId, @Nullable Bundle extras) { + mProvider.notifyChildrenChanged_impl(parentId, extras); } } @@ -133,21 +133,6 @@ public abstract class MediaLibraryService2 extends MediaSessionService2 { return null; } - /** - * Called to get the search result. Return search result here for the browser. - *

- * Return an empty list for no search result, and return {@code null} for the error. - * - * @param query The search query sent from the media browser. It contains keywords separated - * by space. - * @param extras The bundle of service-specific arguments sent from the media browser. - * @return search result. {@code null} for error. - */ - public @Nullable List onSearch(@NonNull ControllerInfo controllerInfo, - @NonNull String query, @Nullable Bundle extras) { - return null; - } - /** * Called to get an item. Return result here for the browser. *

@@ -169,11 +154,11 @@ public abstract class MediaLibraryService2 extends MediaSessionService2 { * @param parentId parent id to get children * @param page number of page * @param pageSize size of the page - * @param options optional bundle + * @param extras extra bundle * @return list of children. Can be {@code null}. */ public @Nullable List onLoadChildren(@NonNull ControllerInfo controller, - @NonNull String parentId, int page, int pageSize, @Nullable Bundle options) { + @NonNull String parentId, int page, int pageSize, @Nullable Bundle extras) { return null; } @@ -182,10 +167,10 @@ public abstract class MediaLibraryService2 extends MediaSessionService2 { * * @param controller controller * @param parentId parent id - * @param options optional bundle + * @param extras extra bundle */ - public void onSubscribed(@NonNull ControllerInfo controller, - String parentId, @Nullable Bundle options) { + public void onSubscribed(@NonNull ControllerInfo controller, String parentId, + @Nullable Bundle extras) { } /** @@ -193,10 +178,41 @@ public abstract class MediaLibraryService2 extends MediaSessionService2 { * * @param controller controller * @param parentId parent id - * @param options optional bundle + * @param extras extra bundle */ - public void onUnsubscribed(@NonNull ControllerInfo controller, - String parentId, @Nullable Bundle options) { + public void onUnsubscribed(@NonNull ControllerInfo controller, String parentId, + @Nullable Bundle extras) { + } + + /** + * Called when a controller requests search. + * + * @param query The search query sent from the media browser. It contains keywords separated + * by space. + * @param extras The bundle of service-specific arguments sent from the media browser. + */ + public void onSearch(@NonNull ControllerInfo controllerInfo, @NonNull String query, + @Nullable Bundle extras) { + + } + + /** + * Called to get the search result. Return search result here for the browser which has + * requested search previously. + *

+ * Return an empty list for no search result, and return {@code null} for the error. + * + * @param controllerInfo Information of the controller requesting the search result. + * @param query The search query which was previously sent through + * {@link #onSearch(ControllerInfo, String, Bundle)} call. + * @param page page number. Starts from {@code 1}. + * @param pageSize page size. Should be greater or equal to {@code 1}. + * @param extras The bundle of service-specific arguments sent from the media browser. + * @return search result. {@code null} for error. + */ + public @Nullable List onLoadSearchResult(@NonNull ControllerInfo controllerInfo, + @NonNull String query, int page, int pageSize, @Nullable Bundle extras) { + return null; } } diff --git a/media/java/android/media/update/MediaBrowser2Provider.java b/media/java/android/media/update/MediaBrowser2Provider.java index 17256a891277c..f2e73132a13ad 100644 --- a/media/java/android/media/update/MediaBrowser2Provider.java +++ b/media/java/android/media/update/MediaBrowser2Provider.java @@ -16,7 +16,6 @@ package android.media.update; -import android.annotation.SystemApi; import android.os.Bundle; /** @@ -29,6 +28,7 @@ public interface MediaBrowser2Provider extends MediaController2Provider { void unsubscribe_impl(String parentId, Bundle options); void getItem_impl(String mediaId); - void getChildren_impl(String parentId, int page, int pageSize, Bundle options); - void search_impl(String query, int page, int pageSize, Bundle extras); + void getChildren_impl(String parentId, int page, int pageSize, Bundle extras); + void search_impl(String query, Bundle options); + void getSearchResult_impl(String query, int page, int pageSize, Bundle extras); }