Merge "Document MediaPlayer.release to be mandatory"

media/java/android/media/MediaPlayer.java

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