javax.media
Interface Player

All Known Subinterfaces:

Processor

All Known Implementing Classes:

MediaPlayer

public interface Player

extends MediaHandler, Controller

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:

• setMediaTime
• setRate

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.

See Also:

Manager, GainControl, Clock, TransitionEvent, RestartingEvent, DurationUpdateEvent, Component

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) Tells the Player to assume control of another Controller.
java.awt.Component	getControlPanelComponent() Gets the Component that provides the default user interface for controlling this Player.
GainControl	getGainControl() Gets the object for controlling this Player's audio gain.
java.awt.Component	getVisualComponent() Gets the display Component for this Player.
void	removeController(Controller oldController) Tells the Player to stop controlling a Controller.
void	start() Starts 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

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

public GainControl 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.

addController

public void addController(Controller newController)
                   throws IncompatibleTimeBaseException

Tells the Player to assume control of another Controller.

Parameters:

newController - The Controller to be managed.

Throws:

IncompatibleTimeBaseException - Thrown if the added Controller cannot take this Player's TimeBase.

removeController

public void removeController(Controller oldController)

Tells the Player to stop controlling a Controller.

Parameters:

oldController - The Controller to stop managing.