javax.media
Interface Player

Player is a MediaHandler for rendering
and controlling time based media data.
Player extends the Controller interface.
Player provides methods for
obtaining AWT components, media processing controls, and a way to
manage other Controllers.

How a Player Differs from a Controller

Player relaxes some restrictions that a
Controller imposes
on what methods can be called on a StartedController.
It also provides a way to manage groups of Controllers.

Methods Restricted to Stopped Players

The following methods cannot be invoked on a StartedPlayer. If they are, ClockStartedError
is thrown.

setTimeBase

syncStart

deallocate

addController

removeController

Methods Allowed on Started Players

Unlike a Controller, the following methods are legal on
a Player in the Started state:

setMediaTime

setRate

Invoking these methods on a StartedPlayer might
initiate significant and time-consuming processing, depending
on the location and type of media being processed.
These methods might also cause the state of the Player to
change.
If this happens, the appropriate TransitionEvents are posted
by the Player when its state changes.

For example, a Player might have to enter
the Prefetching state to process a setMediaTime
invocation.
In this case, the Player posts a RestartingEvent,
a PrefetchCompleteEvent, and a StartEvent as
it moves from the Started state to Prefetching, back to
Prefetched, and finally back to the Started state.

Methods that are Illegal on Unrealized Players

As with Controller, it is illegal to call the following methods
on an UnrealizedPlayer:

getTimeBase

setTimeBase

setMediaTime

setRate

setStopTime

getStartLatency

It is also illegal to call the following Player methods on an
UnrealizedPlayer:

getVisualComponent

getControlPanelComponent

getGainControl

addController

removeController

The Player throws a NotRealizedError
if any of these methods are called while the Player
is in the Unrealized state.

Start Method

As a convenience, Player provides a start
method that can be invoked before a Player
is Prefetched.
This method attempts to transition the Player to
the Started state from whatever state it's currently in.
For example, if the Player is Unrealized,
start implicitly calls realize,
prefetch, and Clock.syncStart.
The appropriate TransitionEvents are posted as
the Player moves through each state on its way
to Started.

RestartingEvent

If setMediaTime or setRate cause a perceptible
delay in the presentation of the media, the Player posts a
RestartingEvent and transitions to the Prefetching
state.
The previous state and target state of a RestartingEvent
is always Started. RestartingEvent is a subclass
of StopEvent.

DurationUpdateEvent

Because a Player cannot always know the duration of the media
it is playing, the Duration interface defines that
getDuration returns Duration.DURATION_UNKNOWN
until the duration can be determined.
A DurationUpdateEvent is generated when the Player
can determine its duration or the if its duration
changes, which can happen at any time. When the end of the media
is reached, the duration should be known.

Managing other Controllers

In some situations, an application might want to use a single
Player to
control other Players or Controllers.
A single controlling Player can be used to
invoke start, stop, setMediaTime,
and other methods on the entire group. The controlling
Player manages all of the state transitions and event posting.

It is also possible to construct a simple Controller
to update animations, report on media time-line progress, or
provide other timing-related functions. Such Controllers can
operate in sync with a controlling Player.

Adding a Controller

To have a Player assume control over a Controller,
use the addController method.
A Controller can not be added to a StartedPlayer. If addController is called on
a StartedPlayer,
a ClockStartedError is thrown.
An Unrealized&nbsp or Started;Controller
cannot be added to a
Player; a NotRealizedError is thrown if the
Controller is Unrealized;
a ClockStartedError is thrown if the Controller
is Started.

Once a Controller has been added, the Player:

Invokes setTimeBase on the Controller with the
Player'sTimeBase.
If this fails, addController throws
an IncompatibleTimeBaseException.

Synchronizes the Controller with the Player
using setMediaTime, setStopTime,
and setRate.

Takes the added Controller's latency into account when
computing the Player's start latency.
When getStartLatency is called,
the Player returns the greater of:
its latency before the Controller was added and
the latency of the added Controller.

Takes the added Controller's duration into account when
computing the Player's
duration. When getDuration is called,
the Player returns the greater of:
its duration before the Controller was added and
the duration of the added Controller.
If either of these values is DURATION_UNKNOWN,
getDuration returns DURATION_UNKNOWN.
If either of these values is DURATION_UNBOUNDED getDuration
returns DURATION_UNBOUNDED.

Adds itself as a ControllerListener for the
added Controller so that it can
manage the events that the Controller generates.
(See the Events section below for more information.)

Invokes control methods on the added Controller
in response to methods invoked on the Player. The
methods that affect
managed Controllers are discussed below.

Once a Controller has been added to a Player,
methods should only be called on the Controller through the
managing Player.
It is not defined how the Controller or Player
will behave if methods are called directly on an added
Controller.
You cannot place a controlling Player under the control of a
Player that it is managing; the resulting behavior is
undefined.

When a Controller is added to a
Player, the Player
does not transition the added Controller to
new state, nor does the Player transition itself
forward.
The Player either transitions back to the
realized state if the added Controller
is realized or prefetching or it stays
in the prefetched state if the both the Player
and the added Controller are in the prefetched
state. If the Player makes a state transition
as a result of adding a Controller the Player
posts a TransitionEvent.

Removing a Controller

To stop a Player from managing another
Controller, call removeController.
The managing Player must be Stopped before
removeController can be called.
A ClockStartedError is thrown if removeController
is called on a StartedPlayer.

When a Controller is removed from a Player's
control, the Player:

Resets the Controller'sTimeBase
to its default.

Recalculates its duration and posts a
DurationUpdateEvent if the Player's duration
is different without the Controller added.

Recalculates its start latency.

Setting the Media Time and Rate of a Managing Player

When you call setMediaTime on a Player that's
managing other Controllers,
its actions differ depending on whether or not the Player
is Started.
If the Player is not Started, it simply
invokes setMediaTime on all of the
Controllers it's managing.

If the Player is Started,
it posts a RestartingEvent and
performs the following tasks for each managed Controller:

Invokes stop on the Controller.

Invokes setMediaTime on the Controller.

Invokes prefetch on the Controller.

Waits for a PrefetchCompleteEvent from
the Controller.

Invokes syncStart on the Controller

The same is true when setRate is called on a
managing Player.
The Player attempts to set the specified rate
on all managed Controllers, stopping and restarting
the Controllers if necessary.
If some of the Controllers do not support the requested rate,
the Player returns the rate that was actually set.
All Controllers are guaranteed to have been successfully
set to the rate returned.

Starting a Managing Player

When you call start on a managing Player,
all of the Controllers managed by
the Player are transitioned to
the Prefetched state. When the Controllers
are Prefetched,
the managing Player calls syncStart
with a time consistent with the latencies of each of the managed
Controllers.

Calling realize, prefetch, stop, or deallocate on a Managing Player

When you call realize, prefetch,
stop, or deallocate on a managing
Player,
the Player calls that method on all of the
Controllers that it is managing.
The Player moves from one state to the
next when all of its Controllers have reached that state.
For example, a Player in the Prefetching
state does not transition into the Prefetched
state until all of its managed Controllers
are Prefetched.
The Player posts TransitionEvents normally
as it changes state.

Calling syncStart or setStopTime on a Managing Player

When you call syncStart or setStopTime on a
managing Player, the Player
calls that method on all of the Controllers that it
is managing. (The Player
must be in the correct state or an error is thrown.
For example, the Player must be Prefetched
before you can call syncStart.)

Setting the Time Base of a Managing Player

When setTimeBase is called on a managing Player,
the Player calls setTimeBase on all of
the Controllers it's managing.
If setTimeBase fails on any of the Controllers,
an IncompatibleTimeBaseException is thrown
and the TimeBase last used
is restored for all of the Controllers.

Getting the Duration of a Managing Player

Calling getDuration on a managing Player
returns the maximum duration of all of the added
Controllers and the managing Player.
If the Player or any Controller
has not resolved its duration, getDuration
returns Duration.DURATION_UNKNOWN.

Closing a Managing Player

When close is called on a managing Player
all managed Controllers are closed as well.

Most events posted by a managed Controller are filtered
by the managing Player. Certain events are sent directly
from the Controller through the Player and to the
listeners registered with the Player.

To handle the events that a managed Controller can generate,
the Player registers a listener with the
Controller when it is added.
Other listeners that are registered with the Controller
must be careful not to invoke methods on the Controller
while it is being managed by the Player.
Calling a control method on a managed Controller directly
will produce unpredictable results.

When a Controller is removed from the Player's
list of managed Controllers,
the Player removes itself from the Controller's
listener list.

Transition Events

A managing Player posts TransitionEvents normally
as it moves between states, but
the managed Controllers affect when the Player
changes state.
In general,
a Player does not post a transition event until all of its
managed Controllers have posted the event.

Status Change Events

The managing Player collects the
RateChangeEvents, StopTimeChangeEvents,
and MediaTimeSetEvents posted by its
managed Controllers and posts a single event for the group.

DurationUpdateEvent

A Player posts a DurationUpdateEvent when
it determines its duration or its duration changes.
A managing Player's duration might change if a managed
Controller updates or discovers its duration.
In general, if a managed Controller
posts a DurationUpdateEvent and the new duration
changes the managing Player's duration,
the Player posts a DurationUpdateEvent

CachingControlEvent

A managing Player reposts CachingControlEvents
received from a Players that it manages, but otherwise
ignores the events.

ControllerErrorEvents

A managing Player immediately reposts
any ControllerErrorEvent received from a
Controller that it is managing.
After a ControllerErrorEvent has been
received from a managed Controller, a
managing Player no longer invokes any methods
on the managed Controller; the
managed Controller is ignored from that point on.

getVisualComponent

public java.awt.Component getVisualComponent()

Gets the display Component for this Player.
The display Component is where visual media
is rendered.
If this Player has no visual component,
getVisualComponent returns null.
For example, getVisualComponent might return
null if the Player only plays audio.

Returns:

The media display Component for this
Player.

getGainControl

Gets the object for controlling this Player's
audio gain.
If this player does not have a
GainControl, getGainControl returns
null.
For example, getGainControl might return
null if the Player does not play audio data.

Returns:

The GainControl object for this
Player.

getControlPanelComponent

public java.awt.Component getControlPanelComponent()

Gets the Component that provides the default user
interface for controlling this Player.
If this Player has no default control panel,
getControlPanelComponent returns null.

Returns:

The default control panel GUI for this Player.

start

public void start()

Starts the Player as soon as possible.
The start method attempts to transition the
Player to the Started state.
If the Player has not been Realized or
Prefetched, start automatically performs
those actions. The appropriate events
are posted as the Player moves through each state.

Submit a bug or featureCopyright 1999-2001 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. See the Specification License for more details. Sun, Sun Microsystems, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.