javax.tv.media

Interface MediaSelectControl

All Superinterfaces:

Control

All Known Subinterfaces:

DVBMediaSelectControl

All Known Implementing Classes:

MediaSelectControlImpl

public interface MediaSelectControl
extends Control

MediaSelectControl allows the selection of different kinds of content in a running Player. It serves as a high level demultiplex control, where the selection is specified by locators indicating one or more service components to present.

If the Player on which a MediaSelectControl operates is an instance of ServiceMediaHandler, then MediaSelectControl is restricted to operating only on service components belonging to the service with which the ServiceMediaHandler is associated (that is, the ServiceContext's currently selected service).

Instances of MediaSelectControl may be obtained from a JMF Player via the methods getControl(String) and getControls(). Note that a Java TV API implementation may not always or ever support MediaSelectControl for a given Player; in such a case, the failure modes specified by the two aforementioned methods will apply. Applications should note that the set of selected service components can be changed by other entities apart from themselves. Such changes will be reported by a MediaSelectEvent being sent if a MediaSelectListener is currently registered.

See Also:

Player, Controller.getControls(), ServiceMediaHandler, ServiceContext

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Locator component) Adds a service component (for example, subtitles) to the presentation.
void	addMediaSelectListener(MediaSelectListener listener) Subscribes the specified MediaSelectListener to receive events related to media selection on this Player.
Locator[]	getCurrentSelection() Reports the components of the current selection.
void	remove(Locator component) Removes a service component from the presentation.
void	removeMediaSelectListener(MediaSelectListener listener) Unsubscribes the specified MediaSelectListener from receiving events related to media selection on this Player.
void	replace(Locator fromComponent, Locator toComponent) Replaces a service component in the presentation.
void	select(Locator component) Selects a new service component for presentation.
void	select(Locator[] components) Selects one or more service components for presentation.

Methods inherited from interface javax.media.Control

getControlComponent

Method Detail

select

void select(Locator component)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   InsufficientResourcesException,
                   SecurityException

Selects a new service component for presentation. If some content is currently playing, it is replaced in its entirety by the specified selection. This is an asynchronous operation that is completed upon receipt of a MediaSelectEvent. Note that for certain selections that imply a different time base or otherwise change synchronization relationships, a RestartingEvent will be posted by the Player.

Parameters:

component - A locator representing an individual service component to present.

Throws:

InvalidLocatorException - If the locator does not reference a selectable service component.

InvalidServiceComponentException - If the specified service component is not part of the Service to which the MediaSelectControl is restricted, or if it cannot be presented alone.

InsufficientResourcesException - If the operation cannot be completed due to a lack of system resources.

SecurityException - If the caller does not have MediaSelectPermission(component) permission.

select

void select(Locator[] components)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   InsufficientResourcesException,
                   SecurityException

Selects one or more service components for presentation. If some content is currently playing, it is replaced in its entirety by the specified selection. This is an asynchronous operation that is completed on receipt of a MediaSelectEvent. Note that for certain selections that imply a different time base or otherwise change synchronization relationships, a RestartingEvent will be posted by the Player. If some of the specified components are successfully selected and others are not, a MediaSelectSucceededEvent is generated with the locator array containing only those components that were successfully selected.

Parameters:

components - An array of locators representing a set of individual service components to present together.

Throws:

InvalidLocatorException - If a locator provided does not reference a selectable service component.

InvalidServiceComponentException - If a specified service component is not part of the Service to which the MediaSelectControl is restricted, if a specified service component must be presented in conjunction with another service component not contained in components, if the specified set of service components cannot be presented as a coherent whole, or if the service components are not all available simultaneously.

InsufficientResourcesException - If the operation cannot be completed due to a lack of system resources.

SecurityException - If the caller does not have MediaSelectPermission(components[i]) permission for any valid i.

add

void add(Locator component)
         throws InvalidLocatorException,
                InvalidServiceComponentException,
                InsufficientResourcesException,
                SecurityException

Adds a service component (for example, subtitles) to the presentation. This is an asynchronous operation that is completed on receipt of a MediaSelectEvent. Components whose addition would require Player resynchronization are not permitted. If the specified service component is already part of the presentation, this method does nothing.

Parameters:

component - The locator representing an individual service component to add to the presentation.

Throws:

InvalidLocatorException - If the specified locator does not reference a selectable service component.

InvalidServiceComponentException - If the addition of the service component would require resynchronization of the Player, If the specified service component is not part of the Service or Services to which the MediaSelectControl is restricted, or if the service component must be presented in conjunction with another service component that is not part of the current presentation.

InsufficientResourcesException - If the operation cannot be completed due to a lack of system resources.

SecurityException - If the caller does not have MediaSelectPermission(component) permission.

remove

void remove(Locator component)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   SecurityException

Removes a service component from the presentation. This is an asynchronous operation that is completed on receipt of a MediaSelectEvent. Components whose removal would require Player resynchronization are not permitted.

Parameters:

component - The locator representing an individual service component to remove from the presentation.

Throws:

InvalidLocatorException - If the specified locator does not reference a service component in the current selection.

InvalidServiceComponentException - If removal of the specified service component would require resynchronization of the Player, or if another service component in the current presentation must be presented in conjunction with component.

SecurityException - If the caller does not have MediaSelectPermission(component) permission.

replace

void replace(Locator fromComponent,
           Locator toComponent)
             throws InvalidLocatorException,
                    InvalidServiceComponentException,
                    InsufficientResourcesException,
                    SecurityException

Replaces a service component in the presentation. This is an asynchronous operation that is completed on receipt of a MediaSelectEvent. Components whose replacement would require Player resynchronization are not permitted.

Parameters:

fromComponent - The locator that represents the service component to remove from the presentation.

toComponent - The locator that represents the service component to add to the presentation.

Throws:

InvalidLocatorException - If fromComponent does not reference a service component in the current selection, or if toComponent does not reference a selectable service component.

InvalidServiceComponentException - If toComponent references a service component that is not part of the Service to which the MediaSelectControl is restricted, if fromComponent or toComponent reference service components for which this operation would require resynchronization of the Player, if another service component in the current presentation must be presented in conjunction with fromComponent, or if toComponent must be presented in conjunction with a service component not in the resulting presentation.

InsufficientResourcesException - If the operation cannot be completed due to a lack of system resources.

SecurityException - If the caller does not have MediaSelectPermission(fromComponent) and MediaSelectPermission(toComponent) permission.

addMediaSelectListener

void addMediaSelectListener(MediaSelectListener listener)

Subscribes the specified MediaSelectListener to receive events related to media selection on this Player. If the specified listener is currently subscribed, no action is performed.

Parameters:

listener - The MediaSelectListener to which to send events.

removeMediaSelectListener

void removeMediaSelectListener(MediaSelectListener listener)

Unsubscribes the specified MediaSelectListener from receiving events related to media selection on this Player.

Parameters:

listener - The MediaSelectListener to unsubscribe.

getCurrentSelection

Locator[] getCurrentSelection()

Reports the components of the current selection.

Returns:

An array of locators representing the service components in the current selection.