All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class ejmf.toolkit.media.AbstractController

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

public abstract class AbstractController
extends AbstractClock
implements Controller
The AbstractController class provides a basic implementation of a javax.media.Controller. Subclasses should implement the following abstract "do" methods to transition their Controller:

Follow these rules when implementing these methods:

  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:

See Also:
AbstractPlayer

Constructor Index

 o AbstractController()
Construct a AbstractController.

Method Index

 o addControl(Control)
Add a Control to this Controller.
 o addControllerListener(ControllerListener)
Specify a ControllerListener to which this Controller will send events.
 o blockUntilStart(Time)
For a given time-base start time, block until the AbstractController should be started.
 o close()
Close the Controller.
 o deallocate()
Deallocate Controller on current thread.
 o doClose()
Close the Controller.
 o doDeallocate()
Implement to deallocate the Controller.
 o doPrefetch()
Implement to prefetch the Controller.
 o doRealize()
Implement to realize the Controller.
 o doSetMediaTime(Time)
Override to provide implementation-specific functionality.
 o doSetRate(float)
Override to provide implementation-specific functionality.
 o doStop()
Implement to stop the Controller.
 o doSyncStart(Time)
Implement to start the Controller.
 o endOfMedia()
Indicates to the framework that the end of media has been reached.
 o getControl(String)
Get the Control that supports the class or interface specified.
 o getControls()
Get a list of the Control objects that this Controller supports.
 o getDuration()
Returns DURATION_UNKNOWN.
 o getMediaTime()
Calculates the current media time based on the current time-base time, the time-base start time, the media start time, and the rate.
 o getPreviousState()
Get the previous state of this Controller.
 o getStartLatency()
Returns LATENCY_UNKNOWN.
 o getState()
Get the current state of this Controller.
 o getTargetState()
Get the target state of this Controller.
 o getThreadQueue()
Gets the ThreadQueue object for this AbstractController.
 o getTimeBase()
Get the TimeBase that this Controller is using.
 o postControllerClosedEvent()
Post a ControllerClosedEvent to the Media Event Queue.
 o postDataStarvedEvent()
Post a DataStarvedEvent to the Media Event Queue.
 o postDeallocateEvent()
Post a DeallocateEvent to the Media Event Queue.
 o postEndOfMediaEvent()
Post a EndOfMediaEvent to the Media Event Queue.
 o postEvent(ControllerEvent)
Post a ControllerEvent to the Media Event Queue
 o postPrefetchCompleteEvent()
Post a PrefetchCompleteEvent to the Media Event Queue.
 o postRealizeCompleteEvent()
Post a RealizeCompleteEvent to the Media Event Queue.
 o postRestartingEvent()
Post a RestartingEvent to the Media Event Queue.
 o postStartEvent()
Post a StartEvent to the Media Event Queue.
 o postStopAtTimeEvent()
Post a StopAtTimeEvent to the Media Event Queue.
 o postStopByRequestEvent()
Post a StopByRequestEvent to the Media Event Queue.
 o postStopEvent()
Post a StopEvent to the Media Event Queue.
 o postTransitionEvent()
Post a TransitionEvent to the Media Event Queue.
 o prefetch()
Prefetch Controller on new thread.
 o realize()
Realize Controller on new thread.
 o removeControl(Control)
Remove a Control from this Controller.
 o removeControllerListener(ControllerListener)
Remove the specified listener from this Controller's listener list.
 o setMediaTime(Time)
Sets the media time.
 o setRate(float)
Set the temporal scale factor.
 o setState(int)
Set the current state of this Controller.
 o setStopTime(Time)
Sets the stop time for this AbstractController.
 o setTargetState(int)
Set the targetState state of this Controller.
 o setTimeBase(TimeBase)
Set the TimeBase for this Clock.
 o stop()
Stop Controller on current thread and post a StopByRequestEvent.
 o stopAtTime()
Stop Controller on current thread and post a StopAtTimeEvent.
 o stopController()
Stop the controller.
 o stopInRestart()
Stop Controller on current thread and post a RestartingEvent.
 o synchronousPrefetch()
Realize the AbstractController synchronously.
 o synchronousRealize()
Realize the AbstractController synchronously.
 o synchronousSyncStart(Time)
SyncStart the AbstractController synchronously at the previously-specified time-base start time.
 o syncStart(Time)
SyncStart Controller on new thread.

Constructors

 o AbstractController
 public AbstractController()
Construct a AbstractController.

Methods

 o doRealize
 public abstract boolean doRealize()
Implement to realize the Controller.

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

Returns:
True if successful, false otherwise.
 o doPrefetch
 public abstract boolean doPrefetch()
Implement to prefetch the Controller.

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

Returns:
True if successful, false otherwise.
 o doSyncStart
 public abstract boolean doSyncStart(Time t)
Implement to start the Controller.

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

Returns:
True if successful, false otherwise.
 o doDeallocate
 public abstract boolean doDeallocate()
Implement to deallocate the Controller.

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

Returns:
True if successful, false otherwise.
 o doStop
 public abstract boolean doStop()
Implement to stop the Controller.

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

Returns:
True if successful, false otherwise.
 o doClose
 public abstract void doClose()
Close the Controller. Typically this method will release as many resources as possible, especially those that may be needed by other Controllers.

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

 o doSetMediaTime
 public abstract void doSetMediaTime(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 doSetRate
 public abstract float doSetRate(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 setTimeBase
 public synchronized void setTimeBase(TimeBase timebase) throws IncompatibleTimeBaseException
Set the TimeBase for this Clock. This method can only be called on a Stopped Clock. A ClockStartedError is thrown if setTimeBase is called on a Started Clock.

A Clock has a default TimeBase that is determined by the implementation. To reset a Clock to its default TimeBase, call setTimeBase(null).

Parameters:
timebase - The new TimeBase or null to reset the Clock to its default TimeBase.
Throws: IncompatibleTimeBaseException
Thrown if the Clock can't use the specified TimeBase.
Overrides:
setTimeBase in class AbstractClock
 o getTimeBase
 public synchronized TimeBase getTimeBase()
Get the TimeBase that this Controller is using.

Overrides:
getTimeBase in class AbstractClock
 o setStopTime
 public synchronized void setStopTime(Time mediaStopTime)
Sets the stop time for this AbstractController. Posts a StopTimeChangeEvent if the stop time given is different than the current stop time.

Parameters:
mediaStopTime - The time at which you want the Clock to stop, in media time.
Throws: NotRealizedError
If the Controller is not Realized.
Throws: ClockStartedError
If the Controller is Started.
Overrides:
setStopTime in class AbstractClock
 o setMediaTime
 public synchronized void setMediaTime(Time t)
Sets the media time.

Parameters:
t - The media time to set
Throws: NotRealizedError
If the Controller is not Realized.
Throws: ClockStartedError
If the Controller is Started.
Overrides:
setMediaTime in class AbstractClock
 o getMediaTime
 public synchronized Time getMediaTime()
Calculates the current media time based on the current time-base time, the time-base start time, the media start time, and the rate.

Returns:
The current media time
Overrides:
getMediaTime in class AbstractClock
 o setRate
 public synchronized float setRate(float rate)
Set the temporal scale factor. The argument suggests the scale factor to use.

The setRate method returns the actual rate set by the Clock. Clocks should set their rate as close to the requested value as possible, but are not required to set the rate to the exact value of any argument other than 1.0. A Clock is only guaranteed to set its rate exactly to 1.0.

Parameters:
rate - The temporal scale factor (rate) to set.
Returns:
The actual rate set.
Throws: NotRealizedError
If the Controller is not Realized.
Throws: ClockStartedError
If the Controller is Started.
Overrides:
setRate in class AbstractClock
 o getDuration
 public Time getDuration()
Returns DURATION_UNKNOWN. This method should be overridden to report a more precise duration.

 o realize
 public final synchronized void realize()
Realize Controller on new thread. Subclasses should override doRealize() to do the actual work to transition the Controller.

Checks for Controller state prerequisites and creates a RealizeThread to realize the AbstractController. If there is already a thread transitioning the AbstractController forward, then the target state of the AbstractController is set to Realized and the method returns.

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

 o prefetch
 public final synchronized void prefetch()
Prefetch Controller on new thread. Subclasses should override doPrefetch() to do the actual work to transition the Controller.

Checks for Controller state prerequisites and creates a PrefetchThread to prefetch the AbstractController. If there is already a thread transitioning the AbstractController forward, then the target state of the AbstractController is set to Prefetched and the method returns.

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

 o syncStart
 public final synchronized void syncStart(Time t)
SyncStart Controller on new thread. Subclasses should override doSyncStart() to do the actual work to transition the Controller.

Checks for Controller state prerequisites and creates a SyncStartThread to syncstart the AbstractController. The target state of the AbstractController is then set to Started and the thread is started.

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

Overrides:
syncStart in class AbstractClock
 o deallocate
 public final synchronized void deallocate()
Deallocate Controller on current thread. Subclasses should override doDeallocate() to do the actual work to transition the Controller. After ensuring state prerequisites, this method will call doDeallocate(). If doDeallocate() returns true, then the Controller is placed in the appropriate state and a DeallocateCompleteEvent is posted. Otherwise, it is assumed that the controller has posted a ControllerErrorEvent detailing the reasons for it's failure.

Synchronous method -- return when transition complete

 o stop
 public final void stop()
Stop Controller on current thread and post a StopByRequestEvent. Subclasses should override doStop() to do the actual work to stop the Controller.

Overrides:
stop in class AbstractClock
 o stopAtTime
 protected void stopAtTime()
Stop Controller on current thread and post a StopAtTimeEvent. Subclasses should override doStop() to do the actual work to stop the Controller.

This method is usually only called (indirectly) by the StopTimeMonitor class.

Synchronous method -- return when transition complete

 o stopInRestart
 protected void stopInRestart()
Stop Controller on current thread and post a RestartingEvent. Subclasses should override doStop() to do the actual work to stop the Controller.

This method is usually only called (indirectly) by Player.setMediaTime() or Player.setRate() when a managed Controller must be stopped before its media time and rate, respectively, can be set.

Synchronous method -- return when transition complete

 o stopController
 protected synchronized boolean stopController()
Stop the controller. If the Controller is Realizing or Prefetching, then the target state will be set to Realized or Prefetched, respectively, and the Controller will stop when it completes the transition. If the Controller is Started, this method will call doStop(). If doStop() returns true, then the Controller is placed in the Prefetched state and a StopEvent is posted. If doStop() returns false, it is assumed that the controller has posted a ControllerErrorEvent detailing the reasons for it's failure.

Synchronous method -- return when transition complete

Returns:
boolean indicating whether the stop was successful.
 o close
 public final synchronized void close()
Close the Controller. Release resources held by this Controller. Subclasses should implement doClose() to add additional functionality.

 o addControl
 public void addControl(Control newControl)
Add a Control to this Controller.

Parameters:
newControl - The Control to add.
 o removeControl
 public void removeControl(Control oldControl)
Remove a Control from this Controller.

Parameters:
oldControl - The Control to remove.
 o getControls
 public Control[] getControls()
Get a list of the Control objects that this Controller supports. If there are no controls, an array of length zero is returned.

Returns:
A list of Controller Controls.
 o getControl
 public Control getControl(String forName)
Get the Control that supports the class or interface specified. The full class or interface name should be specified. Null is returned if the Control is not supported.

Returns:
Control for the given class or interface name, or null if no such Control is supported.
 o addControllerListener
 public void addControllerListener(ControllerListener listener)
Specify a ControllerListener to which this Controller will send events.

Parameters:
listener - The listener to which the Controller will post events.
 o removeControllerListener
 public void removeControllerListener(ControllerListener listener)
Remove the specified listener from this Controller's listener list.

Parameters:
listener - The listener that has been receiving events from this Controller.
 o getPreviousState
 public int getPreviousState()
Get the previous state of this Controller.

 o setState
 protected synchronized void setState(int state)
Set the current state of this Controller. This will implicitly set the previous state as well.

 o getState
 public int getState()
Get the current state of this Controller.

 o setTargetState
 protected void setTargetState(int state)
Set the targetState state of this Controller.

 o getTargetState
 public int getTargetState()
Get the target state of this Controller.

 o endOfMedia
 protected synchronized 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.
 o postEvent
 protected void postEvent(ControllerEvent event)
Post a ControllerEvent to the Media Event Queue

Parameters:
event - The ControllerEvent to post.
 o postTransitionEvent
 protected void postTransitionEvent()
Post a TransitionEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, and Target State properties of the TransitionEvent.

 o postRealizeCompleteEvent
 protected void postRealizeCompleteEvent()
Post a RealizeCompleteEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, and Target State properties of the RealizeCompleteEvent.

 o postPrefetchCompleteEvent
 protected void postPrefetchCompleteEvent()
Post a PrefetchCompleteEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, and Target State properties of the PrefetchCompleteEvent.

 o postDeallocateEvent
 protected void postDeallocateEvent()
Post a DeallocateEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the DeallocateEvent.

 o postStopEvent
 protected void postStopEvent()
Post a StopEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the StopEvent.

 o postStopAtTimeEvent
 protected void postStopAtTimeEvent()
Post a StopAtTimeEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the StopAtTimeEvent.

 o postStartEvent
 protected void postStartEvent()
Post a StartEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, Media Time, and Time-base Time properties of the StartEvent.

 o postDataStarvedEvent
 protected void postDataStarvedEvent()
Post a DataStarvedEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the DataStarvedEvent.

 o postEndOfMediaEvent
 protected void postEndOfMediaEvent()
Post a EndOfMediaEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the EndOfMediaEvent.

 o postRestartingEvent
 protected void postRestartingEvent()
Post a RestartingEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the RestartingEvent.

 o postStopByRequestEvent
 protected void postStopByRequestEvent()
Post a StopByRequestEvent to the Media Event Queue. Automatically fill in the Previous State, Current State, Target State, and Media Time properties of the StopByRequestEvent.

 o postControllerClosedEvent
 protected void postControllerClosedEvent()
Post a ControllerClosedEvent to the Media Event Queue.

 o getThreadQueue
 protected ThreadQueue getThreadQueue()
Gets the ThreadQueue object for this AbstractController.

 o synchronousRealize
 protected void synchronousRealize()
Realize the AbstractController synchronously.

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

Synchronous method -- return when transition complete

 o synchronousPrefetch
 protected void synchronousPrefetch()
Realize the AbstractController synchronously.

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

Synchronous method -- return when transition complete

 o getStartLatency
 public Time getStartLatency()
Returns LATENCY_UNKNOWN. This method should be overridden to report a more precise start latency.

 o synchronousSyncStart
 protected void synchronousSyncStart(Time t)
SyncStart the AbstractController synchronously at the previously-specified time-base start time.

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

Synchronous method -- return when transition complete

 o blockUntilStart
 public void blockUntilStart(Time t)
For a given time-base start time, block until the AbstractController should be started. For a given time- base start time (t), this method will get the AbstractController's start latency (l) and block until (t - l). This method is useful for implementations of doSyncStart().

If the time-base time (t - l) has already passed, return immediately.


All Packages  Class Hierarchy  This Package  Previous  Next  Index