public interface Player extends Controllable
Player
controls the rendering of time based media data. It
provides the methods to manage the Player
's life cycle, controls
the playback progress, obtains the presentation components, controls and
provides the means to synchronize with other Players
.
APlayer
can be created from one of theManager
'screatePlayer
methods. After thePlayer
is created, callingstart()
will start the playback as soon as possible. The method will return when the playback is started. The playback will continue in the background and will stop automatically when the end of media is reached.Simple playback example illustrates this.
APlayer
has five states:UNREALIZED
,REALIZED
,PREFETCHED
,STARTED
, andCLOSED
.The purpose of these life-cycle states is to provide programmatic control over potentially time-consuming operations. For example, when a
Player
is first constructed, it's in the UNREALIZED state. Transitioned from UNREALIZED to REALIZED, thePlayer
performs the communication necessary to locate all of the resources it needs to function (such as communicating with a server or a file system). Therealize()
method allows an application to initiate this potentially time-consuming process at an appropriate time.Typically, a
Player
moves from the UNREALIZED state to the REALIZED state, then to the PREFETCHED state, and finally on to the STARTED state.A
Player
stops when it reaches the end of media; when its stop time is reached; or when thestop()
method is invoked. When that happens, thePlayer
moves from the STARTED state back to the PREFETCHED state. It is then ready to repeat the cycle.To use a
Player
, you must set up parameters to manage its movement through these life-cycle states and then move it through the states using thePlayer
's state transition methods.
This section describes the semantics of each of thePlayer
states.UNREALIZED State
APlayer
starts in the UNREALIZED state. An unrealizedPlayer
does not have enough information to acquire all the resources it needs to function.The following methods must not be used when the
Player
is in the UNREALIZED state.Otherwise an
getContentType
setTimeBase
getTimeBase
setMediaTime
getControls
getControl
IllegalStateException
will be thrown.The
realize()
method transitions thePlayer
from the UNREALIZED state to the REALIZED state.REALIZED State
APlayer
is in the REALIZED state when it has obtained the information required to acquire the media resources. Realizing aPlayer
can be a resource and time consuming process. ThePlayer
may have to communicate with a server, read a file, or interact with a set of objects.Although a realized
Player
does not have to acquire any resources, it is likely to have acquired all of the resources it needs except those that imply exclusive use of a scarce system resource, such as an audio device.Normally, a
Player
moves from the UNREALIZED state to the REALIZED state. Afterrealize()
has been invoked on aPlayer
, the only way it can return to the UNREALIZED state is ifdeallocate()
is invoked beforerealize()
is completed.Once a
Player
reaches the REALIZED state, it never returns to the UNREALIZED state. It remains in one of four states: REALIZED, PREFETCHED, STARTED or CLOSED.PREFETCHED State
Once realized, aPlayer
may still need to perform a number of time-consuming tasks before it is ready to be started. For example, it may need to acquire scarce or exclusive resources, fill buffers with media data, or perform other start-up processing. Callingprefetch()
on thePlayer
carries out these tasks.Once a
Player
is in the PREFETCHED state, it may be started. Prefetching reduces the startup latency of aPlayer
to the minimum possible value.When a started
Player
stops, it returns to the PREFETCHED state.STARTED State
Once prefetched, aPlayer
can enter the STARTED state by calling thestart()
method. A STARTEDPlayer
means thePlayer
is running and processing data. APlayer
returns to the PREFETCHED state when it stops, because thestop()
method was invoked, it has reached the end of the media, or its stop time.When the
Player
moves from the PREFETCHED to the STARTED state, it posts aSTARTED
event. When it moves from the STARTED state to the PREFETCHED state, it posts aSTOPPED
orEND_OF_MEDIA
event depending on the reason it stopped.The following methods must not be used when the
Player
is in the STARTED state:Otherwise, an
setTimeBase
setLoopCount
IllegalStateException
will be thrown.CLOSED state
CallingTheclose()
on thePlayer
puts it in the CLOSED state. In the CLOSED state, thePlayer
has released most of its resources and must not be used again.Player
's five states and the state transition methods are summarized in the following diagram:
Player
events asynchronously deliver information about thePlayer
's state changes and other relevant information from thePlayer
'sControl
s.To receive events, an object must implement the
PlayerListener
interface and use theaddPlayerListener
method to register its interest in aPlayer
's events. AllPlayer
events are posted to each registered listener.The events are guaranteed to be delivered in the order that the actions representing the events occur. For example, if a
Player
stops shortly after it starts because it is playing back a very short media file, theSTARTED
event must always precede theEND_OF_MEDIA
event.An
ERROR
event may be sent any time an irrecoverable error has occured. When that happens, thePlayer
is in the CLOSED state.The
Player
event mechanism is extensible and somePlayers
define events other than the ones described here. For a list of pre-defined player events, check thePlayerListener
interface.
Theprefetch()
method is used to acquire scarce or exclusive resources such as the audio device. Conversely, thedeallocate()
method is used to release the scarce or exclusive resources. By using these two methods, an application can programmatically manage thePlayer
's resources.For example, in an implementation with an exclusive audio device, to alternate the audio playback of multiple
Player
s, an application can selectively deallocate and prefetch individualPlayer
s.
TheTimeBase
of aPlayer
provides the basic measure of time for thePlayer
to synchronize its media playback. EachPlayer
must provide one defaultTimeBase
. ThegetTimeBase
method can be used to retrieve that.Setting a different
TimeBase
on aPlayer
instructs thePlayer
to synchronize its playback rate according to the givenTimeBase
.Two
Player
s can be synchronized by getting theTimeBase
from onePlayer
and setting that on the secondPlayer
.However, not all
Player
s support using a differentTimeBase
other than its own. In such cases, aMediaException
will be thrown whensetTimeBase
is called.
Player
implementsControllable
which provides extra controls via some type-specificControl
interfaces.getControl
andgetControls
cannot be called when thePlayer
is in the UNREALIZED or CLOSED state. AnIllegalStateException
will be thrown.
try { Player p = Manager.createPlayer("http://abc.wav"); p.start(); } catch (MediaException pe) { } catch (IOException ioe) { } |
Modifier and Type | Field and Description |
---|---|
static int |
CLOSED
The state of the
Player indicating that the Player is closed. |
static int |
PREFETCHED
The state of the
Player indicating that it has acquired all
the resources to begin playing. |
static int |
REALIZED
The state of the
Playe r indicating that it has acquired the
required information but not the resources to function. |
static int |
STARTED
The state of the
Player indicating that the Player has
already started. |
static long |
TIME_UNKNOWN
The returned value indicating that the requested time is unknown.
|
static int |
UNREALIZED
The state of the
Player indicating that it has not acquired
the required information and resources to function. |
Modifier and Type | Method and Description |
---|---|
void |
addPlayerListener(PlayerListener playerListener)
Add a
PlayerListener for this player. |
void |
close()
Close the
Player and release its resources. |
void |
deallocate()
Release the scarce or exclusive resources like the audio device acquired
by the
Player . |
java.lang.String |
getContentType()
Get the content type of the media that's being played back by this
Player . |
long |
getDuration()
Get the duration of the media.
|
long |
getMediaTime()
Gets this
Player 's current media time. |
int |
getState()
Gets the current state of this
Player . |
TimeBase |
getTimeBase()
Gets the
TimeBase that this Player is using. |
void |
prefetch()
Acquires the scarce and exclusive resources and processes as much data as
necessary to reduce the start latency.
|
void |
realize()
Constructs portions of the
Player without acquiring the
scarce and exclusive resources. |
void |
removePlayerListener(PlayerListener playerListener)
Remove a
PlayerListener for this player. |
void |
setLoopCount(int count)
Set the number of times the
Player will loop and play the content. |
long |
setMediaTime(long now)
Sets the
Player 's media time. |
void |
setTimeBase(TimeBase master)
Sets the
TimeBase for this Player . |
void |
start()
Starts the
Player as soon as possible. |
void |
stop()
Stops the
Playe r. |
getControl, getControls
static final int UNREALIZED
Player
indicating that it has not acquired
the required information and resources to function.
Value 100
is assigned to UNREALIZED
.
static final int REALIZED
Playe
r indicating that it has acquired the
required information but not the resources to function.
Value 200
is assigned to REALIZED
.
static final int PREFETCHED
Player
indicating that it has acquired all
the resources to begin playing.
Value 300
is assigned to PREFETCHED
.
static final int STARTED
Player
indicating that the Player has
already started.
Value 400
is assigned to STARTED
.
static final int CLOSED
Player
indicating that the Player is closed.
Value 0
is assigned to CLOSED
.
static final long TIME_UNKNOWN
Value -1
is assigned to TIME_UNKNOWN
.
void realize() throws MediaException
Player
without acquiring the
scarce and exclusive resources. This may include examining media data and
may take some time to complete.
When realize
completes successfully, the Player is
in the REALIZED state.
If realize
is called when the Player
is in the
REALIZED, PREFETCHTED or STARTED state, the request
will be ignored.
java.lang.IllegalStateException
- if the Player
is in the
CLOSED statejava.lang.SecurityException
- if the caller does not have security permission
to realize the Player
{@link
- MediaException} if the Player
cannot be realizedMediaException
void prefetch() throws MediaException
When prefetch
completes successfully, the Player
is in the PREFETCHED state.
If prefetch
is called when the Player
is in the
UNREALIZED state, it will implicitly call realize()
.
If prefetch
is called when the Player
is already
in the PREFETCHED state, the Player
may still process
data necessary to reduce the start latency. This is to guarantee that start
latency can be maintained at a minimum.
If prefetch
is called when the Player
is in the
STARTED state, the request will be ignored.
If the Player
cannot obtain all of the resources it needs,
it throws a MediaException
. When that happens, the Player
will not be able to start. However, prefetch
may be called
again when the needed resource is later released perhaps by another
Player
or application.
java.lang.IllegalStateException
- if the Player
is in the
CLOSED statejava.lang.SecurityException
- if the caller does not have security permission
to prefetch the Player
{@link
- MediaException} if the Player
cannot be prefetchedMediaException
void start() throws MediaException
Player
as soon as possible. If the Player
was previously stopped by calling stop()
, it will resume playback
from where it was previously stopped. If the Player
has
reached the end of media, calling start()
will automatically
start the playback from the start of the media.
When start
returns successfully, the Player
must have been started and a STARTED
event
will be delivered to the registered PlayerListeners
.
However, the Player
is not guaranteed to be in the STARTED
state. The Player
may have already stopped (in the PREFETCHED
state) because the media has 0
or a very short duration.
If start
is called when the Player
is in the
UNREALIZED or REALIZED state, it will implicitly call
prefetch()
.
If startPlayer
is in the
STARTED state, the request will be ignored.
java.lang.IllegalStateException
- if the Player
is in the
CLOSED statejava.lang.SecurityException
- if the caller does not have security permission
to start the Player
{@link
- MediaException} if the Player
cannot be startedMediaException
void stop() throws MediaException
Playe
r. It will pause the playback at the current
media time.
When stop
returns, the Player
is in the
PREFETCHED state. A STOPPED
event
will be delivered to the registered PlayerListeners
.
If stop
is called on a stopped Player
, the
request is ignored.
java.lang.IllegalStateException
- if the Player
is in the
CLOSED stateMediaException
- if the Player
cannot be stoppedvoid deallocate()
Player
.
When deallocate
returns, the Player
is in the
UNREALIZED or REALIZED state.
If the Player
is blocked at the realize()
call while
realizing, calling deallocate
unblocks the realize
call and returns the Player
to the UNREALIZED state.
Otherwise, calling deallocate
returns the Player
to the REALIZED state.
If deallocate
is called when the Player
is in
the UNREALIZED or REALIZED state, the request is ignored.
If the Player
is STARTED
when
deallocate
is called, deallocate
will
implicitly call stop()
on the Player
.
java.lang.IllegalStateException
- if the Player
is in the
CLOSED statevoid close()
Player
and release its resources.
When the method returns, the Player
is in the CLOSED
state and can no longer be used. A CLOSED
event will be delivered to the registered
PlayerListeners
.
If close
is called on a closed Player
the
request is ignored.
void setTimeBase(TimeBase master) throws MediaException
TimeBase
for this Player
.
A Player
has a default TimeBase
that is
determined by the implementation. To reset a Player
to its
default TimeBase
, call setTimeBase(null)
.
master
- the new TimeBase
or null
to reset
the Player
to its default TimeBase
java.lang.IllegalStateException
- if the Player
is in the
UNREALIZED, STARTED or CLOSED state{@link
- MediaException} if the specified TimeBase
cannot be set on the Player
MediaException
getTimeBase()
TimeBase getTimeBase()
TimeBase
that this Player
is using.TimeBase
that this Player
is usingjava.lang.IllegalStateException
- if the Player
is in the
UNREALIZED or CLOSED statesetTimeBase(javax.microedition.media.TimeBase)
long setMediaTime(long now) throws MediaException
Player
's media time.
For some media types, setting the media time may not be very accurate. The returned value will indicate the actual media time set.
Setting the media time to negative values will effectively set the media time to zero. Setting the media time to beyond the duration of the media will set the time to the end of media.
There are some media types that cannot support the setting of media time.
Calling setMediaTime
will throw a MediaException
in
those cases.
now
- the new media time in microsecondsjava.lang.IllegalStateException
- if the Player
is in the
UNREALIZED or CLOSED state{@link
- MediaException} if the media time cannot be setMediaException
getMediaTime()
long getMediaTime()
Player
's current media time.
getMediaTime
may return TIME_UNKNOWN
to indicate
that the media time cannot be determined. However, once
getMediaTime
returns a known time (time not equals to
TIME_UNKNOWN
), subsequent calls to getMediaTime
must not return TIME_UNKNOWN
.
TIME_UNKNOWN
java.lang.IllegalStateException
- if the Player
is in the
CLOSED statesetMediaTime(long)
int getState()
Player
. The possible states are:
UNREALIZED, REALIZED, PREFETCHED, STARTED,
and CLOSED.Player
's current statelong getDuration()
If the duration cannot be determined (for example, the Player
is presenting live media) getDuration
returns
TIME_UNKNOWN
.
TIME_UNKNOWN
java.lang.IllegalStateException
- if the Player
is in the
CLOSED statejava.lang.String getContentType()
Player
.
See content type for the syntax of the content type returned.
Player
java.lang.IllegalStateException
- if the Player
is in the
UNREALIZED or CLOSED statevoid setLoopCount(int count)
Player
will loop and play the content.
By default, the loop count is one. That is, once started, the Player will start playing from the current media time to the end of media once.
If the loop count is set to N
where N
is bigger
than one, starting the Player
will start playing the content
from the current media time to the end of media. It will then loop back
to the beginning of the content (media time zero) and play till the end
of the media. The number of times it will loop to the beginning and play
to the end of media will be N-1
.
Setting the loop count to 0
is invalid. An
IllegalArgumentException
will be thrown then.
Setting the loop count to -1
will loop and play the content
indefinitely.
If the Player
is stopped before the preset loop count is
reached either because stop()
is called, calling start()
again will resume the looping playback from where it was stopped until it
fully reaches the preset loop count.
An END_OF_MEDIA
event will be posted
every time the Player
reaches the end of media. If the
Player
loops back to the beginning and starts playing
again because it has not completed the loop count, a
STARTED
event will be posted.
count
- indicates the number of times the content will be played.
1
is the default. 0
is invalid.
-1
indicates looping indefintelyjava.lang.IllegalArgumentException
- if the given count is invalidjava.lang.IllegalStateException
- if the Player
is in the
STARTED or CLOSED statevoid addPlayerListener(PlayerListener playerListener)
PlayerListener
for this player.playerListener
- the listener to add. If null
is used,
the request will be ignoredjava.lang.IllegalStateException
- if the Player
is in the
CLOSED stateremovePlayerListener(javax.microedition.media.PlayerListener)
void removePlayerListener(PlayerListener playerListener)
PlayerListener
for this player.playerListener
- the listener to remove. If null
is used
or the given playerListener
is not a listener for
this Player
, the request will be ignored.java.lang.IllegalStateException
- if the Player
is in the
CLOSED stateaddPlayerListener(javax.microedition.media.PlayerListener)
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.