javax.tv.media

Interface MediaSelectControl

All Superinterfaces:

Control

All Known Subinterfaces:

DVBMediaSelectControl

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). A MediaSelectControl which is not associated with a ServiceMediaHandler may also have restrictions on the set of services which it may access.

Instances of MediaSelectControl may be obtained from a JMF Player via the methods getControl(String) and getControls(). 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 entities other than themselves, or as a side-effect of calls to ServiceContext.select(Locator[]). Such changes will be reported to the MediaSelectListeners 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.

If the specified component is already being presented, it will continue to be presented and will not be restarted. A MediaSelectSucceededEvent is generated immediately.

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 set of services 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.

If some of the specified components are already being presented, these components continue to be presented and will not be restarted. Their selection is considered successful and is immediately reported by a MediaSelectSucceededEvent. 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.

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:

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 set of services 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.

IllegalArgumentException - If components is a zero-length array.

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 service component is not part of the set of 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 set of services 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.

No action is performed if the specified MediaSelectListener is already subscribed.

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.

No action is performed if the specified MediaSelectListener is not subscribed.

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.