SIManager

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
Class SIManager

    java.lang.Object
      javax.tv.service.SIManager

    public abstract class SIManager

extends Object

An `SIManager` represents a managing entity which has knowledge of all the broadcast resources available to a receiver. An `SIManager` can be used to retrieve any `SIElement` or create a collection of `Service` objects according to filtering rules.

An `SIManager` may also be used to set parameters such as the preferred language for multilingual text information. Normally an application will create a single instance of `SIManager` and use that instance to access all SI information. If an application creates more than one instance of `SIManager` it may experience degraded caching performance, particularly if the `SIManager` instances use different preferred languages.

See Also:
  `Service`, `SIElement`

Method Summary
`static SIManager` | `createInstance()` Creates a new instance of `SIManager`.
`abstract ServiceList` | `filterServices(ServiceFilter filter)` Filters the available services using the `ServiceFilter` provided to generate a `ServiceList` containing the matching services.
`abstract String` | `getPreferredLanguage()` Reports the preferred language for this `SIManager`.
`abstract RatingDimension` | `getRatingDimension(String name)` Reports the `RatingDimension` corresponding to the specified string name.
`abstract Service` | `getService(Locator locator)` Provides the `Service` referred to by a given `Locator`.
`abstract String[]` | `getSupportedDimensions()` Provides the names of available rating dimensions in the local rating region.
`abstract Transport[]` | `getTransports()` Reports the various content delivery mechanisms currently available on this platform.
`abstract void` | `registerInterest(Locator locator, boolean active)` Provides a hint to the SI database that the application desires SI information as complete as possible about the specified `SIElement`.
`abstract SIRequest` | `retrieveProgramEvent(Locator locator, SIRequestor requestor)` Retrieves the `ProgramEvent` corresponding to the given `Locator`.
`abstract SIRequest` | `retrieveServiceDetails(Locator locator, SIRequestor requestor)` Retrieves the `ServiceDetails` object corresponding to the given `Locator`.
`abstract SIRequest` | `retrieveSIElement(Locator locator, SIRequestor requestor)` Retrieves the `SIElement` corresponding to the specified `Locator`.
`abstract void` | `setPreferredLanguage(String language)` Overrides the system-level preferred language for objects obtained through this `SIManager`.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### createInstance

    public static SIManager createInstance()

  Creates a new instance of `SIManager`.

  Returns:
    A new instance of `SIManager`.

### setPreferredLanguage

    public abstract void setPreferredLanguage(String language)

  Overrides the system-level preferred language for objects obtained through this `SIManager`. The specified language will be used by the textual information obtained from the `SIElement` objects obtained through this `SIManager`, if such information is available in the specified language. If the specified language is not available the system-level preferred language is used. If the system-level preferred language is not available either, the first available language will be used.

  The preferred language is indicated using a language code. This is typically a three-character language code as specified by ISO 639.2/B, but the code may be system-dependent.

  Parameters:
    `language` - A string representing the desired language code. If the input parameter is `null`, any language preference previously set using this method is canceled.

### getPreferredLanguage

    public abstract String getPreferredLanguage()

  Reports the preferred language for this `SIManager`. The resulting string is a language code indicating the language desired when retrieving multilingual text. This is typically a three-character code as specified by ISO 639.2/B.

  Returns:
    A string representing a language code defining the language used to retrieve multilingual strings. If no language preference is in effect, `null` is returned.

### registerInterest

    public abstract void registerInterest(Locator locator,
                                          boolean active)
                                   throws InvalidLocatorException,
                                          SecurityException

  Provides a hint to the SI database that the application desires SI information as complete as possible about the specified `SIElement`. As a result, the SI database might tune to the transport stream delivering the desired information and begin caching it, depending on resource availability.

  For example, if the given `Locator` references a bouquet, the database might begin caching `ServiceDetails` data for services that are part of the bouquet. If the given `Locator` references a service, the database might start caching `ProgramEvent` data for the service.

  Note that this method returns immediately and that there is no indication of the completion of any resulting SI database operations. Since it is only a hint for cache optimization, no specific behavior for this method is guaranteed.

  Parameters:
    `locator` - A locator referencing the `SIElement` for which complete information is desired.
    `active` - A flag indicating whether this interest is active or not. A value of `true` means that the application is interested in the `SIElement`; `false` means that the application wants to cancel a previously shown interest for the `SIElement`.
  Throws:
    `InvalidLocatorException` - If `locator` does not reference a valid `SIElement`.
    `SecurityException` - If the caller does not have `javax.tv.service.ReadPermission(locator)`.
  See Also:
    `ReadPermission`

### getSupportedDimensions

    public abstract String[] getSupportedDimensions()

  Provides the names of available rating dimensions in the local rating region. A zero-length array is returned if no rating dimensions are available.

  Returns:
    An array of strings representing the names of available rating dimensions in this rating region.
  See Also:
    `RatingDimension`

### getRatingDimension

    public abstract RatingDimension getRatingDimension(String name)
                                                throws SIException

  Reports the `RatingDimension` corresponding to the specified string name.

  Parameters:
    `name` - The name of the requested rating dimension.
  Returns:
    The requested `RatingDimension`.
  Throws:
    `SIException` - If `name` is not a supported rating dimension, as returned by `getSupportedDimensions()`.
  See Also:
    `getSupportedDimensions()`

### getTransports

    public abstract Transport[] getTransports()

  Reports the various content delivery mechanisms currently available on this platform. The implementation must be capable of supporting at least one `Transport` instance.

  Returns:
    An array of `Transport` objects representing the content delivery mechanisms currently available on this platform.

### retrieveSIElement

    public abstract SIRequest retrieveSIElement(Locator locator,
                                                SIRequestor requestor)
                                         throws InvalidLocatorException,
                                                SecurityException

  Retrieves the `SIElement` corresponding to the specified `Locator`. If the locator identifies more than one `SIElement`, all matching `SIElements` are retrieved.

  For example, multiple `SIElement` objects are retrieved when the locator represents identical content delivered over different media (terrestrial, satellite, cable, etc.) or a specific program event made available at different times, possibly on different services.

  This call retrieves various types of `SIElement` instances according to the locator specified. For example, if the locator is a transport-dependent locator to a service (and therefore to a `ServiceDetails` -- see `Service.getLocator()` for more information), a `ServiceDetails` object is retrieved; if the locator represents a program event, a `ProgramEvent` object is retrieved; if the locator represents a service component, a `ServiceComponent` is retrieved.

  This method delivers its results asynchronously.

  Parameters:
    `locator` - A locator referencing one or more SIElements.
    `requestor` - The `SIRequestor` to be notified when this retrieval operation completes.
  Returns:
    An `SIRequest` object identifying this asynchronous retrieval request.
  Throws:
    `InvalidLocatorException` - If `locator` does not reference a valid `SIElement`.
    `SecurityException` - if the caller does not have `javax.tv.service.ReadPermission(locator)`.
  See Also:
    `SIElement`

### getService

    public abstract Service getService(Locator locator)
                                throws InvalidLocatorException,
                                       SecurityException

  Provides the `Service` referred to by a given `Locator`. An implementation must be capable of supporting at least one `Service` instance.

  Parameters:
    `locator` - A locator specifying a service.
  Returns:
    The `Service` object corresponding to the specified locator.
  Throws:
    `InvalidLocatorException` - If `locator` does not reference a valid `Service`.
    `SecurityException` - If the caller does not have `javax.tv.service.ReadPermission(locator)`.
  See Also:
    `ReadPermission`

### retrieveServiceDetails

    public abstract SIRequest retrieveServiceDetails(Locator locator,
                                                     SIRequestor requestor)
                                              throws InvalidLocatorException,
                                                     SecurityException

  Retrieves the `ServiceDetails` object corresponding to the given `Locator`.

  Note that the locator may point to an SI element lower in the hierarchy than a service (such as a program event). In such a case, the `ServiceDetails` for the service that the program event is part of will be returned.

  If a transport-independent locator is provided, one or more `ServiceDetails` objects may be returned. However, it is permissible in this case for this method to always retrieve a single `ServiceDetails` object, as determined by the implementation, user preferences, or availability. To obtain all of the corresponding `ServiceDetails` objects, the application may transform the transport-independent locator into multiple transport-dependent locators and retrieve a `ServiceDetails` object for each.

  This method delivers its results asynchronously.

  Parameters:
    `locator` - A locator referencing a Service
    `requestor` - The `SIRequestor` to be notified when this retrieval operation completes.
  Returns:
    An `SIRequest` object identifying this asynchronous retrieval request.
  Throws:
    `InvalidLocatorException` - If `locator` does not reference a valid `Service`.
    `SecurityException` - If the caller does not have `javax.tv.service.ReadPermission(locator)`.
  See Also:
    `Locator`, `ServiceDetails`, `ReadPermission`

### retrieveProgramEvent

    public abstract SIRequest retrieveProgramEvent(Locator locator,
                                                   SIRequestor requestor)
                                            throws InvalidLocatorException,
                                                   SecurityException

  Retrieves the `ProgramEvent` corresponding to the given `Locator`. If a transport-independent locator is provided (e.g., one referencing the same movie shown at different times and/or on different services), this method may retrieve multiple `ProgramEvent` objects.

  This method delivers its results asynchronously.

  Parameters:
    `locator` - A locator referencing a ProgramEvent
    `requestor` - The `SIRequestor` to be notified when this retrieval operation completes.
  Returns:
    An `SIRequest` object identifying this asynchronous retrieval request.
  Throws:
    `InvalidLocatorException` - If `locator` does not reference a valid `ProgramEvent`.
    `SecurityException` - If the caller does not have `javax.tv.service.ReadPermission(locator)`.
  See Also:
    `ProgramEvent`, `ReadPermission`

### filterServices

    public abstract ServiceList filterServices(ServiceFilter filter)

  Filters the available services using the `ServiceFilter` provided to generate a `ServiceList` containing the matching services. If the filter parameter is `null`, a list of all known services is generated. Only `Service` instances for which the caller has `javax.tv.service.ReadPermission` on the underlying locator will be present in the returned list.

  Note that for each `Service` to be filtered, the `accept()` method of the given `ServiceFilter` will be invoked with the same application thread that invokes this method.

  Parameters:
    `filter` - A `ServiceFilter` by which to generate the requested service list, or `null`.
  Returns:
    A `ServiceList` generated according to the specified filtering rules.
  See Also:
    `ServiceFilter.accept(javax.tv.service.Service)`

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

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