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 Started
Controller.
It also provides a way to manage groups of Controllers.
Methods Restricted to Stopped Players
The following methods cannot be invoked on a Started
Player. 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:
Invoking these methods on a Started Player 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 Unrealized Player:
-
getTimeBase
-
setTimeBase
-
setMediaTime
-
setRate
-
setStopTime
-
getStartLatency
It is also illegal to call the following Player methods on an
Unrealized Player:
-
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 Started
Player. If addController is called on
a Started Player,
a ClockStartedError is thrown.
An Unrealized 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's TimeBase.
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 Started Player.
When a Controller is removed from a Player's
control, the Player:
- Resets the
Controller's TimeBase
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.
Events
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. |
