javax.tv.service.package.html Maven / Gradle / Ivy
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
{@link javax.tv.service.SIRequestFailureType#DATA_UNAVAILABLE
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.