javax.media.Player Maven / Gradle / Ivy
/**
This is not an official specification document, and usage is restricted.
NOTICE
(c) 2005-2008 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative use only. For example,
this file and any files generated from it may be used to generate other documentation,
such as a unified set of documents of API signatures for a platform
that includes technologies expressed as Java APIs.
This file may also be used to produce "compilation stubs,"
which allow applications to be compiled and validated for such platforms.
By contrast, no permission is given for you to incorporate this file,
in whole or in part, in an implementation of a Java specification.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 927: Java TV API 1.1.1.
In the event of a discrepency between this work and the JSR 927 specification,
which is available at http://www.jcp.org/en/jsr/detail?id=927, the latter takes precedence.
*/
package javax.media;
import java.awt.Component;
import javax.media.protocol.DataSource;
import java.io.IOException;
/**
* 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.
*
*
How a Player Differs from a Controller
*
* 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.
*
* Methods Restricted to Stopped Players
*
* The following methods can only be called on a Player in
* one of the Stopped states.
* If they are invoked on a Started Player,
* a 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 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:
*
* - 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 Manager
* @see GainControl
* @see Clock
* @see TransitionEvent
* @see RestartingEvent
* @see DurationUpdateEvent
* @see java.awt.Component
*
* @version 1.76, 07/09/19
*/
public interface Player extends MediaHandler, Controller, Duration
{
/**
* 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.
*
*
* @return The media display Component for this
* Player.
*/
public Component getVisualComponent();
/**
* 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.
*
* @return The GainControl object for this
* Player.
*/
public GainControl getGainControl();
/**
* Obtain the Component that provides the default user
* interface for controlling this Player.
* If this Player has no default control panel,
* getControlPanelComponent returns null.
*
* @return The default control panel GUI for this Player.
*/
public Component getControlPanelComponent();
/**
* 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 start();
/**
* Assume control of another Controller.
*
* Note that in some implementations of Java TV, there may be no two
* instances of {@link Controller} with compatible timebases.
* In such cases, {@link IncompatibleTimeBaseException} will always
* be thrown.
*
* @param newController The Controller to be managed.
*
* @exception IncompatibleTimeBaseException Thrown if the added
* Controller cannot take this
* Player's TimeBase.
*/
public void addController(Controller newController)
throws IncompatibleTimeBaseException;
/**
* Stop controlling a Controller.
*
* @param oldController The Controller to stop managing.
*/
public void removeController(Controller oldController);
}