MediaSession2: Workaround javadoc issue with hidden generic super class
This includes two changes.
- Change all methods in MediaSession2.BuilderBase signatures from
public to package private.
- Subclasses of MediaSession2.BuilderBase (MediaSession2.Builder,
MediaLibraryService2.MediaLibrarySessionBuilder) now inherit all
methods from its super class and change method signatures to public
Changes are needed to workaround and fix following issues.
- Hidden super class's methods aren't shown in the Javadoc and 3rd
party apps cannot use them.
- Public generic methods in the super classes are shown in the Javadoc
with the generic types (e.g. 'U setSessionCallback()' instead of
'Builder setSessionCallback()')
- Stub classes for tests are automatically generated, but it somehow
fails to generate stub for the BuilderBase (seems like a bug)
Test: 'm update-api' and checked generated javadoc
Change-Id: I6f635624ef806578ab79d080424f11cb637d7984
diff --git a/media/java/android/media/MediaLibraryService2.java b/media/java/android/media/MediaLibraryService2.java
index f88f9f2..a11768e 100644
--- a/media/java/android/media/MediaLibraryService2.java
+++ b/media/java/android/media/MediaLibraryService2.java
@@ -27,7 +27,6 @@
import android.media.update.ApiLoader;
import android.media.update.MediaLibraryService2Provider.LibraryRootProvider;
import android.media.update.MediaLibraryService2Provider.MediaLibrarySessionProvider;
-import android.media.update.MediaSession2Provider;
import android.media.update.MediaSessionService2Provider;
import android.os.Bundle;
@@ -63,7 +62,8 @@
public static final String SERVICE_INTERFACE = "android.media.MediaLibraryService2";
/**
- * Session for the media library service.
+ * Session for the {@link MediaLibraryService2}. Build this object with
+ * {@link MediaLibrarySessionBuilder} and return in {@link #onCreateSession(String)}.
*/
public static class MediaLibrarySession extends MediaSession2 {
private final MediaLibrarySessionProvider mProvider;
@@ -101,6 +101,9 @@
}
}
+ /**
+ * Callback for the {@link MediaLibrarySession}.
+ */
public static class MediaLibrarySessionCallback extends MediaSession2.SessionCallback {
public MediaLibrarySessionCallback(Context context) {
@@ -200,6 +203,8 @@
/**
* Builder for {@link MediaLibrarySession}.
*/
+ // Override all methods just to show them with the type instead of generics in Javadoc.
+ // This workarounds javadoc issue described in the MediaSession2.BuilderBase.
public class MediaLibrarySessionBuilder extends BuilderBase<MediaLibrarySession,
MediaLibrarySessionBuilder, MediaLibrarySessionCallback> {
public MediaLibrarySessionBuilder(
@@ -210,6 +215,38 @@
context, (MediaLibrarySessionBuilder) instance, player, callbackExecutor,
callback));
}
+
+ @Override
+ public MediaLibrarySessionBuilder setVolumeProvider(
+ @Nullable VolumeProvider2 volumeProvider) {
+ return super.setVolumeProvider(volumeProvider);
+ }
+
+ @Override
+ public MediaLibrarySessionBuilder setRatingType(int type) {
+ return super.setRatingType(type);
+ }
+
+ @Override
+ public MediaLibrarySessionBuilder setSessionActivity(@Nullable PendingIntent pi) {
+ return super.setSessionActivity(pi);
+ }
+
+ @Override
+ public MediaLibrarySessionBuilder setId(String id) {
+ return super.setId(id);
+ }
+
+ @Override
+ public MediaLibrarySessionBuilder setSessionCallback(
+ @NonNull Executor executor, @NonNull MediaLibrarySessionCallback callback) {
+ return super.setSessionCallback(executor, callback);
+ }
+
+ @Override
+ public MediaLibrarySession build() {
+ return super.build();
+ }
}
@Override
@@ -229,7 +266,7 @@
* This method will be called on the main thread.
*
* @param sessionId session id written in the AndroidManifest.xml.
- * @return a new browser session
+ * @return a new library session
* @see MediaLibrarySessionBuilder
* @see #getSession()
* @throws RuntimeException if returned session is invalid
diff --git a/media/java/android/media/MediaSession2.java b/media/java/android/media/MediaSession2.java
index 8bde3d1..ae2649a 100644
--- a/media/java/android/media/MediaSession2.java
+++ b/media/java/android/media/MediaSession2.java
@@ -580,8 +580,20 @@
};
/**
- * Base builder class for MediaSession2 and its subclass.
- *
+ * Base builder class for MediaSession2 and its subclass. Any change in this class should be
+ * also applied to the subclasses {@link MediaSession2.Builder} and
+ * {@link MediaLibraryService2.MediaLibrarySessionBuilder}.
+ * <p>
+ * APIs here should be package private, but should have documentations for developers.
+ * Otherwise, javadoc will generate documentation with the generic types such as follows.
+ * <pre>U extends BuilderBase<T, U, C> setSessionCallback(Executor executor, C callback)</pre>
+ * <p>
+ * This class is hidden to prevent from generating test stub, which fails with
+ * 'unexpected bound' because it tries to auto generate stub class as follows.
+ * <pre>abstract static class BuilderBase<
+ * T extends android.media.MediaSession2,
+ * U extends android.media.MediaSession2.BuilderBase<
+ * T, U, C extends android.media.MediaSession2.SessionCallback>, C></pre>
* @hide
*/
static abstract class BuilderBase
@@ -601,7 +613,7 @@
*
* @param volumeProvider The provider that will handle volume changes. Can be {@code null}.
*/
- public U setVolumeProvider(@Nullable VolumeProvider2 volumeProvider) {
+ U setVolumeProvider(@Nullable VolumeProvider2 volumeProvider) {
mProvider.setVolumeProvider_impl(volumeProvider);
return (U) this;
}
@@ -619,7 +631,7 @@
* <li>{@link Rating2#RATING_THUMB_UP_DOWN}</li>
* </ul>
*/
- public U setRatingType(@Rating2.Style int type) {
+ U setRatingType(@Rating2.Style int type) {
mProvider.setRatingType_impl(type);
return (U) this;
}
@@ -631,7 +643,7 @@
*
* @param pi The intent to launch to show UI for this session.
*/
- public U setSessionActivity(@Nullable PendingIntent pi) {
+ U setSessionActivity(@Nullable PendingIntent pi) {
mProvider.setSessionActivity_impl(pi);
return (U) this;
}
@@ -646,7 +658,7 @@
* @throws IllegalArgumentException if id is {@code null}
* @return
*/
- public U setId(@NonNull String id) {
+ U setId(@NonNull String id) {
mProvider.setId_impl(id);
return (U) this;
}
@@ -658,7 +670,7 @@
* @param callback session callback.
* @return
*/
- public U setSessionCallback(@NonNull @CallbackExecutor Executor executor,
+ U setSessionCallback(@NonNull @CallbackExecutor Executor executor,
@NonNull C callback) {
mProvider.setSessionCallback_impl(executor, callback);
return (U) this;
@@ -671,7 +683,7 @@
* @throws IllegalStateException if the session with the same id is already exists for the
* package.
*/
- public T build() {
+ T build() {
return mProvider.build_impl();
}
}
@@ -682,13 +694,44 @@
* Any incoming event from the {@link MediaController2} will be handled on the thread
* that created session with the {@link Builder#build()}.
*/
- // TODO(jaewan): Add setRatingType()
- // TODO(jaewan): Add setSessionActivity()
+ // Override all methods just to show them with the type instead of generics in Javadoc.
+ // This workarounds javadoc issue described in the MediaSession2.BuilderBase.
public static final class Builder extends BuilderBase<MediaSession2, Builder, SessionCallback> {
public Builder(Context context, @NonNull MediaPlayerInterface player) {
super((instance) -> ApiLoader.getProvider(context).createMediaSession2Builder(
context, (Builder) instance, player));
}
+
+ @Override
+ public Builder setVolumeProvider(@Nullable VolumeProvider2 volumeProvider) {
+ return super.setVolumeProvider(volumeProvider);
+ }
+
+ @Override
+ public Builder setRatingType(@Rating2.Style int type) {
+ return super.setRatingType(type);
+ }
+
+ @Override
+ public Builder setSessionActivity(@Nullable PendingIntent pi) {
+ return super.setSessionActivity(pi);
+ }
+
+ @Override
+ public Builder setId(@NonNull String id) {
+ return super.setId(id);
+ }
+
+ @Override
+ public Builder setSessionCallback(@NonNull Executor executor,
+ @Nullable SessionCallback callback) {
+ return super.setSessionCallback(executor, callback);
+ }
+
+ @Override
+ public MediaSession2 build() {
+ return super.build();
+ }
}
/**