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

java.lang.Object
  extended by net.sf.fmj.ejmf.toolkit.media.AbstractClock
      extended by net.sf.fmj.ejmf.toolkit.media.AbstractController
          extended by 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:

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:

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