MediaController (mhp-1.1.2 1.1 API)

java.lang.Object
- com.sun.tv.media.MediaController

All Implemented Interfaces:

EventListener, Clock, Controller, ControllerListener, Duration

Direct Known Subclasses:

AMController, MediaPlayer
```
public abstract class MediaController
extends Object
implements Controller, ControllerListener, Duration, EventListener
```
This class is a part of the porting layer implementation for JavaTV. Media Controller implements the basic functionalities of a java.media.Controller. These include:<
- The clock calculations using the MediaClock helper class.
- The RealizeWorkThread and PrefetchWorkThread to implement realize() and prefetch() in the correct unblocking manner.
- The ListenerList to maintain the list of ControllerListener.
- Two ThreadedEventQueues for incoming and outgoing ControllerEvents.
Version:

1.61, 98/11/02

Field Summary

Fields
Modifier and Type Field and Description

protected Controller parent

protected int state
- 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

Fields
Modifier and Type	Field and Description
`protected Controller`	`parent`
`protected int`	`state`

Constructor Summary

Constructors
Constructor and Description

MediaController()
constructs media controller.

Constructors
Constructor and Description
`MediaController()` constructs media controller.

Method Summary

Methods
Modifier and Type	Method and Description
`protected abstract void`	`abortPrefetch()` Called when the prefetch() is aborted, i.e.
`protected abstract void`	`abortRealize()` Called when the realize() is aborted, i.e.
`void`	`addControllerListener(ControllerListener listener)` Add a listener to the listenerList.
`protected void`	`cleanup()` stops send and receive threads
`void`	`close()` A subclass of this implement close to stop all threads to make it "finalizable", i.e., ready to be garbage collected.
`protected void`	`completePrefetch()` Called when the controller is prefetched and when all the PrefetchCompleteEvents from down stream nodes have been received.
`protected void`	`completeRealize()` Called when the controller is realized and when all the RealizeCompleteEvents from down stream Controllers have been received.
`void`	`controllerUpdate(ControllerEvent evt)` This get called when some Controller notifies this controller of any event.
`void`	`deallocate()` Release the resouces held by the controller.
`protected void`	`dispatchEvent(ControllerEvent evt)` An internal function to notify the listeners on the listener list the given event.
`protected void`	`doClose()` Invoked by close() to cleanup the Controller.
`protected void`	`doDeallocate()` Called by deallocate().
`protected void`	`doFailedPrefetch()` Called when the prefetch() has failed.
`protected void`	`doFailedRealize()` Called when realize() has failed.
`protected abstract boolean`	`doPrefetch()` The stub function to perform the steps to prefetch the controller.
`protected abstract boolean`	`doRealize()` The stub function to perform the steps to realize the controller.
`protected float`	`doSetRate(float factor)`
`protected abstract void`	`doStart()` Start immediately.
`protected void`	`doStop()` Invoked from stop().
`Control`	`getControl(String forName)` Get the `Control` that supports the class or interface specified.
`Control[]`	`getControls()` Return a list of Control objects this Controller supports.
`Time`	`getDuration()` Return the duration of the media.
`protected Time`	`getMediaClockTime()` For subclasses to access to the theoretical clock time as computed by MediaClock.
`long`	`getMediaNanoseconds()` Get the current media time in nanoseconds.
`Time`	`getMediaTime()` Return the current media time.
`float`	`getRate()` Get the current presentation speed.
`Time`	`getStartLatency()` Returns the start latency.
`int`	`getState()` Get the current state of the controller.
`Time`	`getStopTime()` Get the preset stop time.
`Time`	`getSyncTime()` Return the Sync Time.
`int`	`getTargetState()` Get the current target state.
`TimeBase`	`getTimeBase()` Get the current time base.
`Time`	`mapToTimeBase(Time t)` Map the given media-time to time-base-time.
`void`	`prefetch()` Take the necessary steps to prefetch the controller.
`protected void`	`processEvent(ControllerEvent evt)` Process one event from another Controller which we are listening to.
`void`	`realize()` Take the necessary steps to realize the controller.
`void`	`removeControllerListener(ControllerListener listener)` Remove a listener from the list of listeners.
`protected void`	`sendEvent(ControllerEvent evt)` Send an event to the listeners listening to my events.
`protected void`	`setMediaLength(long t)` Set the duration of the media in nanoseconds.
`void`	`setMediaTime(Time now)` Set the media time.
`float`	`setRate(float factor)` Set the rate of presentation: 1.0: normal, 2.0: twice the speed.
`void`	`setStopTime(Time t)` Set the stop time.
`protected void`	`setTargetState(int state)` Set the target state.
`void`	`setTimeBase(TimeBase tb)` Set the timebase used by the controller.
`void`	`stop()` Stop the controller.
`protected void`	`stopAtTime()` Stop because stop time has been reached.
`void`	`syncStart(Time tbt)` Start the controller.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - state
```
protected int state
```
  - parent
```
protected Controller parent
```
- Constructor Detail
  - MediaController
```
public MediaController()
```
    constructs media controller. Initializes the send and receive queues and the clock
- Method Detail
  - doRealize
```
protected abstract boolean doRealize()
```
    The stub function to perform the steps to realize the controller. Call realize() for the public method. This is called from a separately running thread. So do take necessary precautions to protect shared resources. It's OK to put an empty stub function body here.
    Return true if the realize is successful. Return false and set the processError string if failed.
    This function is not declared synchronized because first it is already guaranteed by realize() not to be called more than once simultaneously. Secondly if this is synchronized, then other synchronized methods, deallocate() and processEvent() will be blocked since they are synchronized methods. Override this to implement subclass behavior.
    
    Returns:
    true if successful.
  - abortRealize
```
protected abstract void abortRealize()
```
    Called when the realize() is aborted, i.e. deallocate() was called while realizing. Release all resources claimed previously by the realize() call. Override this to implement subclass behavior.
  - doPrefetch
```
protected abstract boolean doPrefetch()
```
    The stub function to perform the steps to prefetch the controller. Call prefetch for the public method. This is called from a separately running thread. So do take necessary precautions to protect shared resources. It's OK to put an empty stub function body here.
    Return true if the prefetch is successful. Return false and set the processError string if failed.
    This function is not declared synchronized because first it is already guaranteed by realize() not to be called more than once simultaneously. Secondly if this is synchronized, then other synchronized methods, deallocate() and processEvent() will be blocked since they are synchronized methods. Override this to implement subclass behavior.
    
    Returns:
    true if successful.
  - abortPrefetch
```
protected abstract void abortPrefetch()
```
    Called when the prefetch() is aborted, i.e. deallocate() was called while prefetching. Release all resources claimed previously by the prefetch call. Override this to implement subclass behavior.
  - doStart
```
protected abstract void doStart()
```
    Start immediately. Invoked from start(tbt) when the scheduled start time is reached. Use the public start(tbt) method for the public interface. Override this to implement subclass behavior.
  - doStop
```
protected void doStop()
```
    Invoked from stop(). Override this to implement subclass behavior.
  - close
```
public void close()
```
    A subclass of this implement close to stop all threads to make it "finalizable", i.e., ready to be garbage collected.
    
    Specified by:
    
    close in interface Controller
  - doClose
```
protected void doClose()
```
    Invoked by close() to cleanup the Controller. Override this to implement subclass behavior.
  - cleanup
```
protected final void cleanup()
```
    stops send and receive threads
  - setTimeBase
```
public void setTimeBase(TimeBase tb)
                 throws IncompatibleTimeBaseException
```
    Set the timebase used by the controller. i.e. all media-time to time-base-time will be computed with the given time base. The subclass should implement and further specialized this method to do the real work. But it should also invoke this method to maintain the correct states.
    
    Specified by:
    
    setTimeBase in interface Clock
    
    Parameters:
    tb - the time base to set to.
    
    Throws:
    
    IncompatibleTimeBaseException - is thrown if the Controller cannot accept the given time base.
  - getControls
```
public Control[] getControls()
```
    Return a list of Control objects this Controller supports. If there are no controls, then an array of length zero is returned.
    
    Specified by:
    
    getControls in interface Controller
    
    Returns:
    list of Controller controls.
  - 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.
    
    Specified by:
    
    getControl in interface Controller
    
    Returns:
    Control for the class or interface name.
  - syncStart
```
public void syncStart(Time tbt)
```
    Start the controller. Invoke clock.start() to maintain the clock states. It starts a wait thread to wait for the given tbt. At tbt, it will wake up and call doStart(). A subclass should implement the doStart() method to do the real work.
    
    Specified by:
    
    syncStart in interface Clock
    
    Parameters:
    tbt - the timebase time to start the controller.
  - stop
```
public void stop()
```
    Stop the controller. Invoke clock.stop() to maintain the clock states. The subclass should implement and further specialized this method to do the real work. But it should also invoke this method to maintain the correct states.
    
    Specified by:
    
    stop in interface Clock
  - stopAtTime
```
protected void stopAtTime()
```
    Stop because stop time has been reached. Subclasses should override this method.
  - setStopTime
```
public void setStopTime(Time t)
```
    Set the stop time. Invoke clock.setStopTime() to maintain the clock states. The subclass should implement and further specialized this method to do the real work. But it should also invoke this method to maintain the correct states.
    
    Specified by:
    
    setStopTime in interface Clock
    
    Parameters:
    t - the time to stop.
  - getStopTime
```
public Time getStopTime()
```
    Get the preset stop time.
    
    Specified by:
    
    getStopTime in interface Clock
    
    Returns:
    the preset stop time.
  - setMediaTime
```
public void setMediaTime(Time now)
```
    Set the media time. Invoke clock.setMediaTime() to maintain the clock states. The subclass should implement and further specialized this method to do the real work. But it should also invoke this method to maintain the correct states.
    
    Specified by:
    
    setMediaTime in interface Clock
    
    Parameters:
    now - the media time to set to.
  - getMediaTime
```
public Time getMediaTime()
```
    Return the current media time. Uses the clock to do the computation. A subclass can override this method to do the right thing for itself.
    
    Specified by:
    
    getMediaTime in interface Clock
    
    Returns:
    the current media time.
  - getMediaNanoseconds
```
public long getMediaNanoseconds()
```
    Get the current media time in nanoseconds.
    
    Specified by:
    
    getMediaNanoseconds in interface Clock
    
    Returns:
    the media time in nanoseconds.
  - getMediaClockTime
```
protected final Time getMediaClockTime()
```
    For subclasses to access to the theoretical clock time as computed by MediaClock. Normally, getMediaTime() would return the same value. But some classes might choose to override getMediaTime(). And in those cases, getMediaClockTime() will bypass that and give you the theoretical time.
  - getSyncTime
```
public Time getSyncTime()
```
    Return the Sync Time. Not yet implementated.
    
    Specified by:
    
    getSyncTime in interface Clock
  - getTimeBase
```
public TimeBase getTimeBase()
```
    Get the current time base.
    
    Specified by:
    
    getTimeBase in interface Clock
    
    Returns:
    the current time base.
  - mapToTimeBase
```
public Time mapToTimeBase(Time t)
                   throws ClockStoppedException
```
    Map the given media-time to time-base-time.
    
    Specified by:
    
    mapToTimeBase in interface Clock
    
    Parameters:
    t - given media time.
    
    Returns:
    timebase time.
    
    Throws:
    
    ClockStoppedException - thrown if the Controller has already been stopped.
  - setRate
```
public float setRate(float factor)
```
    Set the rate of presentation: 1.0: normal, 2.0: twice the speed. -2.0: twice the speed in reverse. Note that not all rates are supported. Invokes clock.setRate() to maintain the clock states. The subclass SHOULDN'T in general override this class. If necessary, it should override the behavior using the doSetRate method. By overriding the doSetRate method, subclass Conrollers can support negative rates, fractional rates etc., but they should guard against illegal rates from going into the clock calculations.
    
    Specified by:
    
    setRate in interface Clock
    
    Parameters:
    factor - the rate to set to.
    
    Returns:
    the actual rate used.
  - doSetRate
```
protected float doSetRate(float factor)
```
  - getRate
```
public float getRate()
```
    Get the current presentation speed.
    
    Specified by:
    
    getRate in interface Clock
    
    Returns:
    the current presentation speed.
  - getState
```
public final int getState()
```
    Get the current state of the controller.
    
    Specified by:
    
    getState in interface Controller
    
    Returns:
    the current state of the controller.
  - setTargetState
```
protected final void setTargetState(int state)
```
    Set the target state.
  - getTargetState
```
public final int getTargetState()
```
    Get the current target state.
    
    Specified by:
    
    getTargetState in interface Controller
    
    Returns:
    the current target state.
  - getStartLatency
```
public Time getStartLatency()
```
    Returns the start latency. Don't know until the particular node is implemented.
    
    Specified by:
    
    getStartLatency in interface Controller
    
    Returns:
    the start latency.
  - getDuration
```
public Time getDuration()
```
    Return the duration of the media. It's unknown until we implement a particular node.
    
    Specified by:
    
    getDuration in interface Duration
    
    Returns:
    the duration of the media.
  - setMediaLength
```
protected void setMediaLength(long t)
```
    Set the duration of the media in nanoseconds.
    
    Parameters:
    t - duration in nanoseconds.
  - realize
```
public final void realize()
```
    Take the necessary steps to realize the controller. This is a non-blocking call. It starts a work thread to do the real work. The actual code to do the realizing should be written in doRealize(). The thread is also responsible for catching all the RealizeCompleteEvents from the down stream nodes. When the steps to realize the controller are completed and when all the RealizeCompleteEvents from down stream nodes have been received, the completeRealize() call will be invoked.
    
    Specified by:
    
    realize in interface Controller
  - completeRealize
```
protected void completeRealize()
```
    Called when the controller is realized and when all the RealizeCompleteEvents from down stream Controllers have been received. If a subclass wants to override this method, it should still invoke this to ensure the correct events being sent to the upstream Controllers.
  - doFailedRealize
```
protected void doFailedRealize()
```
    Called when realize() has failed.
  - prefetch
```
public final void prefetch()
```
    Take the necessary steps to prefetch the controller. This is a non-blocking call. It starts a work thread to do the real work. The actual code to do the realizing should be written in doPrefetch(). The thread is also responsible for catching all the PrefetchCompleteEvents from the down stream nodes. When the steps to prefetch the controller are completed and when all the PrefetchCompleteEvents from down stream nodes have been received, the completePrefetch() call will be invoked.
    
    Specified by:
    
    prefetch in interface Controller
  - completePrefetch
```
protected void completePrefetch()
```
    Called when the controller is prefetched and when all the PrefetchCompleteEvents from down stream nodes have been received. If a subclass wants to override this method, it should still invoke this to ensure the correct events being sent to the upstream Controllers.
  - doFailedPrefetch
```
protected void doFailedPrefetch()
```
    Called when the prefetch() has failed.
  - deallocate
```
public final void deallocate()
```
    Release the resouces held by the controller. It obeys strict rules as specified in the spec. Implement the abortRealize and abortPrefetch methods to actually do the work.
    
    Specified by:
    
    deallocate in interface Controller
  - doDeallocate
```
protected void doDeallocate()
```
    Called by deallocate(). Subclasses should implement this for its specific behavior.
  - addControllerListener
```
public final void addControllerListener(ControllerListener listener)
```
    Add a listener to the listenerList. This listener will be notified of this controller's event. This needs to be a synchronized method so as to maintain the integrity of the listenerList.
    
    Specified by:
    
    addControllerListener in interface Controller
    
    Parameters:
    listener - controller listener to be added to the list of listeners
  - removeControllerListener
```
public final void removeControllerListener(ControllerListener listener)
```
    Remove a listener from the list of listeners. This needs to be a synchronized method so as to maintain the integrity of the listenerList.
    
    Specified by:
    
    removeControllerListener in interface Controller
    
    Parameters:
    listener - listener to be removed from the list of listeners
  - sendEvent
```
protected final void sendEvent(ControllerEvent evt)
```
    Send an event to the listeners listening to my events. The event is Queued in the sendEvtQueue which runs in a separate thread. This way, sendEvent() won't be blocked.
    
    Parameters:
    evt - event to be sent
  - dispatchEvent
```
protected final void dispatchEvent(ControllerEvent evt)
```
    An internal function to notify the listeners on the listener list the given event. This gets called by the sendEvtQueue's processEvent() callback. This method updates a lock on the Vector listenerList before enumerating it.
  - controllerUpdate
```
public final void controllerUpdate(ControllerEvent evt)
```
    This get called when some Controller notifies this controller of any event. We queue that event in the recvEvtQueue to be handled later. This way, the calling controller won't get blocked. This doesn't have to be synchronized since the recvEvtQueue already handles the locking.
    
    Specified by:
    
    controllerUpdate in interface ControllerListener
    
    Parameters:
    evt - The event generated.
  - processEvent
```
protected void processEvent(ControllerEvent evt)
```
    Process one event from another Controller which we are listening to. This is invoked by the recvEvtQueue when there is at least one event in the queue. If you need to extend this methods, please also invoke this such that the events can be catched by the work threads.
    
    Parameters:
    evt - controller event to be processed

Class MediaController

Field Summary

Fields inherited from interface javax.media.Controller

Fields inherited from interface javax.media.Clock

Fields inherited from interface javax.media.Duration

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

state

parent

Constructor Detail

MediaController

Method Detail

doRealize

abortRealize

doPrefetch

abortPrefetch

doStart

doStop

close

doClose

cleanup

setTimeBase

getControls

getControl

syncStart

stop

stopAtTime

setStopTime

getStopTime

setMediaTime

getMediaTime

getMediaNanoseconds

getMediaClockTime

getSyncTime

getTimeBase

mapToTimeBase

setRate

doSetRate

getRate

getState

setTargetState

getTargetState

getStartLatency

getDuration

setMediaLength

realize

completeRealize

doFailedRealize

prefetch

completePrefetch

doFailedPrefetch

deallocate

doDeallocate

addControllerListener

removeControllerListener

sendEvent

dispatchEvent

controllerUpdate

processEvent