MediaSelectControl

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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).

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.

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

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

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

  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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD