Runtime Notes

JavaTM TV API Optional Package

Reference Implementation

Version 1.1.1

Connected Device Configuration

December 2008


Table of Contents

Software Contents
Installing the Java TV API RI
Compiling the Sample Applications
Running the Sample Applications


The Java TV API optional package provides access to digital television services such as conditional access and tuner control. These runtime notes describe runtime features specific to the Java TV API optional package. This includes how to compile, setup and run a sample application. Since this reference implementation (RI) version of the Java TV API optional package supports both 1.0.x and 1.1.x versions of CDC, these runtime notes apply to both systems.

The Java TV API RI allows application developers to build applications that access digital television features and content while remaining independent of the underlying broadcast technology on which they will be deployed. The Java TV API RI demonstrates these capabilities by providing a simulated environment for running digital television applications.


To understand how the Java TV API RI works, it is necessary to review a few definitions:


The Java TV API optional package has programming features that allow applications to perform television-specific operations:

Application Examples

Sample applications that use these programming features include:

Software Contents

The JavaTV API RI contains the following software components.

File or Directory Description

j2me_xml_ri.jar The JAXP optional package subset of Java Web Services (JSR 172).
javatv.jar Java TV API (JSR 927) optional package. JNI implementation for the audio codec.
lib/ The default Java TV API property file and two service descriptor files. See Service Descriptor Files for a description of the files in this directory and the companion document Service Descriptor Reference for more information about their formats.
samples/ Contains sample applications. See Sample Applications for a description of the files in this directory.
video/ Contains, a sample QuickTime movie.

Service Descriptor Files

The Java TV API RI requires the following files in lib:

File Comment System properties file that defines the Java TV configuration, such as ServiceFileHandler class to populate the SI database, ServiceFile file reference to the XML file for ServiceFileHandler, locator list class implementation and so on.
JavaTVServiceFile.dtd Service information DTD.
JavaTVServiceFile.xml Sample description of the SI database.
JavaTVSampleFile0{1,2,3}.xml Sample XML population file of the SI database, referenced in the lib/ file.

Sample Applications

The samples directory contains four subdirectories for sample applications that demonstrate different portions of the Java TV API optional package functionality. These sample applications are described in the following table:

Directory Comment

db/ Populates the emulator and then retrieves values to be sure that the expected results are obtained.
locator/ Exercises the locator functionality in a variety of positive and negative tests.
media/ Attempts to create a service object based on a known valid location.
runxlet/ Populates the SI database and then invokes an xlet that is named on the command line.

Installing the Java TV API RI

This section describes how to install the Java TV API RI into the CDC Java runtime environment.

The following procedures shows how to deploy the runtime files for the Java TV API optional package into the CDC Java runtime environment.

  1. Unzip the Java TV API RI distribution bundle.
    % unzip
  2. Copy the .jar files for Java TV API optional package and the subset of the Java Web Services optional package into the lib directory in the CDC Java runtime environment.
    % cp ${JAVATV_HOME}/j2me_xml_ri.jar ${BASIS_HOME}/lib
    % cp ${JAVATV_HOME}/javatv.jar ${BASIS_HOME}/lib
  3. Copy the .so file for Java TV API native method implementation into the ${BASIS_HOME}/lib directory in the CDC Java runtime environment.
    % cp ${JAVATV_HOME}/ ${BASIS_HOME}/lib
  4. Copy the contents of the ${JAVATV_HOME}/lib into the lib directory in the CDC Java runtime environment.
    % cp ${JAVATV_HOME}/lib/* ${BASIS_HOME}/lib

Compiling the Sample Applications

The sample applications must be compiled with the following .jar files:

For example, the following script will compile the sample application in samples/db:



${J2SE_HOME}/bin/javac -bootclasspath \
  ${JAVATV_HOME}/javatv.jar:${JAVATV_HOME}/j2me_xml_ri.jar:${BASIS_HOME}/lib/ \

The example above is based on using javac from the Java 1.4.2 SDK. See the CDC Runtime Guide for more information about compiling Java applications for the CDC platform.

Running the Sample Applications

The mechanism for deploying and running the sample applications is different from conventional desktop platforms. The sample applications included with this release cannot demonstrate every capability of the Java TV API optional package.

The Java TV API RI can be configured by populating the SI database both programmatically or statically using an XML file.

The following basic capabilities can be demonstrated with the sample applications.

In addition, the RunXlet xlet launcher can be used to launch an xlet while bypassing the SI database.

The lib sub-directory contains the file The Java TV API RI looks for the file lib/ and uses the system property ServiceFileHandler to reference a class that is used to populate the SI database.

The ServiceFileHandler system property can be set to two values to illustrate different approaches to populating the SI database.

Using the RunXlet Xlet Launcher

This section describes how to use RunXlet, the Java TV API xlet launcher. Note that RunXlet is not an xlet manager. It takes the class name of a single target xlet as a command-line argument and executes that xlet. By default, RunXlet populates the SI database with the target xlet. Adding the -n flag to RunXlet launches the target xlet without populating the SI database.

The following example script runs the RunXlet launcher to run the xlet and populate the SI database. SvcDispXlet is a simple xlet that displays a list of all available service instances in the SI database.



${BASIS_HOME}/bin/cvm -cp \
  ${BASIS_HOME}/j2me_xml_ri.jar:${BASIS_HOME}/javatv.jar:. \
  RunXlet SvcDispXlet

Statically Loading a Java TV Service

The ReceiverFile class in the RI parses an XML file specified in the ServiceFile property of the lib/ file. This file's path is relative to the directory where the Java TV API RI is run. ReceiverFile is the default ServiceFileHandler. The default XML file is lib/JavaTVSampleFile01.xml. The specified XML file is read on startup of the Java TV API RI. Every ten seconds the XML file is checked to see if it has changed (the modification time is noted). If it has changed, the file is re-parsed. The general semantics of the re-parse are to replace duplicate SI elements (MODIFY are events generated), add new elements (ADD are events generated), and remove elements marked for removal (REMOVE are events generated).

JavaTVSampleFile01.xml refers to the video/ Quicktime movie file.

Programatically Loading a Java TV Service

The sample application samples/db/ performs the following operations:

In this release, all services specified in the SampleData_01 class refer to placeholder media files. The RI does not include those media files, so you must edit samples/db/ to point to valid media files (Quicktime .mov files) and then recompile the class. The following file references must be changed:

You can substitute these with Quicktime .mov files that use the Cinepak video format and the IMA4 ADPCM audio format.