net.sf.fmj.ejmf.toolkit.media
Class AbstractPlayer

java.lang.Object
  net.sf.fmj.ejmf.toolkit.media.AbstractClock
      net.sf.fmj.ejmf.toolkit.media.AbstractController
          net.sf.fmj.ejmf.toolkit.media.AbstractPlayer

All Implemented Interfaces:

Clock, Controller, ControllerListener, Duration, MediaHandler, Player

Direct Known Subclasses:

AbstractProcessor, Handler

public abstract class AbstractPlayer
extends AbstractController
implements Player, ControllerListener

The AbstractPlayer class provides a basic implementation of a javax.media.Player. The abstract "do" methods from AbstractController have been implemented here to provide support for management of multiple Controllers. Subclasses of this class should instead implement the following abstract "do" methods to transition their Controller:

• doPlayerRealize()
• doPlayerPrefetch()
• doPlayerSyncStart()
• doPlayerDeallocate()
• doPlayerStop()

The rules for implementation of these methods are identical to those for implementing a AbstractController:

1. Do not return until the state change is complete. Once the state change is complete, return ASAP.
2. Do not call one another. They will be called in the correct order at the correct time.
3. Do not set the current or target states. They are set automatically.
4. Do not post any TransitionEvents. They are posted automatically.
5. Do not call any of the Clock routines. They will be called automatically.
6. Return true if successful. If unsuccessful, post an appropriate ControllerErrorEvent and return false.
7. When the end of the media has been reached, call endOfMedia(). This will post an EndOfMediaEvent and set the appropriate states. Do not post an EndOfMediaEvent in any other way.

Other abstact methods that should be implemented are:

• doPlayerClose()
• doPlayerSetMediaTime()
• doPlayerSetRate()
• getPlayerStartLatency()
• getPlayerDuration()

From the book: Essential JMF, Gordon, Talley (ISBN 0130801046). Used with permission.

Author:

Steve Talley

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

Constructor Summary

AbstractPlayer()
Construct a AbstractPlayer.

Method Summary

void	addController(Controller newController) Adds a Controller to be controlled by this Player.
void	controllerUpdate(ControllerEvent e) Used to monitor events posted by this Player's managed Controllers.
void	doClose() Close the Player.
boolean	doDeallocate() Deallocate player on current thread.
abstract void	doPlayerClose() Close the Player.
abstract boolean	doPlayerDeallocate() Implement to deallocate the Player.
abstract boolean	doPlayerPrefetch() Implement to prefetch the Player.
abstract boolean	doPlayerRealize() Implement to realize the Player.
abstract void	doPlayerSetMediaTime(Time t) Override to provide implementation-specific functionality.
abstract float	doPlayerSetRate(float rate) Override to provide implementation-specific functionality.
abstract boolean	doPlayerStop() Implement to stop the Player.
abstract boolean	doPlayerSyncStart(Time t) Implement to start the Player.
boolean	doPrefetch() Prefetch player and all of its managed Controllers.
boolean	doRealize() Realize player and all of its managed Controllers.
void	doSetMediaTime(Time t) Sets the media time for this Player and all of its managed Controllers.
float	doSetRate(float rate) Sets the rate for this Player and all of its managed Controllers.
boolean	doStop() Stop player on current thread.
boolean	doSyncStart(Time t) Start player and all of its managed Controllers at the given time.
protected void	endOfMedia() Indicates to the framework that the end of media has been reached.
protected java.util.Vector	getControllers() Gets the list of Controllers under control of this Player.
java.awt.Component	getControlPanelComponent() Get the control panel Component for this Player.
Time	getDuration() Gets the duration of this Player.
GainControl	getGainControl() Get the Gain Control for this Player.
abstract Time	getPlayerDuration() Returns the duration of the media played by this Player only.
abstract Time	getPlayerStartLatency() Returns the start latency of the media played by this Player only.
DataSource	getSource() Convenience method to get the DataSource for the Player.
Time	getStartLatency() Gets the start latency of this Player.
java.awt.Component	getVisualComponent() Get the visual Component for this Player.
void	removeController(Controller oldController) Remove a Controller from the list of Controllers managed by this Player.
protected void	setControlPanelComponent(java.awt.Component c) Set the control panal Component for this AbstractPlayer.
protected void	setGainControl(GainControl c) Set the GainControl for this AbstractPlayer.
void	setMediaTime(Time t) Sets the media time.
float	setRate(float rate) Sets the rate.
void	setSource(DataSource source) Called by javax.media.Manager.
protected void	setVisualComponent(java.awt.Component c) Set the visual Component for this AbstractPlayer.
void	start() Start the player on a new thread.
protected void	synchronousStart() Start the AbstractPlayer ASAP.

Methods inherited from class net.sf.fmj.ejmf.toolkit.media.AbstractController

addControl, addControllerListener, blockUntilStart, close, deallocate, getControl, getControls, getMediaTime, getPreviousState, getState, getTargetState, getThreadQueue, getTimeBase, postControllerClosedEvent, postControllerErrorEvent, postDataStarvedEvent, postDeallocateEvent, postEndOfMediaEvent, postEvent, postPrefetchCompleteEvent, postRealizeCompleteEvent, postRestartingEvent, postStartEvent, postStopAtTimeEvent, postStopByRequestEvent, postStopEvent, postTransitionEvent, prefetch, realize, removeControl, removeControllerListener, setState, setStopTime, setTargetState, setTimeBase, stop, stopAtTime, stopController, stopInRestart, synchronousPrefetch, synchronousRealize, synchronousSyncStart, syncStart

Methods inherited from class net.sf.fmj.ejmf.toolkit.media.AbstractClock

getMediaNanoseconds, getMediaStartTime, getRate, getStopTime, getSyncTime, getTimeBaseStartTime, mapToTimeBase

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface javax.media.Controller

addControllerListener, close, deallocate, getControl, getControls, getState, getTargetState, prefetch, realize, removeControllerListener

Methods inherited from interface javax.media.Clock

getMediaNanoseconds, getMediaTime, getRate, getStopTime, getSyncTime, getTimeBase, mapToTimeBase, setStopTime, setTimeBase, stop, syncStart

Constructor Detail

AbstractPlayer

public AbstractPlayer()

Construct a AbstractPlayer.

Method Detail

doPlayerRealize

public abstract boolean doPlayerRealize()

Implement to realize the Player.

This method should not be called directly. Instead, call realize().

Returns:

True if successful, false otherwise.

doPlayerPrefetch

public abstract boolean doPlayerPrefetch()

Implement to prefetch the Player.

This method should not be called directly. Instead, call prefetch().

Returns:

True if successful, false otherwise.

doPlayerSyncStart

public abstract boolean doPlayerSyncStart(Time t)

Implement to start the Player.

This method should not be called directly. Instead, call start().

Returns:

True if successful, false otherwise.

doPlayerDeallocate

public abstract boolean doPlayerDeallocate()

Implement to deallocate the Player.

This method should not be called directly. Instead, call deallocate().

Returns:

True if successful, false otherwise.

doPlayerStop

public abstract boolean doPlayerStop()

Implement to stop the Player.

This method should not be called directly. Instead, call stop().

Returns:

True if successful, false otherwise.

doPlayerClose

public abstract void doPlayerClose()

Close the Player. Typically this method will release as many resources as possible, especially those that may be needed by other Players.

This method should not be called directly. Instead, call close().

doPlayerSetMediaTime

public abstract void doPlayerSetMediaTime(Time t)

Override to provide implementation-specific functionality. When this method is called, it is guaranteed that the Controller is Stopped and that the given time is within the Controller's duration.

This method should not be called directly. Instead, call setMediaTime().

Parameters:

t - The media time to set

doPlayerSetRate

public abstract float doPlayerSetRate(float rate)

Override to provide implementation-specific functionality. When this method is called, it is guaranteed that the Controller is Stopped.

This method should not be called directly. Instead, call setRate().

Parameters:

rate - The requested rate to set

Returns:

The actual rate that was set

getPlayerStartLatency

public abstract Time getPlayerStartLatency()

Returns the start latency of the media played by this Player only. It does not consider any of the Controllers that this Player may be managing.

getPlayerDuration

public abstract Time getPlayerDuration()

Returns the duration of the media played by this Player only. It does not consider any of the Controllers that this Player may be managing.

getDuration

public final Time getDuration()

Gets the duration of this Player.

Specified by:

getDuration in interface Duration

Overrides:

getDuration in class AbstractController

setMediaTime

public void setMediaTime(Time t)

Sets the media time. If the Player is in the Started state, it is stopped before setting the media time and restarted afterwards.

Specified by:

setMediaTime in interface Clock

Overrides:

setMediaTime in class AbstractController

Parameters:

t - The media time to set

Throws:

NotRealizedError - If the Controller is not Realized.

setRate

public float setRate(float rate)

Sets the rate. If the Player is in the Started state, it is stopped before setting the rate and restarted afterwards.

Specified by:

setRate in interface Clock

Overrides:

setRate in class AbstractController

Parameters:

rate - The temporal scale factor (rate) to set.

Returns:

The actual rate set.

Throws:

NotRealizedError - If the Controller is not Realized.

getStartLatency

public Time getStartLatency()

Gets the start latency of this Player. It is defined to be the longest start latency between this Player and any of the Controllers that this Player may be managing. If any of the Controllers returns LATENCY_UNKNOWN, it's value is skipped in the calculation of the maximum latency.

Specified by:

getStartLatency in interface Controller

Overrides:

getStartLatency in class AbstractController

Returns:

The maximum start latency of this Player and all its managed Controllers, or LATENCY_UNKNOWN if the Player and its managed Controllers all return LATENCY_UNKNOWN.

start

public final void start()

Start the player on a new thread. If necessary, the Player will be prefetched before being started. Subclasses should override doSyncStart() to do the actual work to transition the Controller.

Checks for Player state prerequisites and creates a StartThread to start the AbstractPlayer. If there is already a thread transitioning the AbstractPlayer forward, then the target state of the AbstractPlayer is set to Started and the method returns.

Asynchronous method -- Start synchronous transition on another thread and return ASAP.

Specified by:

start in interface Player

addController

public void addController(Controller newController)
                   throws IncompatibleTimeBaseException

Adds a Controller to be controlled by this Player.

Specified by:

addController in interface Player

Parameters:

newController - The Controller to add

Throws:

NotRealizedError - If this Player or the new Controller are not Realized.

ClockStartedError - If this Player or the new Controller are in the Started state.

IncompatibleTimeBaseException - Thrown by newController.setTimeBase() if the new Controller cannot use this player's TimeBase

removeController

public void removeController(Controller oldController)

Remove a Controller from the list of Controllers managed by this Player.

Specified by:

removeController in interface Player

Parameters:

oldController - The Controller to remove

getControllers

protected java.util.Vector getControllers()

Gets the list of Controllers under control of this Player.

setGainControl

protected void setGainControl(GainControl c)

Set the GainControl for this AbstractPlayer. If the AbstractPlayer does not support audio media, this method should return null.

Parameters:

c - The GainControl allowing control of the volume of this AbstractPlayer's media.

getGainControl

public GainControl getGainControl()

Get the Gain Control for this Player.

Specified by:

getGainControl in interface Player

Returns:

The GainControl object, or null if it has not been set.

setVisualComponent

protected void setVisualComponent(java.awt.Component c)

Set the visual Component for this AbstractPlayer. If the AbstractPlayer does not support video media, this method should return null.

Parameters:

c - A java.awt.Component on which the media is rendered.

getVisualComponent

public java.awt.Component getVisualComponent()

Get the visual Component for this Player.

Specified by:

getVisualComponent in interface Player

Returns:

The visual Component, or null if it has not been set.

setControlPanelComponent

protected void setControlPanelComponent(java.awt.Component c)

Set the control panal Component for this AbstractPlayer.

Parameters:

c - A java.awt.Component providing control over this AbstractPlayer's media.

getControlPanelComponent

public java.awt.Component getControlPanelComponent()

Get the control panel Component for this Player.

Specified by:

getControlPanelComponent in interface Player

Returns:

The control panel Component, or null if it has not been set.

setSource

public void setSource(DataSource source)
               throws IncompatibleSourceException

Called by javax.media.Manager. This is the litmus test that tells whether this Player can support the given DataSource. If it can't, this method should throw a IncompatibleSourceException. Our only requirement here is that the DataSource has not already been set. Subclasses may wish to override this method to extend the acceptance criteria.

Specified by:

setSource in interface MediaHandler

Parameters:

source - The DataSource to test

Throws:

IncompatibleSourceException - Thrown if the DataSource has already been set on this MediaHandler, or if the DataSource is not a PullDataSource

getSource

public DataSource getSource()

Convenience method to get the DataSource for the Player.

controllerUpdate

public final void controllerUpdate(ControllerEvent e)

Used to monitor events posted by this Player's managed Controllers. By keeping track of the actions of each Controller, the Player can synchronize the state transtitions of multiple Controllers.

This method is final because the controller-management functionality of the AbstractPlayer will not work if it is overridden.

Specified by:

controllerUpdate in interface ControllerListener

Parameters:

e - The ControllerEvent posted by one of the managed Controllers.

doRealize

public final boolean doRealize()

Realize player and all of its managed Controllers. Subclasses should override doPlayerRealize() to do the actual work to transition the Controller.

This method should not be called directly. Instead, call realize().

Specified by:

doRealize in class AbstractController

Returns:

True if successful, false otherwise.

doPrefetch

public final boolean doPrefetch()

Prefetch player and all of its managed Controllers. Subclasses should override doPlayerPrefetch() to do the actual work to transition the Controller.

This method should not be called directly. Instead, call prefetch().

Specified by:

doPrefetch in class AbstractController

Returns:

True if successful, false otherwise.

doSyncStart

public final boolean doSyncStart(Time t)

Start player and all of its managed Controllers at the given time. Subclasses should override doPlayerSyncStart() to do the actual work to transition the Controller.

This method should not be called directly. Instead, call syncStart().

Specified by:

doSyncStart in class AbstractController

Returns:

True if successful, false otherwise.

doDeallocate

public final boolean doDeallocate()

Deallocate player on current thread. Subclasses should override doPlayerDeallocate() to do the actual work to transition the Controller.

This method should not be called directly. Instead, call deallocate().

Specified by:

doDeallocate in class AbstractController

Returns:

True if successful, false otherwise.

doStop

public final boolean doStop()

Stop player on current thread. Subclasses should override doPlayerStop() to do the actual work to transition the Controller.

This method should not be called directly. Instead, call stop().

Specified by:

doStop in class AbstractController

Returns:

True if successful, false otherwise.

doClose

public final void doClose()

Close the Player. First close all Controllers under the control of this Player. Then release resources held by this Player. Subclasses should implement doPlayerClose() to add additional functionality.

This method should not be called directly. Instead, call close().

Specified by:

doClose in class AbstractController

doSetMediaTime

public final void doSetMediaTime(Time t)

Sets the media time for this Player and all of its managed Controllers.

This method should not be called directly. Instead, call setMediaTime().

Specified by:

doSetMediaTime in class AbstractController

Parameters:

t - The media time to set.

doSetRate

public final float doSetRate(float rate)

Sets the rate for this Player and all of its managed Controllers. If any of the above cannot accomodate the given rate, then the rate is set to 1.0 for all of the above.

This method should not be called directly. Instead, call setRate().

Specified by:

doSetRate in class AbstractController

Parameters:

rate - The rate to set.

Returns:

The actual rate that was set

endOfMedia

protected void endOfMedia()
                   throws ClockStoppedException

Indicates to the framework that the end of media has been reached. Marks the media time, sets the current and target states to Prefetched, and posts an EndOfMediaEvent.

Overrides:

endOfMedia in class AbstractController

Throws:

ClockStoppedException - If the AbstractController is not in the Started state.

synchronousStart

protected void synchronousStart()

Start the AbstractPlayer ASAP.

Synchronous method -- return when transition complete