Java多媒体框架JFM中的播放器

原文：

Overview 	Package 	 Class 	Tree 	Deprecated 	Index 	Help 
 PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD	DETAIL:  FIELD | CONSTR | METHOD
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.
Overview 	Package 	 Class 	Tree 	Deprecated 	Index 	Help 
 PREV CLASS   NEXT CLASS	FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD	DETAIL:  FIELD | CONSTR | METHOD
Submit a bug or feature 
Copyright 1999-2000 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved. See the Specification License for more details. 
Sun, Sun Microsystems, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.

译文：

Player是MediaHandler用于渲染和控制基于时间的媒体数据。 Player扩展了Controller界面。 Player提供了获取AWT组件的方法，媒体处理控件以及管理其他组件的方法Controllers。

玩家与控制器的不同之处
Player放松了一些限制，这些限制 Controller强加了可以在Started 上调用哪些方法Controller。它还提供了一种管理组的方法Controllers。
限制停止  玩家的方法
无法在Started 上调用以下方法Player。如果他们是，ClockStartedError 被抛出。
setTimeBase
syncStart
deallocate
addController
removeController
启动  播放器允许的方法
不像Controller，下面的方法是法律上Player的启动状态：
setMediaTime
setRate
在Started 上调用这些方法Player可能会启动重要且耗时的处理，具体取决于正在处理的媒体的位置和类型。这些方法也可能导致状态Player发生变化。如果发生这种情况，则在其状态发生变化时TransitionEvents发布相应的相应内容Player。
例如，Player可能必须进入预取状态才能处理setMediaTime 调用。在这种情况下，Player帖子a RestartingEvent，a PrefetchCompleteEvent和a StartEvent从Started状态移动到Prefetching，返回 Prefetched，最后返回Started状态。

对未实现玩家非法的方法
与此同时Controller，在Unrealized 上调用以下方法是违法的Player：
getTimeBase
setTimeBase
setMediaTime
setRate
setStopTime
getStartLatency
Player在Unrealized 上 调用以下方法也是非法的 Player：

getVisualComponent
getControlPanelComponent
getGainControl
addController
removeController
将Player抛出一个NotRealizedError 。如果这些方法被调用，而Player 在未实现的状态。

开始方法
为方便起见，Player提供了一种start 前体，其可以调用的方法Player 是预取的。此方法试图转型Player的开始，从它的任何状态目前的状态。例如，如果Player是未实现的， start隐式调用realize， prefetch和Clock.syncStart。适当的TransitionEvents是作为在开始Player途中通过每个州的移动而发布的。
RestartingEvent
如果setMediaTime或setRate引起媒体呈现的明显延迟，则Player帖子a RestartingEvent转换到预取 状态。a的先前状态和目标状态RestartingEvent 始终为“已启动”。RestartingEvent是。的子类StopEvent。
DurationUpdateEvent
因为a Player不能总是知道它正在播放的媒体的持续时间，所以Duration界面定义 getDuration返回Duration.DURATION_UNKNOWN 直到可以确定持续时间。DurationUpdateEvent当Player 可以确定其持续时间或其持续时间是否改变时生成A ，这可以在任何时间发生。到达媒体的末尾时，应该知道持续时间。
管理其他控制器
在某些情况下，应用程序可能希望使用单个 Player控件来控制其他Players或Controllers。单个控制Player可以被用来调用start，stop，setMediaTime，和在整个群组的其它方法。控制 Player管理所有状态转换和事件发布。
还可以构建简单Controller 的更新动画，报告媒体时间线进度或提供其他与时序相关的功能。这Controllers可以与控制同步操作Player。

添加控制器
要对a进行Player控制Controller，请使用该addController方法。A Controller无法添加到已启动  Player。如果addController在启动时 调用Player， ClockStartedError则抛出a。一个未实现   或Started; Controller 不能加入 Player; 一个NotRealizedError如果被抛出 Controller是未实现的 ; ClockStartedError如果Controller 已启动，则抛出a 。
一旦Controller已添加，则Player：

调用setTimeBase在Controller与 Player's TimeBase。如果失败，addController抛出一个IncompatibleTimeBaseException。
同步Controller与Player 使用setMediaTime，setStopTime以及setRate。
Controller's在计算Player's启动延迟时考虑增加的延迟。当getStartLatency被调用时，Player返回更大的：它在Controller添加之前的延迟和添加的延迟Controller。
Controller's在计算Player's 持续时间时考虑增加的持续时间。当getDuration调用时，Player返回更大的：它在Controller添加之前的持续时间和添加的持续时间Controller。如果这些值中的任何一个为DURATION_UNKNOWN，则 getDuration返回DURATION_UNKNOWN。如果其中任何一个值为DURATION_UNBOUNDED，则getDuration 返回DURATION_UNBOUNDED。
添加自身作为ControllerListener添加的内容，Controller以便它可以管理Controller生成的事件。（有关详细信息，请参阅下面的“ 事件”部分。）
Controller 为响应调用的方法调用添加的控制方法Player。影响托管的方法Controllers将在下面讨论。
将a Controller添加到a后Player，只应Controller通过管理调用方法Player。 如果直接在添加的方法上调用方法，则不会定义Controller或Player将如何表现 Controller。您不能将控制权Player置于其管理的控制之下 Player; 结果行为未定义。
当a Controller添加到a时 Player，Player 不会将添加的Controller状态转换为新状态，Player转换本身也不会转发。该Player要么转换回 意识到如果添加的状态Controller 是实现或预取，或者停留在预取的状态，如果两者的Player 和添加的Controller是在预取 状态。如果Player进行状态转变为添加的结果Controller的Player 职位TransitionEvent。

删除控制器
要阻止Player管理另一个 Controller，请致电removeController。在调用之前 Player必须先停止管理removeController。一ClockStartedError，如果被抛出removeController 被称为一个开始 Player。
当Controller从去除Player's 控制中，Player：

将Controller's TimeBase 其重置为默认值。
DurationUpdateEvent如果Player's持续时间不同而没有Controller添加，则重新计算其持续时间并发布 。
重新计算其启动延迟。
设置管理播放器的媒体时间和速率
当你打电话setMediaTime给Player那个管理他人时Controllers，它的动作会有所不同，具体取决于是否Player 是已启动。如果Player没有启动，它只是调用它的setMediaTime所有 Controllers管理。
如果Player已启动，则会RestartingEvent为每个托管发布并执行以下任务Controller：

调用stop的Controller。
调用setMediaTime的Controller。
调用prefetch的Controller。
等待PrefetchCompleteEvent来自Controller。
调用syncStart上Controller
setRate在管理上调用 时也是如此Player。在Player尝试设置在所有指定率管理Controllers，停止和重新启动Controllers，如果必要的。如果某些Controllers不支持请求的速率，则Player返回实际设置的速率。所有Controllers这些都保证已成功设置为返回的费率。

启动管理员
当您调用start管理时Player，Controllers由其管理的所有内容 Player都将转换为Prefetched状态。当Controllers 被预取，管理Player要求syncStart 与每个被管理的延迟一致的时间 Controllers。
在管理播放器上调用实现，预取，停止或取消分配
当你打电话realize，prefetch， stop，或deallocate在管理 Player中，Player调用，所有的方法 Controllers，这是管理。在Player从一个状态到下一个动作时，其所有的Controllers已经达到该状态。例如，Player在预取 状态不转变到预取的 状态，直到其所有管理的Controllers 是预取。这些 Player帖子TransitionEvents通常会改变状态。
在Managing Player上调用syncStart或setStopTime
当你打电话syncStart或setStopTime管理时Player，在它所管理的Player 所有方法上调用该方法Controllers。（Player 必须处于正确状态或抛出错误。例如，Player必须先预取， 然后才能调用syncStart。）
设置管理播放器的时基
当setTimeBase在管理Player上Player调用时，setTimeBase对所有Controllers它的管理进行调用。如果setTimeBase在任何Controllers一个上失败，IncompatibleTimeBaseException则抛出TimeBase一个并且恢复所有的 最后一次使用Controllers。
获得管理播放器的持续时间
呼叫getDuration管理会Player 返回所有添加Controllers和管理的最长持续时间 Player。如果Player 或任何Controller 尚未解决其持续时间，则getDuration 返回Duration.DURATION_UNKNOWN。
关闭管理员
当close管理Player 所有托管时Controllers也被关闭。
活动
托管发布的大多数事件都由管理Controller过滤Player。某些事件直接从Controller通过Player和向注册的听众发送Player。
要处理托管Controller可以生成的事件，请向Player侦听器注册 Controller添加时间。注册的其他监听器Controller 必须注意不要在由Controller 它管理的时候调用方法Player。Controller直接在托管上调用控制方法将产生不可预测的结果。

当a Controller从Player's 托管列表中删除时Controllers，Player将自己从Controller's 侦听器列表中删除。

过渡事件
一个管理Player职位TransitionEvents，通常因为它的动作状态之间，但管理Controllers影响时Player 的变化状态。通常，a Player不会发布转换事件，直到其所有托管Controllers已发布事件。
状态变更事件
该管理Player收集 RateChangeEvents，StopTimeChangeEvents以及MediaTimeSetEvents通过其管理的发布Controllers和岗位单一的群体性事件。
DurationUpdateEvent
甲Player帖一个DurationUpdateEvent当它决定了它的持续时间或持续时间的变化。Player's如果托管Controller更新或发现其持续时间，则管理持续时间可能会更改 。通常，如果管理的Controller 帖子a DurationUpdateEvent和新的持续时间改变了管理Player's持续时间，则Player帖子aDurationUpdateEvent
CachingControlEvent
从其 管理的收到的管理Player转发，但否则忽略事件。 CachingControlEventsPlayers
ControllerErrorEvents
Player管理层会立即重新发布ControllerErrorEvent从其 管理的任何收到的 Controller内容。一个后ControllerErrorEvent已经从管理接收到的Controller，一个管理Player不再调用了管理的任何方法Controller; Controller从那一点开始忽略托管。