From 9b4a3701d49092209b4e86748bd3aa58acc4036f Mon Sep 17 00:00:00 2001
From: olly <olly@google.com>
Date: Wed, 13 Nov 2019 03:03:34 +0000
Subject: [PATCH] Clean up ExoMediaDrm reference counting documentation

PiperOrigin-RevId: 280106092
---
 .../android/exoplayer2/drm/ExoMediaDrm.java   | 41 +++++++++++--------
 .../exoplayer2/drm/FrameworkMediaDrm.java     |  6 +--
 2 files changed, 27 insertions(+), 20 deletions(-)

diff --git a/library/core/src/main/java/com/google/android/exoplayer2/drm/ExoMediaDrm.java b/library/core/src/main/java/com/google/android/exoplayer2/drm/ExoMediaDrm.java
index 1d0e15e81c..b6ee644842 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/drm/ExoMediaDrm.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/drm/ExoMediaDrm.java
@@ -31,6 +31,16 @@ import java.util.UUID;
 
 /**
  * Used to obtain keys for decrypting protected media streams. See {@link android.media.MediaDrm}.
+ *
+ * <h3>Reference counting</h3>
+ *
+ * <p>Access to an instance is managed by reference counting, where {@link #acquire()} increments
+ * the reference count and {@link #release()} decrements it. When the reference count drops to 0
+ * underlying resources are released, and the instance cannot be re-used.
+ *
+ * <p>Each new instance has an initial reference count of 1. Hence application code that creates a
+ * new instance does not normally need to call {@link #acquire()}, and must call {@link #release()}
+ * when the instance is no longer required.
  */
 public interface ExoMediaDrm<T extends ExoMediaCrypto> {
 
@@ -38,26 +48,25 @@ public interface ExoMediaDrm<T extends ExoMediaCrypto> {
   interface Provider<T extends ExoMediaCrypto> {
 
     /**
-     * Returns an {@link ExoMediaDrm} instance with acquired ownership for the DRM scheme identified
-     * by the given UUID.
-     *
-     * <p>Each call to this method must have a corresponding call to {@link ExoMediaDrm#release()}
-     * to ensure correct resource management.
+     * Returns an {@link ExoMediaDrm} instance with an incremented reference count. When the caller
+     * no longer needs to use the instance, it must call {@link ExoMediaDrm#release()} to decrement
+     * the reference count.
      */
     ExoMediaDrm<T> acquireExoMediaDrm(UUID uuid);
   }
 
   /**
-   * {@link Provider} implementation which provides an {@link ExoMediaDrm} instance owned by the
-   * app.
+   * Provides an {@link ExoMediaDrm} instance owned by the app.
    *
-   * <p>This provider should be used to manually handle {@link ExoMediaDrm} resources.
+   * <p>Note that when using this provider the app will have instantiated the {@link ExoMediaDrm}
+   * instance, and remains responsible for calling {@link ExoMediaDrm#release()} on the instance
+   * when it's no longer being used.
    */
   final class AppManagedProvider<T extends ExoMediaCrypto> implements Provider<T> {
 
     private final ExoMediaDrm<T> exoMediaDrm;
 
-    /** Creates an instance, which provides the given {@link ExoMediaDrm}. */
+    /** Creates an instance that provides the given {@link ExoMediaDrm}. */
     public AppManagedProvider(ExoMediaDrm<T> exoMediaDrm) {
       this.exoMediaDrm = exoMediaDrm;
     }
@@ -269,17 +278,17 @@ public interface ExoMediaDrm<T extends ExoMediaCrypto> {
   Map<String, String> queryKeyStatus(byte[] sessionId);
 
   /**
-   * Acquires ownership over this instance, which must be released by calling {@link #release()}.
+   * Increments the reference count. When the caller no longer needs to use the instance, it must
+   * call {@link #release()} to decrement the reference count.
+   *
+   * <p>A new instance will have an initial reference count of 1, and therefore it is not normally
+   * necessary for application code to call this method.
    */
   void acquire();
 
   /**
-   * Releases ownership of this instance. If a call to this method causes this instance to have no
-   * acquired ownerships, releases the underlying resources.
-   *
-   * <p>Callers of this method must not make any further use of this instance.
-   *
-   * @see MediaDrm#release()
+   * Decrements the reference count. If the reference count drops to 0 underlying resources are
+   * released, and the instance cannot be re-used.
    */
   void release();
 
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/drm/FrameworkMediaDrm.java b/library/core/src/main/java/com/google/android/exoplayer2/drm/FrameworkMediaDrm.java
index d040552638..8ac92b093c 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/drm/FrameworkMediaDrm.java
+++ b/library/core/src/main/java/com/google/android/exoplayer2/drm/FrameworkMediaDrm.java
@@ -55,8 +55,6 @@ public final class FrameworkMediaDrm implements ExoMediaDrm<FrameworkMediaCrypto
    * {@link ExoMediaDrm.Provider} that returns a new {@link FrameworkMediaDrm} for the requested
    * UUID. Returns a {@link DummyExoMediaDrm} if the protection scheme identified by the given UUID
    * is not supported by the device.
-   *
-   * <p>This provider should be used to make ExoPlayer handle {@link ExoMediaDrm} resources.
    */
   public static final Provider<FrameworkMediaCrypto> DEFAULT_PROVIDER =
       uuid -> {
@@ -78,8 +76,8 @@ public final class FrameworkMediaDrm implements ExoMediaDrm<FrameworkMediaCrypto
   private int referenceCount;
 
   /**
-   * Creates an instance with an {@link #acquire() acquired reference} for the specified scheme
-   * UUID. {@link #release()} must be called when the instance is no longer required.
+   * Creates an instance with an initial reference count of 1. {@link #release()} must be called on
+   * the instance when it's no longer required.
    *
    * @param uuid The scheme uuid.
    * @return The created instance.