sjs/media
1
0
Fork 0
mirror of https://github.com/samsonjs/media.git synced 2026-03-26 09:35:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Clean up ExoMediaDrm reference counting documentation

Browse source 
PiperOrigin-RevId: 280106092
This commit is contained in:
olly 2019-11-13 03:03:34 +00:00 committed by Oliver Woodman
parent 20ab05103b
commit 9b4a3701d4
2 changed files with 27 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
library/core/src/main/java/com/google/android/exoplayer2/drm/ExoMediaDrm.java
View file

@ -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();

6
library/core/src/main/java/com/google/android/exoplayer2/drm/FrameworkMediaDrm.java
View file

@ -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.