ServiceContext

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.service.selection
Interface ServiceContext

All Known Subinterfaces:
  DvbServiceContext

    public interface ServiceContext

A `ServiceContext` represents an environment in which services are presented in a broadcast receiver. Applications may use `ServiceContext` objects to select new services to be presented. Content associated with a selected service is presented by one or more `ServiceContentHandler` objects managed by the `ServiceContext`.

A `ServiceContext` can exist in four states - presenting, not presenting, presentation pending and destroyed. The initial state is not presenting.

The `select()` method can be called from any state except destroyed. Assuming no exception is thrown, the service context then enters the presentation pending state. No event is generated on this state transition. If a call to `select()` completes successfully, either a `NormalContentEvent` or an `AlternativeContentEvent` is generated and the `ServiceContext` moves into the presenting state.

If the selection operation fails, a `SelectionFailedEvent` is generated. If the `select()` method is called during the presentation pending state, a `SelectionFailedEvent` with reason code `INTERRUPTED` is generated, and the `ServiceContext` will proceed in the presentation pending state for the most recent `select() call. Otherwise, if the state before the failed select operation was not presenting, the `ServiceContext` will return to that state and a `PresentationTerminatedEvent` be generated. If the state before the failed select operation was presenting, it will attempt to return to that previous state, which can result in a `NormalContentEvent` or `AlternativeContentEvent` if this is possible, or a `PresentationTerminatedEvent` if it is not possible.`

The not presenting state is entered due to service presentation being stopped which is reported by a `PresentationTerminatedEvent`. The stopping of service presentation can be initiated by an application calling the `stop()` method or because some change in the environment makes continued presentation impossible.

The destroyed state is entered by calling the `destroy()` method, and is signaled by a `ServiceContextDestroyedEvent`. Once this state is entered, the `ServiceContext` can no longer be used for any purpose. A destroyed `ServiceContext` will be eligible for garbage collection once all references to it by any applications have been removed.

Note that the ability to select a service for presentation does not imply exclusive rights to the resources required for that presentation. Subsequent attempts to select the same service may fail.

Applications may also use this interface to register for events associated with `ServiceContext` state changes.

See Also:
  `Service`, `ServiceContentHandler`, `NormalContentEvent`, `AlternativeContentEvent`, `SelectionFailedEvent`, `PresentationTerminatedEvent`, `ServiceContextDestroyedEvent`, `ServiceContextListener`

Method Summary
`void` | `addListener(ServiceContextListener listener)` Subscribes a listener to receive events related to this `ServiceContext`.
`void` | `destroy()` Causes the `ServiceContext` to release all resources and enter the destroyed state.
`Service` | `getService()` Reports the `Service` being presented in this `ServiceContext`.
`ServiceContentHandler[]` | `getServiceContentHandlers()` Reports the current collection of ServiceContentHandlers.
`void` | `removeListener(ServiceContextListener listener)` Unsubscribes a listener from receiving events related to this `ServiceContext`.
`void` | `select(Locator[] components)` Selects content by specifying the parts of a service to be presented.
`void` | `select(Service selection)` Selects a service to be presented in this `ServiceContext`.
`void` | `stop()` Causes the `ServiceContext` to stop presenting content and enter the not presenting state.

Method Detail

### select

    void select(Service selection)
                throws SecurityException

  Selects a service to be presented in this `ServiceContext`. If the `ServiceContext` is already presenting content, the new selection replaces the content being presented. If the `ServiceContext` is not presenting, successful conclusion of this method results in the `ServiceContext` entering the presenting state.

  This method is asynchronous and successful completion of the selection is notified by either a `NormalContentEvent` or a `AlternativeContentEvent`. If an exception is thrown when this method is called, the state of the service context does not change. In such a case, any service being presented before this method was called will continue to be presented.

  If the selection process fails after this method returns, a `SelectionFailedEvent` will be generated. In this case, the system will attempt to return to presenting the original service (if any). If this is not possible (due, for example, to issues such as tuning or CA) the `ServiceContext` will enter the not presenting state and a `PresentationTerminatedEvent` will be generated.

  If the `ServiceContext` is currently presenting a service and components of the current service are also to be presented in the newly selected service, these components will continue to be presented and will not be restarted. If the calling application is not a part of the newly selected service and the application lifecycle policy on the receiver dictates that the calling application be terminated, termination of the application will be affected through the application lifecycle API.

  If the provided `Service` is transport-independent, this method will resolve the `Service` to a transport-dependent `Service` before performing the selection. The actual `Service` selected will be reported through the `getService()` method.

  Successful completion of a select operation using this method provides `ServiceContentHandler` instances for all components that are signaled as "auto-start" in the selected service. Upon entering the presenting state, these `ServiceContentHandler` instances will have begun presenting their respective content; `ServiceMediaHandler` instances will be in the started state.

  Parameters:
    `selection` - The `Service` the service to be selected.
  Throws:
    `SecurityException` - If the caller owns this `ServiceContext` but does not have `SelectPermission(selection.getLocator(), "own")`, or if the caller does not own this `ServiceContext` and does not have `SelectPermission(selection.getLocator(), "*")`.
    `IllegalStateException` - If the `ServiceContext` has been destroyed.
  See Also:
    `NormalContentEvent`, `AlternativeContentEvent`, `SelectionFailedEvent`, `PresentationTerminatedEvent`, `Service`, `getService()`, `ServiceContentHandler`, `destroy()`

### select

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

  Selects content by specifying the parts of a service to be presented. If the `ServiceContext` is already presenting content, the new selection replaces the content being presented. If the `ServiceContext` is not presenting, successful conclusion of this method results in the `ServiceContext` entering the presenting state.

  This method is asynchronous and successful completion of the selection is notified by either a `NormalContentEvent` or a `AlternativeContentEvent`. If failure of the selection can be determined when this method is called, an exception will be generated and the state of the `ServiceContext` will not change. In this case, any service being presented before this method was called will continue to be presented.

  If failure of the selection is determined after this method returns, a `SelectionFailedEvent` will be generated. In this case, the implementation of the method will try to return to presenting the original service (if any). If this is not possible (due, for example, to issues such as tuning or CA) the `ServiceContext` will enter the not presenting state and a `PresentationTerminatedEvent` will be generated.

  If the `ServiceContext` is currently presenting a service and components of the current service are also to be presented in the newly selected content, these components will continue to be presented and will not be restarted. If the calling application is not a part of the newly selected content and the application lifecycle policy on the receiver dictates that the calling application be terminated, termination of the application will be affected through the application lifecycle API.

  Successful completion of a select operation using this method provides `ServiceContentHandler` instances for all components that are indicated in the `components` parameter. Upon entering the presenting state, these `ServiceContentHandler` instances will have begun presenting their respective content; `ServiceMediaHandler` instances will be in the started state. This method will not provide `ServiceContentHandler` instances for service components for which a locator is not specified.

  Parameters:
    `components` - An array of `Locator` instances representing the parts of this service to be selected. Each array element must be a locator to either a `ServiceComponent` or content within a service component (such as an Xlet).
  Throws:
    `InvalidLocatorException` - If a `Locator` provided does not reference a selectable service component or selectable content within a service component.
    `InvalidServiceComponentException` - If a specified service component must be presented in conjunction with another service component not contained in `components`, if the specified components are not all members of the same service, or if the specified set of components cannot be presented as a coherent whole.
    `SecurityException` - If, for any valid `i`, the caller owns this `ServiceContext` but does not have `SelectPermission(components[i], "own")`, or if the caller does not own this `ServiceContext` and does not have `SelectPermission(components[i], "*")`.
    `IllegalStateException` - If the `ServiceContext` has been destroyed.
  See Also:
    `NormalContentEvent`, `AlternativeContentEvent`, `SelectionFailedEvent`, `PresentationTerminatedEvent`, `ServiceContentHandler`, `ServiceComponent`

### stop

    void stop()
              throws SecurityException

  Causes the `ServiceContext` to stop presenting content and enter the not presenting state. Resources used in the presentation will be released, associated `ServiceContentHandlers` will cease presentation (`ServiceMediaHandlers` will no longer be in the started state), and a `PresentationTerminatedEvent` will be posted.

  This operation completes asynchronously. No action is performed if the `ServiceContext` is already in the not presenting state.

  Throws:
    `SecurityException` - If the caller owns this `ServiceContext` but does not have `ServiceContextPermission("stop", "own")`, or if the caller does not own this `ServiceContext` and does not have `SelectPermission("stop", "*")`.
    `IllegalStateException` - If the `ServiceContext` has been destroyed.

### destroy

    void destroy()
                 throws SecurityException

  Causes the `ServiceContext` to release all resources and enter the destroyed state. This method indicates that the the `ServiceContext` must cease further activity, and that it will no longer be used. After completion of this method, `ServiceMediaHandler` instances associated with this `ServiceContext` will have become unrealized or will have been closed. If the `ServiceContext` is currently in the presenting or presentation pending state, this method will first stop the `ServiceContext`, causing a `PresentationTerminatedEvent` to be posted. After the `ServiceContext` has moved to the destroyed state, a `ServiceContextDestroyedEvent` will be posted.

  This operation completes asynchronously. No action is performed if the `ServiceContext` is already in the destroyed state.

  Throws:
    `SecurityException` - If the caller does not have permission to call `stop()` on this `ServiceContext`, or if the caller owns this `ServiceContext` but does not have `ServiceContextPermission("destroy", "own")`, or if the caller does not own this `ServiceContext` and does not have `SelectPermission("destroy", "*")`.
  See Also:
    `stop()`

### getServiceContentHandlers

    ServiceContentHandler[] getServiceContentHandlers()
                                                      throws SecurityException

  Reports the current collection of ServiceContentHandlers. A zero-length array is returned if the `ServiceContext` is in in the not presenting or presentation pending states.

  Returns:
    The current `ServiceContentHandler` instances.
  Throws:
    `SecurityException` - If the caller owns this `ServiceContext` but does not have `ServiceContextPermission("getServiceContentHandlers", "own")`, or if the caller does not own this `ServiceContext` and does not have `SelectPermission("getServiceContentHandlers", "*")`.
    `IllegalStateException` - If the `ServiceContext` has been destroyed.

### getService

    Service getService()

  Reports the `Service` being presented in this `ServiceContext`. If the `ServiceContext` is currently presenting a service, the `Service` returned will be a network-dependent representation of the `Service` indicated in the last successful `select()` method call. If the `ServiceContext` is not in the presenting state then `null` is returned.

  Returns:
    The service currently being presented.
  Throws:
    `IllegalStateException` - If the `ServiceContext` has been destroyed.

### addListener

    void addListener(ServiceContextListener listener)

  Subscribes a listener to receive events related to this `ServiceContext`. If the specified listener is currently subscribed, no action is performed.

  Parameters:
    `listener` - The `ServiceContextListener` to subscribe.
  Throws:
    `IllegalStateException` - If the `ServiceContext` has been destroyed.
  See Also:
    `ServiceContextEvent`

### removeListener

    void removeListener(ServiceContextListener listener)

  Unsubscribes a listener from receiving events related to this `ServiceContext`. If the specified listener is not currently subscribed, no action is performed.

  Parameters:
    `listener` - The `ServiceContextListener` to unsubscribe.
  Throws:
    `IllegalStateException` - If the `ServiceContext` has been destroyed.

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

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