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

[Alexander Matveev]

Hi Richard,

Yes, DISPOSED is only ever reached if dispose() is called and DISPOSED 
status will be set before dispose() returns.

Thanks,
Alexander

> That seems good. So DISPOSED is only ever reached if the developer explicitly calls dispose (that is, it has nothing to do with whether the native resources have been released, but rather, whether the dispose() method was called).
>
> I like that.
>
> Richard
>
> On Mar 7, 2013, at 4:14 PM, Alexander Matveev <alexander.matveev at oracle.com> wrote:
>
>> 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