Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

javax.tv.media
Interface MediaSelectControl

All Superinterfaces:

Control

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. Such changes will be reported to the MediaSelectListeners currently registered.

See Also:

Player, Controller.getControls(), ServiceMediaHandler, ServiceContext

Method Summary

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

public void select(Locator component)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   InsufficientResourcesException,
                   java.lang.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 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.

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

select

public void select(Locator[] components)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   InsufficientResourcesException,
                   java.lang.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 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.

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

java.lang.IllegalArgumentException - If components is a zero-length array.

add

public void add(Locator component)
         throws InvalidLocatorException,
                InvalidServiceComponentException,
                InsufficientResourcesException,
                java.lang.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.

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

remove

public void remove(Locator component)
            throws InvalidLocatorException,
                   InvalidServiceComponentException,
                   java.lang.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.

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

replace

public void replace(Locator fromComponent,
                    Locator toComponent)
             throws InvalidLocatorException,
                    InvalidServiceComponentException,
                    InsufficientResourcesException,
                    java.lang.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.

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

addMediaSelectListener

public 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

public 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

public Locator[] getCurrentSelection()

Reports the components of the current selection.

Returns:

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