Service Descriptor Reference

JavaTM TV API Optional Package

Reference Implementation

Version 1.1.1

Connected Device Configuration

December 2008
 

Table of Contents

Introduction
Overview
Element and Attribute Requirements
How to Launch an Xlet from XML
How to Introduce Changes to the SI Database after Bootup
Service and Locator Transformation
Known Issues

Introduction

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.

Overview

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 and Attribute Requirements

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:

  • Value (String), this is typically a three-character language code as specified by ISO 639.2/B, but could be system dependent.
Bouquet

Defines the data for the Bouquet class.

Attributes defined for Bouquet are as follows:

  • Bouquet ID (integer)
  • Bouquet name (String)
  • ServiceInformationType (String), this is the String constant defined in javax.tv.service.ServiceInformationType.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
ContentRatingAdvisory Defines the data for a ContentRatingAdvisory that is associated with the ProgramEvent.

Attributes defined for ContentRatingAdvisory are as follows:

  • DimensionName (String), a string defined in RatingDimension element's name attribute.
  • RatingName (String), a string defined in Rating element's name attribute.
  • RatingValue (String), this attribute is currently unused.
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:

  • Name (String), a name for this FavoriteService group, such as "Lucy's favorites".
  • ServiceNames (String), an array of Service names separated by commas. It defines the list of Services this FavoriteService group contains.
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:

  • Network ID (integer)
  • Network name (String)
  • ServiceInformationType (String), this is the String constant defined in javax.tv.service.ServiceInformationType.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
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:

  • Name (String)
  • Duration (integer), the duration of this ProgramEvent in minutes.
  • StartTime, the starting time of this ProgramEvent. A string systime sets the startTime of this ProgramEvent as the system time when the RI starts up and the SI database is populated; "+" indicates the systime plus the specified minutes, and "-" indicates the systime minus the specified minutes. For example, if an XML document sets the StartTime at +60 and the reference implementation boots up at August 17, 2006 2pm, this ProgramEvent would have a startTime of August 17, 2006 3pm. Duration and StartTime are added to set the EndTime of this ProgramEvent.
  • Description (String), a textual description of this ProgramEvent.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
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:

  • Name (String)
  • Description (String) corresponding to the Name. An example of MPAA rating is ["PG-13", "Parental Guidance under 13"].
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:

  • Service_Name (String), the name of the Service to which the target ProgramEvent belongs.
  • Program_Name (String), the name of the ProgramEvent to be removed.
RemoveService Requests the removal of a Service from the SI database.

Attributes defined for RemoveService are as follows:

  • Name (String), the name of the Service to be removed.
  • Reason (String), the reason of this Service removal.
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:

  • Name(String), must be unique.
  • ServiceType (String), a String defined in javax.tv.service.ServiceType.
  • SIType (String), a String defined in javax.tv.service.ServiceInformationType.
  • Service Description (String)
  • Service Number (integer)
  • Service Minor Number (integer)
  • Simulation (path), the location of an MPEG stream associated with this service.
  • Alternate (path), the location of an MPEG stream to be played when normal selection on this service fails and alternative selection is needed.
  • CALimit, or Conditional Access Limit (String), to restrict the access to this element. The string matches one of the fields in javax.tv.service.selection.SelectionFailedEvent. When this attribute is provided, an attempt to select this service fails and the SelectionFailedEvent with this reason is generated.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
ServiceComponentDefines data for ServiceComponent associated with a ServiceDetails or a ProgramEvent.

Attributes defined for ServiceComponent are as follows:

  • Name (String), the name of this ServiceComponent.
  • Language (String), this is typically a three-character language code as specified by ISO 639.2/B, but could be system dependent.
  • Stream-type (String), a string constant defined in the class javax.tv.service.navigation.StreamType.
  • Simulation (URL), an optional attribute to set the location of an MPEG file associated with this ServiceComponent element. To make this ServiceComponent carry an IP datagram to be retrieved by the javax.tv.net Package, tie the location of the IP datagram simulation file to this attribute.
  • Alternate (URL), an optional attribute to set the location of the alternate MPEG file associated with this ServiceComponent element.
  • AutoRun (boolean)
  • CALimit, or Conditional Access Limit (String), to restrict the access to this element. The string that matches one of the fields in javax.tv.service.selection.SelectionFailedEvent. When this attribute is provided, an attempt to select this service component fails and the SelectionFailedEvent with this reason is generated.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
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:

  • Name (String), the class name of an xlet.
  • Language (String), this is typically a three-character language code as specified by ISO 639.2/B, but could be system dependent.
  • Path (URL1,URL2,...), an optional attribute to specify the location of the Xlet other than at a class path.
  • args (String), an optional attribute for passing in an argument to the Xlet. Strings separated by commas. These strings are returned via XletContext.getXletProperty(XletContext.ARGS).
  • AutoRun (boolean)
  • CALimit, or Conditional Access Limit (String), to restrict the access to this element. The string matches one of the fields in javax.tv.service.selection.SelectionFailedEvent. When this attribute is provided, an attempt to select this service component fails and the SelectionFailedEvent with this reason is generated.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
  • isServiceUnbound (boolean), to identify whether this xlet is service bound or unbound. If an xlet is running in the current service and the newly selected service also signals a ServiceComponentData with the same classname, then a service bound xlet will be destroyed and restarted, while a service unbound xlet will continue running during the selection.
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:

  • LongName (String), a unique name of this ServiceDetails.
  • ProviderName (String), for ServiceProviderInformation.
  • DeliverySystemType (String), is a string constant defined in the class javax.tv.service.DeliverySystemType.
  • Description (String), data for ServiceDescription.
  • CASystemIDs (array of integer), data for CASystemID, or Conditional Access System Identification.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
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:

  • Name (String), a name of the transport independent service.
  • List(String), a list of service names separated by commas. These services are transport dependent services associated with the transport independent service specified with the "Name" attribute above.
TransportStream Defines the data for the TransportStream class.

Attributes defined for TransportStream are as follows:

  • TransportStream ID (integer)
  • TransportStream name (String)
  • ServiceInformationType (String), this is the String constant defined in javax.tv.service.ServiceInformationType.
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.
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:

  • Name (String), the class name of the Xlet.
  • Path (URL1,URL2,...), the location of the Xlet.
  • Args (String), an argument to the Xlet, separated by commas. The values are returned as an array of Strings for this Xlet's XletContext.getXletProperty(XletContext.ARGS).
  • transmittime (integer), the delay, in seconds, at which this element is added to the SI database.

How to Launch an Xlet from XML

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.

How to Introduce Changes to the SI Database

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.

Service and Locator Transformation

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.

Known Issues

Copyright © 2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.