Package javax.tv.service

Provides mechanisms for accessing the service information (SI) database and APIs representing the SI elements it contains.

See: Description

Interface Summary

Interface	Description
RatingDimension	The RatingDimension interface represents an individual content rating scheme against which program events are rated.
Service	The Service interface represents an abstract view on what is generally referred to as a television "service" or "channel".
ServiceMinorNumber	This interface extends the basic ServiceNumber interface to provide the minor number of two-part service numbers described in major.minor format.
ServiceNumber	This interface is used to identify services by service (or channel) numbers.
SIChangeListener	This is the super-interface of the interfaces by which applications may receive notification of changes to SIElement data.
SIElement	The base interface of elements provided by the SI database.
SIRequest	An SIRequest object is used to cancel a pending asynchronous SI retrieval operation.
SIRequestor	This interface is implemented by application classes to receive the results of asynchronous SI retrieval requests.
SIRetrievable	This interface is implemented by objects that are retrieved from SI data in the broadcast.

Class Summary

Class	Description
ReadPermission	This class represents permission to read the data referenced by a given Locator.
ServiceInformationType	This class represents types of service information (SI) formats.
ServiceType	This class represents service type values such as "digital television", "digital radio", "NVOD reference service", "NVOD time-shifted service", "analog television", "analog radio", "data broadcast" and "application".
SIChangeEvent	SIChangeEvent objects are sent to SIChangeListener instances to signal detected changes in the SI database.
SIChangeType	This class represents types of changes to SI elements.
SIManager	An SIManager represents a managing entity which has knowledge of all the broadcast resources available to a receiver.
SIRequestFailureType	This class represents reason codes for failure of asynchronous SI retrieval requests.

Exception Summary

Exception	Description
SIException	The base class for exceptions related to service information.

Package javax.tv.service Description

Provides mechanisms for accessing the service information (SI) database and APIs representing the SI elements it contains. The javax.tv.service package and its sub-packages are organized into different "views" of service information, as follows:

• The guide package provides APIs useful for electronic program guides (EPGs), including program schedules, program events and program ratings.
• The navigation package provides APIs to navigate through services and hierarchical service information.
• The selection package provides a mechanism to select a service, that is, tune to a service and present its content.
• The transport package provides information concerning the broadcast delivery mechanisms available to the receiver.
• The top-level service package (this package) provides basic SI APIs common to the service sub-packages.

The Java TV APIs for accessing service information are intended to be used in multiple environments where various standards for service information delivery already exist. Therefore, these APIs provide a high level of abstraction from the details of over-wire protocols. Some attributes of SI elements are unique to specific SI standards or are difficult to map to a common API. In order to provide access to such attributes, the service packages define optionally implemented interfaces.

The SIManager provides the primary access point to the underlying SI database. It may be used to acquire the meta-data of an individual service and its associated SI elements. The Service interface provides the minimal information (such as a Locator, name and optionally a ServiceNumber) required to identify and select the content of a service. Such information is typically cached and readily available on a television receiver at all times. Additional information about a service can be obtained through the ServiceDetails object.

The Service interface represents DVB services, ATSC virtual channels (both PSIP and A56) or SCTE virtual channels. It provides the minimal information (such as a Locator, name, and optionally a ServiceNumber) required to identify and select the content of a service. Such information is typically cached and readily available on a television receiver at all times. Additional information about a service can be obtained through the ServiceDetails object. In contrast to the Service interface, ServiceDetails represents service meta-data that exists in the broadcast.

Cache Limitations and Asynchronous SI Retrieval

Since TV receivers are designed with varying capabilities, it is not expected that very receiver will cache all the SI data in memory. The most basic information for accessing services is likely to be cached; however, the receiver must parse the broadcast stream to acquire data that is not cached. Doing so may take a significant amount of time. Therefore the SI APIs provide means for asynchronous access to data that is likely to not be in memory at all times. All APIs prefixed with 'retrieve' return the requested data via an asynchronous callback. This functionality is provided by the SIRequestor, SIRequest and SIRetrievable interfaces. A caller of an asynchronous method registers as an SIRequestor in order to receive SIRetrievable data when it is available. The asynchronous method provides an SIRequest object to cancel the request if it is no longer needed by the caller.

Note that asynchronous SI data retrieval is only a request for information. The latencies involved in reading SI data from the broadcast stream may make retrieval of a requested SI element impractical. Failed SI retrieval is signaled through a call to SIRequestor.notifyFailure(SIRequestFailureType).

Scalability

The Java TV API defines several interfaces in the javax.tv.service.* packages to represent various forms of service information, or "SI elements", that may be encountered. Not every type of SI element may be supported in a given broadcast environment, however. In such a case, asynchronous 'retrieve' operations for unsupported SI elements will result in the failure code DATA_UNAVAILABLE. Likewise, synchronous query operations will fail in a manner indicating that the requested data is unavailable.

Time Synchronization

The service information usually contains system time-related information in the form of the PSIP STT message or DVB TDT and TOT messages. It is assumed that the local TV receiver time will be synchronized with the system time of the service currently tuned and that this value can be obtained using the java.util.Date class. This is straightforward if all transport multiplexes use a reliable and synchronized data source (such as GPS). If a certain multiplex provides erroneous time information, it is up to the receiver implementation to resolve the conflict.

SI Change Notification

The SI APIs permit applications to be notified of changes to elements in the SI database. There are multiple sources of SI change notification:

• Transport objects report changes concerning services.
• TransportStreamCollection objects report changes concerning TransportStream information on a Transport.
• NetworkCollection objects report changes concerning Network information on a Transport.
• BouquetCollection objects report changes concerning Bouquet information on a Transport.
• ServiceDetails objects report chanes conerning ServiceComponent information for individual services.
• ProgramSchedule objects report changes detected in the program events in the schedule, including the current ProgramEvent.

An application can register as an SIChangeListener with the above listed objects to be notified with an SIChangeEvent subtype when a change occurs. The resulting SIChangeEvent will indicate the SIElement that changed in the database. Note that it may be quite difficult for the receiver to provide detailed information concerning the data that changed without a field-by-field comparison of old and new SI tables from the broadcast. The receiver may therefore choose to deliver an SIChangeEvent indicating a change at a high level in the SI hierarchy and require the application to determine the specific nature of the change.