Interface Player

All Known Subinterfaces:
All Known Implementing Classes:

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

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:

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

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.


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.


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:

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:

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:

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.


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


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


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 class
LATENCY_UNKNOWN, Prefetched, Prefetching, Realized, Realizing, Started, Unrealized
Fields inherited from class
Fields inherited from class
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
Methods inherited from interface
addControllerListener, close, deallocate, getControl, getControls, getStartLatency, getState, getTargetState, prefetch, realize, removeControllerListener
Methods inherited from interface
getMediaNanoseconds, getMediaTime, getRate, getStopTime, getSyncTime, getTimeBase, mapToTimeBase, setMediaTime, setRate, setStopTime, setTimeBase, stop, syncStart
Methods inherited from interface

Method Detail


public java.awt.Component getVisualComponent()
Obtain 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.
The media display Component for this Player.


public GainControl getGainControl()
Obtain 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.
The GainControl object for this Player.


public java.awt.Component getControlPanelComponent()
Obtain the Component that provides the default user interface for controlling this Player. If this Player has no default control panel, getControlPanelComponent returns null.
The default control panel GUI for this Player.


public void start()
Start 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.


public void addController(Controller newController)
                   throws IncompatibleTimeBaseException
Assume control of another Controller.
newController - The Controller to be managed.
IncompatibleTimeBaseException - Thrown if the added Controller cannot take this * Player's TimeBase.


public void removeController(Controller oldController)
Stop controlling a Controller.
oldController - The Controller to stop managing.