All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ejmf.toolkit.media.AbstractPlayer

java.lang.Object
   |
   +----ejmf.toolkit.media.AbstractClock
           |
           +----ejmf.toolkit.media.AbstractController
                   |
                   +----ejmf.toolkit.media.AbstractPlayer

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:


Constructor Index

 o AbstractPlayer()
Construct a AbstractPlayer.

Method Index

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

Constructors

 o AbstractPlayer
 public AbstractPlayer()
Construct a AbstractPlayer.

Methods

 o 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.
 o 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.
 o 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.
 o 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.
 o 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.
 o 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().

 o 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
 o 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
 o 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.

 o 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.

 o getDuration
 public final synchronized Time getDuration()
Gets the duration of this Player.

Overrides:
getDuration in class AbstractController
 o setMediaTime
 public synchronized 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.

Parameters:
t - The media time to set
Throws: NotRealizedError
If the Controller is not Realized.
Overrides:
setMediaTime in class AbstractController
 o setRate
 public synchronized 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.

Parameters:
rate - The temporal scale factor (rate) to set.
Throws: NotRealizedError
If the Controller is not Realized.
Overrides:
setRate in class AbstractController
 o getStartLatency
 public synchronized 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.

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.
Overrides:
getStartLatency in class AbstractController
 o 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.

 o addController
 public synchronized void addController(Controller newController) throws IncompatibleTimeBaseException
Adds a Controller to be controlled by this Player.

Parameters:
newController - The Controller to add
Throws: NotRealizedError
If this Player or the new Controller are not Realized.
Throws: ClockStartedError
If this Player or the new Controller are in the Started state.
Throws: IncompatibleTimeBaseException
Thrown by newController.setTimeBase() if the new Controller cannot use this player's TimeBase
 o removeController
 public synchronized void removeController(Controller oldController)
Remove a Controller from the list of Controllers managed by this Player.

Parameters:
oldController - The Controller to remove
 o getControllers
 protected Vector getControllers()
Gets the list of Controllers under control of this Player.

 o 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.
 o getGainControl
 public GainControl getGainControl()
Get the Gain Control for this Player.

Returns:
The GainControl object, or null if it has not been set.
 o setVisualComponent
 protected void setVisualComponent(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.
 o getVisualComponent
 public Component getVisualComponent()
Get the visual Component for this Player.

Returns:
The visual Component, or null if it has not been set.
 o setControlPanelComponent
 protected void setControlPanelComponent(Component c)
Set the control panal Component for this AbstractPlayer.

Parameters:
c - A java.awt.Component providing control over this AbstractPlayer's media.
 o getControlPanelComponent
 public Component getControlPanelComponent()
Get the control panel Component for this Player.

Returns:
The control panel Component, or null if it has not been set.
 o 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.

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
 o getSource
 public DataSource getSource()
Convenience method to get the DataSource for the Player.

 o 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.

Parameters:
e - The ControllerEvent posted by one of the managed Controllers.
 o 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().

Overrides:
doRealize in class AbstractController
 o 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().

Overrides:
doPrefetch in class AbstractController
 o 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().

Overrides:
doSyncStart in class AbstractController
 o 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().

Overrides:
doDeallocate in class AbstractController
 o 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().

Overrides:
doStop in class AbstractController
 o doClose
 public final synchronized 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().

Overrides:
doClose in class AbstractController
 o doSetMediaTime
 public final synchronized 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().

Parameters:
t - The media time to set.
Overrides:
doSetMediaTime in class AbstractController
 o doSetRate
 public final synchronized 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().

Parameters:
t - The rate to set.
Overrides:
doSetRate in class AbstractController
 o 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.

Throws: ClockStoppedException
If the AbstractController is not in the Started state.
Overrides:
endOfMedia in class AbstractController
 o synchronousStart
 protected void synchronousStart()
Start the AbstractPlayer ASAP.

Synchronous method -- return when transition complete


All Packages  Class Hierarchy  This Package  Previous  Next  Index