Service Descriptor ReferenceJavaTM TV API Optional PackageReference ImplementationVersion 1.1.1Connected Device ConfigurationDecember 2008 |
The Java TV API reference implementation (JavaTV API RI) includes the APIs to retrieve service information (SI) elements by accessing a SI database. In a product implementation, the SI database is broadcast to a set-top box. The Java TV API RI emulates the population of the SI database by reading the service descriptor file (SDF), which is an XML document that describes the SI elements and their relationships in the SI database. The JavaTV API RI also captures any changes to the SDF. If a user modifies the SDF after the JavaTV API RI has started, the JavaTV API RI detects the change and modifies its representation of the SI database accordingly, as if the change to the SI database was broadcast to a set-top box.
To customize the JavaTV API RI, you must understand the XML format of the SDF. The default SDF file that the JavaTV API RI reads is at lib/JavaTVSampleFile01.xml. The default is specified in the lib/JavaTV.properties file's ServiceFile property.
This document provides guidelines for configuring the SI settings in the XML document. Also included are tips on the elements or attributes used in the JavaTV API RI and their expected values.
The SI XML document defines a top-level element, TestData, which contains an optional header and one or more DataBundle elements. Each DataBundle is a complete set of SI data for the RI.
Elements that can be defined once in DataBundle:
Elements that can be defined multiple times in DataBundle:
Element | Definition |
---|---|
|
|
Bouquet | data for javax.tv.service.transport.Bouquet |
ContentRatingAdvisory | data for javax.tv.service.guide.ContentRatingAdvisory |
FavoriteService | sets javax.tv.service.navigation.FavoriteServicesName |
IPDatagram | data for javax.tv.net |
Network | data for javax.tv.service.transport.Network |
ProgramEvent | data for javax.tv.service.guide.ProgramEvent |
ProgramSchedule | data for javax.tv.service.guide.ProgramSchedule |
Rating | ratings for rating dimension |
RatingDimension | data for javax.tv.service.navigation.RatingDimension |
RemoveBouquet | an element to remove Bouquet object from SI database |
RemoveList | list of SIElements to remove from the SI database if the SIElement is already in the database |
RemoveNetwork | element to remove Network object from SI database |
RemoveProgramEvent | element to remove ProgramEvent object from SI database |
RemoveService | element to remove Service object from the service cache |
RemoveServiceComponent | element to remove ServiceComponent object from SI database |
RemoveServiceDetails | element to remove ServiceDetails object from SI database |
RemoveSIDatabase | resets the SI database by removing every SIElement in it |
RemoveTransportStream | element to remove TransportStreams object from SI database |
Service | data for javax.tv.service.Service |
ServiceComponent | data for javax.tv.service.navigation.ServiceComponent |
ServiceComponentData | defines ProgramEvent-tied or Service-tied data to be used by Xlet |
ServiceDetails | data for javax.tv.service.navigation.ServiceDetails |
ServiceTransforms | defines the transformation rules between transport independent and dependent services |
TransportStream | data for javax.tv.service.transport.TransportStream |
Xlet | data related to javax.tv.xlet.Xlet |
Element | Definition |
---|---|
|
|
TestData | Top-level element for the RI's SI database. Contains a DataBundle element and an optional Heading element. |
Heading | Provides textual information about the XML document. It is not processed by the RI. |
DataBundle |
Collection of various elements for SIElements and other data for the RI. It can contain one instance of the elements BundleDescription and PreferredLanguage. DataBundle can define multiple instances of the elements Bouquet, FavoriteService, IPDatagram, Network, RatingDimension, RemoveList, RemoveSIDatabase, ServiceTransforms, Service, TransportStream, and Xlet.
The attribute defined for DataBundle is as Name, a unique element identifier for DataBundle. |
BundleDescription | Provides a textual description for the DataBundle element. |
PreferredLanguage | Defines the preferred language for SIManager.
The attribute defined for PreferredLanguage is as follows:
|
Bouquet |
Defines the data for the Bouquet class. Attributes defined for Bouquet are as follows:
|
ContentRatingAdvisory | Defines the data for a ContentRatingAdvisory that is associated with the ProgramEvent.
Attributes defined for ContentRatingAdvisory are as follows:
|
FavoriteService | Defines the data for FavoriteServicesName. A PreferenceFilter created with this FavoriteServicesName accepts the services associated with it.
Attributes defined for FavoriteService are as follows:
|
IPDatagram | Defines the data that carries an IP datagram. It is accessed through the javax.tv.net package. This element is currently unused in the RI. |
Network | Defines the data for the Network class.
Attributes defined for Network are as follows:
|
ProgramEvent | Defines the data for a ProgramEvent. It can contain one or more of the elements ContentRatingAdvisory, ServiceComponent, and ServiceComponentData. Attributes defined for ProgramEvent are as follows:
|
ProgramSchedule | Dlement defines data for ProgramSchedule associated with a ServiceDetails element. ProgramSchedule can contain one or more ProgramEvent elements. ProgramSchedule has no attributes associated with it. |
Rating | Defines a data component for RatingDimension, which can be accessed from RatingDimension.getRatingLevelDescription().
Attributes defined for Rating are as follows:
|
RatingDimension | Defines the data for the RatingDimension class. RatingDimension can contain one or more Rating elements.
The attribute defined for RatingDimension is DimensionName (String), an example of RatingDimension is used by the MPAA (Motion Picture Association of America). |
RemoveBouquet | Requests the removal of a Bouquet from the SI database.
The attribute defined for RemoveBouquet is ID (integer), the identification number of the Bouquet to be removed. |
RemoveList | Specifies an SIElement to remove from the database. RemoveList can contain many elements, including RemoveService, RemoveProgramEvent, RemoveBouquet, RemoveCarousel, RemoveNetwork, RemoveTransportStream, RemoveServiceDetails, and RemoveServiceComponent. |
RemoveNetwork | Requests the removal of a Network from the SI database.
The attribute defined for RemoveNetwork is ID (integer), the identification number of the Network to be removed. |
RemoveProgramEvent | Requests the removal of a ProgramEvent from the SI database.
Attributes defined for RemoveProgramEvent are as follows:
|
RemoveService | Requests the removal of a Service from the SI database.
Attributes defined for RemoveService are as follows:
|
RemoveServiceComponent | Requests the removal of a ServiceComponent from the SI database. The attribute defined for RemoveServiceComponent is Name (String), the name of the ServiceComponent to be removed. |
RemoveServiceDetails | Requests the removal of a ServiceDetails from the SI database. The attribute defined for RemoveServiceDetails is Name (String), the name of the ServiceDetails to be removed. |
RemoveSIDatabase | Requests the removal of every SIElement in the SI database. If this element is present in XML, the database is flashed at the time the element is read into the RI. This element does not have any attributes. |
RemoveTransportStream | Requests the removal of a TransportStream from the SI database. The attribute defined for RemoveTransportStream is ID (integer), the identification number of the TransportStream to be removed. |
Service | Defines data for the Service class. Service can contain one ServiceDetails element. Note that if the service is defined as transport independent in the ServiceTransforms element, the service's transport dependent information, such as ServiceDetails and ProgramEvents, are discarded from the database. Attributes defined for Service are as follows:
|
ServiceComponent | Defines data for ServiceComponent associated with a ServiceDetails or a ProgramEvent.
Attributes defined for ServiceComponent are as follows:
|
ServiceComponentData | Defines the data associated with a ServiceComponent, in particular an xlet. If Xlet is specified in this attribute, XletManager launches this Xlet when this service is selected. Attributes defined for ServiceComponentData are as follows:
|
ServiceDetails | Defines data for the ServiceDetails class. ServiceDetails can contain multiple ServiceComponent elements, ProgramSchedule elements, and ServiceComponentData elements.
Attributes defined for ServiceDetails are as follows:
|
ServiceTransforms | Defines a relationship between transport independent service and dependent services. Services that appear in this element are also be defined in the Service attribute with the same name. Attributes defined for ServiceTransforms are as follows:
|
TransportStream | Defines the data for the TransportStream class.
Attributes defined for TransportStream are as follows:
|
Xlet | Defines the data for Xlet. This Xlet would not be tied to a Service and is launched at the time the SI database is being populated. Attributes defined for Xlet are as follows:
|
Two types of Xlet can be executed from XML, a resident Xlet and a service-tied Xlet. A resident Xlet launches when the application boots and does not terminate unless the application, or another program, requests XletManager to do so. A service-tied Xlet runs only when its associated service is selected and being presented.
A resident Xlet can be specified with the Xlet element. Place the fully qualified class name of the Xlet in the NAME attribute, and use the PATH attribute to specify an additional classpath to load the class from.
For the service-tied Xlet, use the ServiceComponentData element. It can be tied to ProgramEvent or ServiceDetails. In this case, the Xlet launches upon selection of the particular Service to which Xlet is tied.
After the reference implementation boots, the XML file is periodically checked for changes. When an XML change is detected, the RI adjusts the content of the SI database accordingly and appropriate SIChangeEvents are delivered to registered listeners.
Note that the removal of elements from the SI database needs to be done through the Remove* tag in XML. Physically removing the entry from the XML does not generate the event.
A service in the Java TV API can be transport independent or transport dependent.
The mapping between transport independent and dependent services can be specified in the ServiceTransforms tag. It is important that all services in a ServiceTransforms element have a corresponding Service specification with the Service tag. The RI treats all services as transport dependent unless defined in the ServiceTransforms NAME attribute.
Copyright © 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.