Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 35887bc2 authored by Santiago Seifert's avatar Santiago Seifert
Browse files

Document MediaPlayer.release to be mandatory 

Finalizers and cleaners are discouraged java practices. Concretely,
counting on finalize to release MediaPlayer violates the requirement
of single-threaded use in the class javadoc.

Bug: 182712404
Bug: 201440544
Test: N/A. Javadoc only change.
Change-Id: I920860a8ff49d0a6bd9cef321f69269194d5fd39
parent 1c0e4ae8

media/java/android/media/MediaPlayer.java

+26 −42
Original line number Diff line number Diff line
@@ -158,18 +158,10 @@ import java.util.concurrent.Executor; 
 *         the user supplied callback method OnErrorListener.onError() will be

 *         invoked by the internal player engine and the object will be

 *         transfered to the <em>Error</em> state. </li>

 *         <li>It is also recommended that once

 *         a MediaPlayer object is no longer being used, call {@link #release()} immediately

 *         so that resources used by the internal player engine associated with the

 *         MediaPlayer object can be released immediately. Resource may include

 *         singleton resources such as hardware acceleration components and

 *         failure to call {@link #release()} may cause subsequent instances of

 *         MediaPlayer objects to fallback to software implementations or fail

 *         altogether. Once the MediaPlayer

 *         object is in the <em>End</em> state, it can no longer be used and

 *         there is no way to bring it back to any other state. </li>

 *         <li>Furthermore,

 *         the MediaPlayer objects created using <code>new</code> is in the

 *         <li>You must call {@link #release()} once you have finished using an instance to release

 *         acquired resources, such as memory and codecs. Once you have called {@link #release}, you

 *         must no longer interact with the released instance.

 *         <li>MediaPlayer objects created using <code>new</code> is in the

 *         <em>Idle</em> state, while those created with one

 *         of the overloaded convenient <code>create</code> methods are <em>NOT</em>

 *         in the <em>Idle</em> state. In fact, the objects are in the <em>Prepared</em>
@@ -407,7 +399,7 @@ import java.util.concurrent.Executor; 
 * <tr><td>release </p></td>

 *     <td>any </p></td>

 *     <td>{} </p></td>

 *     <td>After {@link #release()}, the object is no longer available. </p></td></tr>

 *     <td>After {@link #release()}, you must not interact with the object. </p></td></tr>

 * <tr><td>reset </p></td>

 *     <td>{Idle, Initialized, Prepared, Started, Paused, Stopped,

 *         PlaybackCompleted, Error}</p></td>
@@ -657,11 +649,13 @@ public class MediaPlayer extends PlayerBase 
    private ProvisioningThread mDrmProvisioningThread;



    /**

     * Default constructor. Consider using one of the create() methods for

     * synchronously instantiating a MediaPlayer from a Uri or resource.

     * <p>When done with the MediaPlayer, you should call  {@link #release()},

     * to free the resources. If not released, too many MediaPlayer instances may

     * result in an exception.</p>

     * Default constructor.

     *

     * <p>Consider using one of the create() methods for synchronously instantiating a MediaPlayer

     * from a Uri or resource.

     *

     * <p>You must call {@link #release()} when you are finished using the instantiated instance.

     * Doing so frees any resources you have previously acquired.

     */

    public MediaPlayer() {

        this(AudioSystem.AUDIO_SESSION_ALLOCATE);
@@ -873,9 +867,10 @@ public class MediaPlayer extends PlayerBase 
    /**

     * Convenience method to create a MediaPlayer for a given Uri.

     * On success, {@link #prepare()} will already have been called and must not be called again.

     * <p>When done with the MediaPlayer, you should call  {@link #release()},

     * to free the resources. If not released, too many MediaPlayer instances will

     * result in an exception.</p>

     *

     * <p>You must call {@link #release()} when you are finished using the created instance. Doing

     * so frees any resources you have previously acquired.

     *

     * <p>Note that since {@link #prepare()} is called automatically in this method,

     * you cannot change the audio

     * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
@@ -892,9 +887,10 @@ public class MediaPlayer extends PlayerBase 
    /**

     * Convenience method to create a MediaPlayer for a given Uri.

     * On success, {@link #prepare()} will already have been called and must not be called again.

     * <p>When done with the MediaPlayer, you should call  {@link #release()},

     * to free the resources. If not released, too many MediaPlayer instances will

     * result in an exception.</p>

     *

     * <p>You must call {@link #release()} when you are finished using the created instance. Doing

     * so frees any resources you have previously acquired.

     *

     * <p>Note that since {@link #prepare()} is called automatically in this method,

     * you cannot change the audio

     * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
@@ -955,9 +951,10 @@ public class MediaPlayer extends PlayerBase 
    /**

     * Convenience method to create a MediaPlayer for a given resource id.

     * On success, {@link #prepare()} will already have been called and must not be called again.

     * <p>When done with the MediaPlayer, you should call  {@link #release()},

     * to free the resources. If not released, too many MediaPlayer instances will

     * result in an exception.</p>

     *

     * <p>You must call {@link #release()} when you are finished using the created instance. Doing

     * so frees any resources you have previously acquired.

     *

     * <p>Note that since {@link #prepare()} is called automatically in this method,

     * you cannot change the audio

     * session ID (see {@link #setAudioSessionId(int)}) or audio attributes
@@ -2157,21 +2154,8 @@ public class MediaPlayer extends PlayerBase 


    /**

     * Releases resources associated with this MediaPlayer object.

     * It is considered good practice to call this method when you're

     * done using the MediaPlayer. In particular, whenever an Activity

     * of an application is paused (its onPause() method is called),

     * or stopped (its onStop() method is called), this method should be

     * invoked to release the MediaPlayer object, unless the application

     * has a special need to keep the object around. In addition to

     * unnecessary resources (such as memory and instances of codecs)

     * being held, failure to call this method immediately if a

     * MediaPlayer object is no longer needed may also lead to

     * continuous battery consumption for mobile devices, and playback

     * failure for other applications if no multiple instances of the

     * same codec are supported on a device. Even if multiple instances

     * of the same codec are supported, some performance degradation

     * may be expected when unnecessary multiple instances are used

     * at the same time.

     *

     * <p>You must call this method once the instance is no longer required.

     */

    public void release() {

        baseRelease();