|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Player
is a MediaHandler
for rendering
and controlling time based media data.
Player
extends both the Controller
and Duration
interfaces
Player
provides methods for
obtaining AWT components, media processing controls, and a way to
manage other Controllers
.
Player
relaxes some restrictions that a
Controller
imposes
on what methods can be called on a Started, Stopped, or
Unrealized Controller
.
It also provides a way to manage groups of Controllers
.
Player
in
one of the Stopped states.
If they are invoked on a Started Player
,
a ClockStartedError
is thrown.
setTimeBase
syncStart
deallocate
addController
removeController
Controller
, the following methods are legal on
a Player
in the Started state:
setMediaTime
setRate
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.
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.
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.
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
.
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.
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
.
Player
assume control over a Controller
,
use the addController
method.
A Controller
can only be added to a Stopped
Player
. If addController
is called on
a Started Player
,
a ClockStartedError
is thrown.
An Unrealized Controller
cannot be added to a
Player
; a NotRealizedError
is thrown if the
Controller
is Unrealized.
Once a Controller
has been added, the Player
:
setTimeBase
on the Controller
with the
Player's
TimeBase
.
If this fails, addController
throws
an IncompatibleTimeBaseException
.
Controller
with the Player
using setMediaTime
, setStopTime
,
and setRate
.
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
.
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.
ControllerListener
for the
added Controller
so that it can
manage the events that the Controller
generates.
(See the Events section below for more information.)
Controller
in response to methods invoked on the Player
. The
methods that affect
managed Controllers
are discussed below.
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
.
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
:
Controller's
TimeBase
to its default.
DurationUpdateEvent
if the Player's
duration
is different without the Controller
added.
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
:
stop
on the Controller
.
setMediaTime
on the Controller
.
prefetch
on the Controller
.
PrefetchCompleteEvent
from
the Controller
.
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.
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
.
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.
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
.)
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
.
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
.
close
is called on a managing Player
all managed Controllers
are closed as well.
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.
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.
Player
collects the
RateChangeEvents
, StopTimeChangeEvents
,
and MediaTimeSetEvents
posted by its
managed Controllers
and posts a single event for the group.
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
Player
reposts CachingControlEvents
received from a Players
that it manages, but otherwise
ignores the events.
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.
Manager
,
GainControl
,
Clock
,
TransitionEvent
,
RestartingEvent
,
DurationUpdateEvent
,
Component
Field Summary |
Fields inherited from interface javax.media.Controller |
LATENCY_UNKNOWN, Prefetched, Prefetching, Realized, Realizing, Started, Unrealized |
Fields inherited from interface javax.media.Clock |
RESET |
Fields inherited from interface javax.media.Duration |
DURATION_UNBOUNDED, DURATION_UNKNOWN |
Method Summary | |
void |
addController(Controller newController)
Assume control of another Controller . |
java.awt.Component |
getControlPanelComponent()
Obtain the Component that provides the default user
interface for controlling this Player . |
GainControl |
getGainControl()
Obtain the object for controlling this Player's
audio gain. |
java.awt.Component |
getVisualComponent()
Obtain the display Component for this Player . |
void |
removeController(Controller oldController)
Stop controlling a Controller . |
void |
start()
Start the Player as soon as possible. |
Methods inherited from interface javax.media.MediaHandler |
setSource |
Methods inherited from interface javax.media.Controller |
addControllerListener, close, deallocate, getControl, getControls, getStartLatency, getState, getTargetState, prefetch, realize, removeControllerListener |
Methods inherited from interface javax.media.Clock |
getMediaNanoseconds, getMediaTime, getRate, getStopTime, getSyncTime, getTimeBase, mapToTimeBase, setMediaTime, setRate, setStopTime, setTimeBase, stop, syncStart |
Methods inherited from interface javax.media.Duration |
getDuration |
Method Detail |
public java.awt.Component getVisualComponent()
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.
Component
for this
Player
.public GainControl getGainControl()
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.
GainControl
object for this
Player
.public java.awt.Component getControlPanelComponent()
Component
that provides the default user
interface for controlling this Player
.
If this Player
has no default control panel,
getControlPanelComponent
returns null
.
Player
.public void start()
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.
public void addController(Controller newController) throws IncompatibleTimeBaseException
Controller
.
newController
- The Controller
to be managed.
IncompatibleTimeBaseException
- Thrown if the added
Controller
cannot take this * Player's
TimeBase
.public void removeController(Controller oldController)
Controller
.
oldController
- The Controller
to stop managing.
|
JSR-927 (Maintenance Release) | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |