javax.tv.service

Class SIManager

java.lang.Object

javax.tv.service.SIManager

Direct Known Subclasses:

SIManagerImpl

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	SIManager() Constructs an SIManager object.

Method Summary

Methods

Modifier and Type	Method and Description
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 identified 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

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SIManager

protected SIManager()

Constructs an SIManager object.

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 identified by a given locator. An implementation must be capable of supporting at least one Service instance.

Parameters:

locator - A locator identifying a service.

Returns:

The Service object corresponding to the specified locator.

Throws:

InvalidLocatorException - If locator does not contain sufficient information to identify a 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. On some implementations of JavaTV, attempts to retrieve a ProgramEvent will always fail with an SIRequestFailureType(INSUFFICIENT_RESOURCES).

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)