com.sun.tv.si

Class SIManagerImpl

java.lang.Object

javax.tv.service.SIManager

com.sun.tv.si.SIManagerImpl

All Implemented Interfaces:

ReceiverListener, Runnable, EventListener

public class SIManagerImpl
extends SIManager
implements ReceiverListener, Runnable

SI Manager represents the central managing entity which has a knowledge of the entire network or a collection of networks and can create a collection of Services based on the ServiceGroup filtering rules. It can also be used to retrieve any SIElement.

The SIManager may be used to set some global parameters such as preferred language for text information which may be delivered as multilingual strings to the receiver.

Constructor Summary

Constructors

Constructor and Description
SIManagerImpl()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	cancel(SIRequest toCancel) This implements the cancel of an async.
ServiceList	filterServices(ServiceFilter filter) Creates a ServiceList object based on the conditions specified in a filter parameter.
Vector	findSIElements(SIRequestImpl request) Find a match in the SI cache for the provided request; a variety of requests are served by this method.
static FavoriteServicesName[]	getFavoriteServices(String localName)
static FavoriteServicesName[]	getFavoriteServicesNames()
String	getPreferredLanguage() Called to determine the preferred language for returning string-type values.
RatingDimension	getRatingDimension(String name) Returns the Rating Dimension corresponding to the specified Dimension name.
Service	getService(Locator locator) This method can be used to obtain a specific Service based on a Locator.
String[]	getSupportedDimensions() Provides a list of names of available rating dimensions for the local rating region.
Transport[]	getTransports() Reports the various content delivery mechanisms available on this platform.
boolean	hasPermission(Locator locator)
void	makeRequest(SIRequestImpl request) This method handles asynchronous SIElement requests, if the request can be full-filled by the existing cached data then the results are immediatley returned.
void	notifyChange(SIChangeEvent event) This interface method handles SI events generated by the receiver, implementors are required to have their receivers generate the SI event passing the event to this method.
static void	putFavoriteServices(String localName, String[] shortNames)
void	registerInterest(Locator locator, boolean active) This method provides a hint to the SI Database that the application would like to have as complete SI information as possible about the specified SI element.
SIRequest	retrieveProgramEvent(Locator locator, SIRequestor requestor) This method can be used to retrieve a specific ProgramEvent based on a Locator.
SIRequest	retrieveServiceDetails(Locator locator, SIRequestor requestor) This method can be used to retrieve specific ServiceDetails (meta-data for a Service) based on a Locator.
SIRequest	retrieveSIElement(Locator locator, SIRequestor requestor) This method retrieves an SIElement corresponding to the specified Locator.
void	run() This async.
void	setPreferredLanguage(String language) Sets the language used to return any textual information from the SI related classes and interfaces (e.g.
boolean	SIElementExists(SIElement element)

Methods inherited from class javax.tv.service.SIManager

createInstance

Methods inherited from class java.lang.Object

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

Constructor Detail

SIManagerImpl

public SIManagerImpl()

Method Detail

putFavoriteServices

public static void putFavoriteServices(String localName,
                       String[] shortNames)

getFavoriteServices

public static FavoriteServicesName[] getFavoriteServices(String localName)

getFavoriteServicesNames

public static FavoriteServicesName[] getFavoriteServicesNames()

setPreferredLanguage

public void setPreferredLanguage(String language)

Sets the language used to return any textual information from the SI related classes and interfaces (e.g. Service name, etc.) if provided as a multilingual string in multiple languages. If the specified language is not available, the system-level preferred language is used. If that language is not available either, the first available language will be used.

This method is used to temporarily override the system-level preferred language within the abstractSI package.

Specified by:

setPreferredLanguage in class SIManager

Parameters:

language - A string representing a language code defining the language associated with this component. It contains a three-character code as specified by ISO 639.2/B. If the input parameter is null, the application set preference is cancelled.

getPreferredLanguage

public String getPreferredLanguage()

Called to determine the preferred language for returning string-type values.

Specified by:

getPreferredLanguage in class SIManager

Returns:

A string representing a language code defining the language used to retrieve multilingual strings. It contains a three-character code as specified by ISO 639.2/B. Null is returned when there is no language preference defined.

registerInterest

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

This method provides a hint to the SI Database that the application would like to have as complete SI information as possible about the specified SI element. The SI Database may tune to the transport stream delivering the information and start caching it (depending on resource availability). Note that this method returns immediately and that there is no event signaling any kind of completion. Also note that this is just a hint for cache optimization on the receiver and no prescribed behavior is guaranteed.

For example, if the locator points to a bouquet, the database may start caching ServiceDetails information for services which are part of the specified bouquet. If the locator points to a Service, the database may start caching ProgramEvents for this service.

Specified by:

registerInterest in class SIManager

Parameters:

locator - A locator referencing the SI element of interest.

active - A flag indicating whether this interest is active or not. True means that the application is interested in the data; false means that the application wants to cancel a previously shown interest for the same locator.

Throws:

InvalidLocatorException - If locator does not reference a valid SIElement for expressing interest.

SecurityException - if the caller does not have javax.tv.service.ReadPermission(locator)

See Also:

ReadPermission

getSupportedDimensions

public String[] getSupportedDimensions()

Provides a list of names of available rating dimensions for the local rating region.

Specified by:

getSupportedDimensions in class SIManager

Returns:

An array of Strings representing names of available rating dimensions for this rating region.

See Also:

RatingDimension

getRatingDimension

public RatingDimension getRatingDimension(String name)
                                   throws SIException

Returns the Rating Dimension corresponding to the specified Dimension name.

Specified by:

getRatingDimension in class SIManager

Parameters:

name - 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:

SIManager.getSupportedDimensions()

getTransports

public Transport[] getTransports()

Reports the various content delivery mechanisms available on this platform.

Specified by:

getTransports in class SIManager

Returns:

An array of Transport objects representing the content delivery mechanisms on this platform.

retrieveSIElement

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

This method retrieves an SIElement corresponding to the specified Locator. If the locator identified more than one SIElement, all matching SIElements are returned in the form of an array.

For example, multiple SIElements may be returned 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 may return different types of SIElements based on the specified locator. E.g. if the locator is transport independent locator, a corresponding Service is returned; if the locator is transport dependent, ServiceDetails object is returned; if the locator represents a program event; ProgramEvent object is returned; etc.

This method delivers its results asynchronously.

Specified by:

retrieveSIElement in class SIManager

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, ProgramEvent

getService

public Service getService(Locator locator)
                   throws InvalidLocatorException,
                          SecurityException

This method can be used to obtain a specific Service based on a Locator.

Note that the locator may point to an SIElement lower in the hierarchy (such as a ProgramEvent). In such a case the Service which the ProgramEvent is part of will be returned.

Specified by:

getService in class SIManager

Parameters:

locator - A locator specifying a Service

Returns:

A 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 SIRequest retrieveServiceDetails(Locator locator,
                               SIRequestor requestor)
                                 throws InvalidLocatorException,
                                        SecurityException

This method can be used to retrieve specific ServiceDetails (meta-data for a Service) based on a Locator. Note that the locator may point to an SIElement lower in the hierarchy (such as a ProgramEvent). In such a case the ServiceDetails which the ProgramEvent is part of will be returned.

Also since a transport-independent locator may represent multiple transport-dependent services, an array of ServiceDetails may be returned.

If multiple ServiceDetails objects are available for the given locator (e.i. the locator is transport independent), this call may return only one of them (choice made by implementation based on e.g. user preferences and availability).

This is because it will probably take a long time to retrieve all of them while one could be returned very quickly. It may not even be possible to always get all of them (e.g. tuning would be required).

If the application really wants to get all of them, it can always transform the trnsport-independent locator into multiple transport-dependent locators and retrieve the ServiceDetails for each one of them.

This method delivers its results asynchronously.

Specified by:

retrieveServiceDetails in class SIManager

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 SIRequest retrieveProgramEvent(Locator locator,
                             SIRequestor requestor)
                               throws InvalidLocatorException,
                                      SecurityException

This method can be used to retrieve a specific ProgramEvent based on a Locator. Note that since a transport-independent locator may represent multiple instances of a ProgramEvent (e.g. the same movie shown at different times and/or on different services), this method may return multiple ProgramEvents.

This method delivers its results asynchronously.

Specified by:

retrieveProgramEvent in class SIManager

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 ServiceList filterServices(ServiceFilter filter)

Creates a ServiceList object based on the conditions specified in a filter parameter. If the filter 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 the accept method of the given ServiceFilter will be invoked for each Service to be filtered using the same application thread that invokes filterServices.

Specified by:

filterServices in class SIManager

Parameters:

filter - A ServiceFilter by which to generate the requested service list, or null.

Returns:

A ServiceList object created based on the specified filtering rules.

See Also:

ServiceFilter.accept(javax.tv.service.Service)

makeRequest

public void makeRequest(SIRequestImpl request)

This method handles asynchronous SIElement requests, if the request can be full-filled by the existing cached data then the results are immediatley returned. Otherwise, the request is stored, and will be full-filled either when a new SIElement enters the system, or when the request expires.

hasPermission

public boolean hasPermission(Locator locator)

findSIElements

public Vector findSIElements(SIRequestImpl request)

Find a match in the SI cache for the provided request; a variety of requests are served by this method. The request will be uniquely handled by the requestKind. Most requets can be handled by searching the SI Element cache.

Parameters:

request - the request for match is being found.

cancel

public boolean cancel(SIRequest toCancel)

This implements the cancel of an async. request made within JavaTV. The request to cancel is remove from the queue of requests, and the requestor is notified of the request failure. Requests are generally cancelled, because they have been timed out.

SIElementExists

public boolean SIElementExists(SIElement element)

notifyChange

public void notifyChange(SIChangeEvent event)

This interface method handles SI events generated by the receiver, implementors are required to have their receivers generate the SI event passing the event to this method. This Reference Implementation uses the SIEmulator class to feed it the SIChangeEvent's.

Specified by:

notifyChange in interface ReceiverListener

run

public void run()

This async. method will process the cached SI requests checking for expired requests. Requests can currently expire by elapsed time, although, the could also expire by cache size limit. The requestor is notified of an expired request via the notifyFailure method. Note: It's important that the requests vector is processed in descending order, so that if the a request is removed from the cache, then the for loop interator i will continue to work properly.

Specified by:

run in interface Runnable