javax.microedition.media
Interface Player

Player controls the rendering of time based media data.
It provides the methods to manage the Player's life
cycle, controls the playback progress and obtains the presentation
components.

Simple Playback

A Player can be created from one of the
Manager's createPlayer methods.
After the Player is created,
calling start 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.

Player Life Cycle

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, the
Player
performs the communication necessary to locate all of the resources
it needs to function (such as communicating with a server
or a file system).
The realize 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;
or when the stop method is invoked.
When that happens, the Player 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 the Player's
state transition methods.

Player States

This section describes the semantics of each of the Player
states.

UNREALIZED State

A Player starts in
the UNREALIZED state.
An unrealized Player
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.

getContentType

setMediaTime

getControls

getControl

An IllegalStateException will be thrown.

The realize method transitions
the Player from the UNREALIZED state to the
REALIZED state.

REALIZED State

A Player is in the REALIZED state when it
has obtained
the information required to acquire the media resources.
Realizing a Player can be a resource and
time consuming process.
The Player 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.
After realize has been
invoked on a Player,
the only way it can return
to the UNREALIZED state is if
deallocate is
invoked before realize 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, a Player 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.
Calling
prefetch
on the Player carries
out these tasks.

Once a Player is in the PREFETCHED state, it may
be started.
Prefetching reduces the startup latency of a Player
to the minimum possible value.

When a started Player stops,
it returns
to the PREFETCHED state.

STARTED State

Once prefetched, a Player can enter the
STARTED state by calling the
start method.
A STARTEDPlayer
means the Player is running and processing data.
A Player returns to the PREFETCHED
state when it stops, because the
stop method was invoked,
or it has reached the end of the media.

When the Player moves from the PREFETCHED
to the STARTED state, it posts a STARTED event.
When it moves from the STARTED state to the
PREFETCHED state,
it posts a STOPPED, END_OF_MEDIA
event depending on the reason it
stopped.

The following method must not be used
when the Player is in the STARTED state:

setLoopCount

An IllegalStateException will be thrown.

CLOSED state

Calling close on the Player
puts it in the CLOSED state. In the CLOSED
state, the Player has
released most of its resources and must not
be used again.

The Player's five states and the state transition
methods are summarized in the following diagram:

Player events asynchronously deliver
information about the Player's state changes
and other relevant information from the Player's
Controls.

To receive events, an object must implement the
PlayerListener interface and use the
addPlayerListener method to register its
interest in a Player's events.
All Player 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, the STARTED event
must always
preceed the END_OF_MEDIA event.

An ERROR event may be sent any time
an irrecoverable error has occured. When that happens, the
Player is in the CLOSED state.

The Player event mechanism is extensible and
some Players define events other than
the ones described here. For a list of pre-defined player
events, check the PlayerListener interface.

Managing the Resources Used by a Player

The prefetch
method is used to acquire scarce or exclusive resources
such as the audio device.
Conversely, the deallocate
method is used to release the scarce or exclusive
resources. By using these two methods, an application can
programmatically manage the Player's resources.

For example, in an implementation with an exclusive audio device, to
alternate the audio playback of multiple Players,
an application can selectively deallocate and prefetch individual
Players.

Player's Controls

Player implements Controllable which
provides extra controls via some type-specific Control
interfaces. getControl and getControls
cannot be called when the Player is in the
UNREALIZED or CLOSED state.
An IllegalStateException will be thrown.

prefetch

Acquires the scarce and exclusive resources
and processes as much data as necessary
to reduce the start latency.

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.

start

Starts the 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 start is called when the Player
is in the STARTED state,
the request will be ignored.

deallocate

void deallocate()

Release the scarce or exclusive
resources like the audio device acquired by the 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.

getState

Gets the current state of this Player.
The possible states are: UNREALIZED,
REALIZED, PREFETCHED, STARTED, CLOSED.

Returns:

The Player's current state.

Since:

BlackBerry API 4.0.0

getDuration

long getDuration()

Get the duration of the media.
The value returned is the media's duration
when played at the default rate.
If the duration cannot be determined (for example, the
Player is presenting live
media) getDuration returns TIME_UNKNOWN.

setLoopCount

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.

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.

Parameters:

count - indicates the number of times the content will be
played. 1 is the default. 0 is invalid. -1 indicates looping
indefintely.

Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.Java is a trademark of Oracle America Inc. in the US and other countries.Legal