com.sun.tv

Class Handler

java.lang.Object

com.sun.tv.Handler

All Implemented Interfaces:

Clock, Controller, Duration, MediaHandler, Player, ServiceContentHandler, ServiceMediaHandler

public class Handler
extends Object
implements ServiceMediaHandler, Player

ServiceMediaHandler represents an handler of service components which are real time media sharing the same clock. A ServiceMediaHandler is associated with the Service currently selected in the ServiceContext from which it was obtained.

See Also:

ServiceContext, MediaSelectControl

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

Constructors

Constructor and Description
Handler(Locator locator, ServiceContextImpl context)

Method Summary

Methods

Modifier and Type	Method and Description
void	addController(Controller newController) Assume control of another Controller.
void	addControllerListener(ControllerListener listener) Specify a ControllerListener to which this Controller will send events.
void	close() Release all resources and cease all activity.
void	deallocate() Abort the current operation and cease any activity that consumes system resources.
Control	getControl(String forName) Get the Control that supports the class or interface specified.
Component	getControlPanelComponent() Obtain the Component that provides the default user interface for controlling this Player.
Control[]	getControls() Get a list of the Control objects that this Controller supports.
Time	getDuration() Get the duration of the media represented by this object.
GainControl	getGainControl() Obtain the object for controlling this Player's audio gain.
long	getMediaNanoseconds() Get this Clock's current media time in nanoseconds.
Time	getMediaTime() Get this Clock's current media time.
float	getRate() Get the current temporal scale factor.
Locator[]	getServiceContentLocators() Reports the portions of the service on which this handler operates.
ServiceContextImpl	getServiceContext()
Locator	getServiceLocator()
Time	getStartLatency() Get the Controller's start latency in nanoseconds.
int	getState() Get the current state of this Controller.
Time	getStopTime() Get the last value successfully set by setStopTime.
Time	getSyncTime() Get the current media time or the time until this Clock will synchronize to its TimeBase.
int	getTargetState() Get the current target state of this Controller.
TimeBase	getTimeBase() Get the TimeBase that this Clock is using.
Component	getVisualComponent() Obtain the display Component for this Player.
Time	mapToTimeBase(Time t) Get the TimeBase time corresponding to the specified media time.
void	prefetch() Process as much data as necessary to reduce the Controller's start latency to the shortest possible time.
void	realize() Construct the media dependent portions of the Controller.
void	removeController(Controller oldController) Stop controlling a Controller.
void	removeControllerListener(ControllerListener listener) Remove the specified listener from this Controller's listener list.
void	setMediaTime(Time now) Set the Clock's media time.
float	setRate(float factor) Set the temporal scale factor.
void	setSource(DataSource source) Set the media source the MediaHandler should use to obtain content.
void	setStopTime(Time stopTime) Set the media time at which you want the Clock to stop.
void	setTimeBase(TimeBase master) Set the TimeBase for this Clock.
void	start() Start the Player as soon as possible.
void	stop() Stop the Clock.
void	syncStart(Time at) Synchronize the current media time to the specified time-base time and start the Clock.
boolean	validHandler()

Methods inherited from class java.lang.Object

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

Constructor Detail

Handler

public Handler(Locator locator,
       ServiceContextImpl context)

Method Detail

getServiceLocator

public Locator getServiceLocator()

getServiceContext

public ServiceContextImpl getServiceContext()

validHandler

public boolean validHandler()

getServiceContentLocators

public Locator[] getServiceContentLocators()

Reports the portions of the service on which this handler operates.

Specified by:

getServiceContentLocators in interface ServiceContentHandler

Returns:

An array of Locators representing the portions of the service on which this handler operates.

See Also:

ServiceContext.select(Locator[] components)

getVisualComponent

public Component getVisualComponent()

Obtain the display Component for this Player. The display Component is where visual media is rendered. If this Player has no visual component, getVisualComponent returns null. For example, getVisualComponent might return null if the Player only plays audio.

Specified by:

getVisualComponent in interface Player

Returns:

The media display Component for this Player.

getGainControl

public GainControl getGainControl()

Obtain the object for controlling this Player's audio gain. If this player does not have a GainControl, getGainControl returns null. For example, getGainControl might return null if the Player does not play audio data.

Specified by:

getGainControl in interface Player

Returns:

The GainControl object for this Player.

getControlPanelComponent

public Component getControlPanelComponent()

Obtain the Component that provides the default user interface for controlling this Player. If this Player has no default control panel, getControlPanelComponent returns null.

Specified by:

getControlPanelComponent in interface Player

Returns:

The default control panel GUI for this Player.

start

public void start()

Start the Player as soon as possible. The start method attempts to transition the Player to the Started state. If the Player has not been Realized or Prefetched, start automatically performs those actions. The appropriate events are posted as the Player moves through each state.

Specified by:

start in interface Player

addController

public void addController(Controller newController)
                   throws IncompatibleTimeBaseException

Assume control of another Controller.

Specified by:

addController in interface Player

Parameters:

newController - The Controller to be managed.

Throws:

IncompatibleTimeBaseException - Thrown if the added Controller cannot take this Player's TimeBase.

removeController

public void removeController(Controller oldController)

Stop controlling a Controller.

Specified by:

removeController in interface Player

Parameters:

oldController - The Controller to stop managing.

setSource

public void setSource(DataSource source)
               throws IOException,
                      IncompatibleSourceException

Set the media source the MediaHandler should use to obtain content.

Specified by:

setSource in interface MediaHandler

Parameters:

source - The DataSource used by this MediaHandler.

Throws:

IOException - Thrown if there is an error using the DataSource

IncompatibleSourceException - Thrown if this MediaHandler cannot make use of the DataSource.

getState

public int getState()

Get the current state of this Controller. The state is an integer constant as defined above.

Note: A race condition can occur between the return of this method and the execution of a state changing method.

Specified by:

getState in interface Controller

Returns:

The Controller's current state.

getTargetState

public int getTargetState()

Get the current target state of this Controller. The state is an integer constant as defined above.

Note: A race condition can occur between the return of this method and the execution of a state changing method.

Specified by:

getTargetState in interface Controller

Returns:

The Controller's current target state.

realize

public void realize()

Construct the media dependent portions of the Controller. This can require examining media data and might take some time to complete.

The realize method puts the Controller into the Realizing state and returns immediately. When realize is complete and the Controller is in the Realized state, the Controller posts a RealizeCompleteEvent.

Specified by:

realize in interface Controller

prefetch

public void prefetch()

Process as much data as necessary to reduce the Controller's start latency to the shortest possible time. This typically requires examining media data and takes some time to complete.

The prefetch method puts the Controller into the Prefetching state and returns immediately. When Prefetching is complete and the Controller is in the Prefetched state, the Controller posts a PrefetchCompleteEvent.

Specified by:

prefetch in interface Controller

deallocate

public void deallocate()

Abort the current operation and cease any activity that consumes system resources. If a Controller is not yet Realized, it returns to the Unrealized state. Otherwise, the Controller returns to the Realized state.

It is illegal to call deallocate on a Started Controller. A ClockStartedError is thrown if deallocate is called and the Controller is in the Started state.

Specified by:

deallocate in interface Controller

close

public void close()

Release all resources and cease all activity. The close method indicates that the Controller will no longer be used, and the Controller can shut itself down. A ControllerClosedEvent is posted. Methods invoked on a closed Controller might throw errors.

Specified by:

close in interface Controller

getStartLatency

public Time getStartLatency()

Get the Controller's start latency in nanoseconds. The start latency represents a worst-case estimate of the amount of time it will take to present the first frame of data.

This method is useful for determining how far in advance the syncStart method must be invoked to ensure that media will be rendered at the specified start time.

For a Controller that has a variable start latency, the value returned represents the maximum possible start latency. If you call getStartLatency on a Controller that isn't Prefetched and getStartLatency returns LATENCY_UNKNOWN, calling prefetch and then calling getStartLatency again after the Controller posts a PrefetchCompleteEvent might return a more accurate estimate. If getStartLatency still returns LATENCY_UNKNOWN, the start latency is indeterminate and you might not be able to use syncStart to synchronize the Controller with other Controllers.

Note: In most cases, the value returned by getStartLatency will change once the Controller is Prefetched.

Specified by:

getStartLatency in interface Controller

Returns:

The time it will take before the first frame of media can be presented.

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.

Specified by:

getControls in interface Controller

Returns:

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

addControllerListener

public void addControllerListener(ControllerListener listener)

Specify a ControllerListener to which this Controller will send events. A Controller can have multiple ControllerListeners.

Specified by:

addControllerListener in interface Controller

Parameters:

listener - The listener to which the Controller will post events.

removeControllerListener

public void removeControllerListener(ControllerListener listener)

Remove the specified listener from this Controller's listener list.

Specified by:

removeControllerListener in interface Controller

Parameters:

listener - The listener that has been receiving events from this Controller.

getDuration

public Time getDuration()

Get the duration of the media represented by this object. The value returned is the media's duration when played at the default rate. If the duration can't be determined (for example, the media object is presenting live video) getDuration returns DURATION_UNKNOWN.

Specified by:

getDuration in interface Duration

Returns:

A Time object representing the duration or DURATION_UNKNOWN.

setTimeBase

public void setTimeBase(TimeBase master)
                 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).

Specified by:

setTimeBase in interface Clock

Parameters:

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

syncStart

public void syncStart(Time at)

Synchronize the current media time to the specified time-base time and start the Clock. The syncStart method sets the time-base start-time, and puts the Clock in the Started state. This method can only be called on a Stopped Clock. A ClockStartedError is thrown if setTimeBase is called on a Started Clock.

Specified by:

syncStart in interface Clock

Parameters:

at - The time-base time to equate with the current media time.

stop

public void stop()

Stop the Clock. Calling stop releases the Clock from synchronization with the TimeBase. After this request is issued, the Clock is in the Stopped state. If stop is called on a Stopped Clock, the request is ignored.

Specified by:

stop in interface Clock

setStopTime

public void setStopTime(Time stopTime)

Set the media time at which you want the Clock to stop. The Clock will stop when its media time passes the stop-time. To clear the stop time, set it to: Clock.RESET.

You can always call setStopTime on a Stopped Clock.

On a Started Clock, the stop-time can only be set once. A StopTimeSetError is thrown if setStopTime is called and the media stop-time has already been set.

Specified by:

setStopTime in interface Clock

Parameters:

stopTime - The time at which you want the Clock to stop, in media time.

getStopTime

public Time getStopTime()

Get the last value successfully set by setStopTime. Returns the constant Clock.RESET if no stop time is set. (Clock.RESET is the default stop time.)

Specified by:

getStopTime in interface Clock

Returns:

The current stop time.

setMediaTime

public void setMediaTime(Time now)

Set the Clock's media time. This method can only be called on a Stopped Clock. A ClockStartedError is thrown if setMediaTime is called on a Started Clock.

Specified by:

setMediaTime in interface Clock

Parameters:

now - The new media time.

getMediaTime

public Time getMediaTime()

Get this Clock's current media time. A Started Clock's media time is based on its TimeBase and rate, as described in Starting a Clock.

Specified by:

getMediaTime in interface Clock

Returns:

The current media time.

getMediaNanoseconds

public long getMediaNanoseconds()

Get this Clock's current media time in nanoseconds.

Specified by:

getMediaNanoseconds in interface Clock

Returns:

The current media time in nanoseconds.

getSyncTime

public Time getSyncTime()

Get the current media time or the time until this Clock will synchronize to its TimeBase. The getSyncTime method is used by Players and advanced applet writers to synchronize Clocks.

Like getMediaTime, this method returns the Clock's current media time, which is based on its TimeBase and rate. However, when syncStart is used to start the Clock, getSyncTime performs a countdown to the time-base start-time, returning the time remaining until the time-base start-time. Once the TimeBase reaches the time-base start-time, getSyncTime and getMediaTime will return the same value.

Specified by:

getSyncTime in interface Clock

getTimeBase

public TimeBase getTimeBase()

Get the TimeBase that this Clock is using.

Specified by:

getTimeBase in interface Clock

mapToTimeBase

public Time mapToTimeBase(Time t)
                   throws ClockStoppedException

Get the TimeBase time corresponding to the specified media time.

Specified by:

mapToTimeBase in interface Clock

Parameters:

t - The media time to map from.

Returns:

The time-base time in media-time coordinates.

Throws:

ClockStoppedException - Thrown if mapToTimeBase is called on a Stopped Clock.

getRate

public float getRate()

Get the current temporal scale factor. The scale factor defines the relationship between the Clock's media time and its TimeBase.

For example, a rate of 2.0 indicates that media time will pass twice as fast as the TimeBase time once the Clock starts. Similarly, a negative rate indicates that the Clock runs in the opposite direction of its TimeBase. All Clocks are guaranteed to support a rate of 1.0, the default rate. Clocks are not required to support any other rate.

Specified by:

getRate in interface Clock

setRate

public float setRate(float factor)

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.

You can only call this method on a Stopped Clock. A ClockStartedError is thrown if setRate is called on a Started Clock.

Specified by:

setRate in interface Clock

Parameters:

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

Returns:

The actual rate set.