[API Review]: RT-28817 - Add explicit dispose() method to MediaPlayer

[Alexander Matveev]

Hi Richard,

To let developers know that MediaPlayer is disposed, I will suggest to 
add new status to MediaPlayer called DISPOSED.
http://docs.oracle.com/javafx/2/api/javafx/scene/media/MediaPlayer.Status.html
Transition to this state will be allowed from any other states that we 
have. I will NOT add to MediaPlayer runnable onDisposed similar to 
onReady or onPlaying, since disposed in synchronous. Also, keeping 
MediaPlayer in any other valid status after disposed will be confusing 
for developers.

We have HALTED status that similar to DISPOSED, except DISPOSED is 
triggered by user. All behavior in DISPOSED status will be same or 
similar as in HALTED status, since in both cases MediaPlayer is unusable.

Thanks,
Alexander

> Hi Alexander,
>
> Sounds good. For reference, Skin also has a method called 'dispose' so I think we have the right name here. Note:
>
> http://docs.oracle.com/javafx/2/api/javafx/scene/control/Skin.html
>
> Be sure to spec in the JavaDoc for MediaPlayer & MediaView what it means when a MediaPlayer has been disposed. For example, if I dispose a MediaPlayer and then set it on a MediaView, what happens? I would suggest that nothing bad should happen (along the lines of Skin). However maybe we want to have an isDisposed method on MediaPlayer so developers can inspect a media player and know whether they should create a new one (in which case having a read only disposedProperty is also a good idea). All methods on the MediaPlayer need to specify their behavior when invoked on a disposed MediaPlayer.
>
> I think you're on the right path that dispose() can be called no matter what state the media player is in. Be sure to specify what state the player will be in after dispose is called. Also we need to have tests that ensure that the state transitions work correctly.
>
> Thanks!
> Richard
>
> On Mar 6, 2013, at 3:07 PM, Alexander Matveev <alexander.matveev at oracle.com> wrote:
>
>> Hi all,
>>
>> Explicit dispose() method is needed to free native resources used by MediaPlayer. Garbage collector is not reliable enough to free native resources fast enough, thus when MediaPlayers are created fast enough we may run out of native memory. Normally, user does not need to call dispose() method on MediaPlayer if application does not create them often. After dispose() is called MediaPlayer cannot be used again and should be disregarded. Media and MediaView associated with disposed MediaPlayer can be reused. Dispose() will be valid in any states. For example, when player is playing call to dispose() will stop playback and release all resources.
>>
>> JIRA:
>> http://javafx-jira.kenai.com/browse/RT-28817
>>
>> Thanks,
>> Alexander