Runtime NotesJavaTM TV API Optional PackageReference ImplementationVersion 1.1.1Connected Device ConfigurationDecember 2008 |
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:
Sample applications that use these programming features include:
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. |
| libmmedia.so | 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 Sample.mov, a sample QuickTime movie. |
The Java TV API RI requires the following files in lib:
| File | Comment |
|---|---|
|
|
|
| JavaTV.properties | 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/JavaTV.properties file. |
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. |
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.
% unzip jtv-1_1_1-linux-x86.zip
% cp ${JAVATV_HOME}/j2me_xml_ri.jar ${BASIS_HOME}/lib
% cp ${JAVATV_HOME}/javatv.jar ${BASIS_HOME}/lib
% cp ${JAVATV_HOME}/libmmedia.so ${BASIS_HOME}/lib
% cp ${JAVATV_HOME}/lib/* ${BASIS_HOME}/lib
The sample applications must be compiled with the following .jar files:
For example, the following script will compile the sample application in samples/db:
#!/bin/sh
J2SE_HOME=/java/1.4.2/linux-i586
BASIS_HOME=/java/pbp
JAVATV_HOME=/java/javatv
${J2SE_HOME}/bin/javac -bootclasspath \
${JAVATV_HOME}/javatv.jar:${JAVATV_HOME}/j2me_xml_ri.jar:${BASIS_HOME}/lib/btclasses.zip \
SampleData_01.java
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.
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 JavaTV.properties. The Java TV API RI looks for the file lib/JavaTV.properties 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.
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.
#!/bin/sh
BASIS_HOME=/java/pbp
JAVATV_HOME=/java/javatv
${BASIS_HOME}/bin/cvm -cp \
${BASIS_HOME}/j2me_xml_ri.jar:${BASIS_HOME}/javatv.jar:. \
RunXlet SvcDispXlet
The ReceiverFile class in the RI parses an XML file specified in the ServiceFile property of the lib/JavaTV.properties 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/Sample.mov Quicktime movie file.
The sample application samples/db/SampleData_01.java 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/SampleData_01.java to point to valid media files (Quicktime .mov files) and then recompile the class. The following file references must be changed:
LocatorImpl.setMediaFile("service:/SERV6",
"file:/c:/work/javatv/gatwick/data/lasco_c3.mpg");
LocatorImpl.setMediaFile("service:/SERV2",
"file:/c:/work/javatv/gatwick/data/12ftwt.mpg");
LocatorImpl.setMediaFile("service:/SERV8",
"file:/c:/work/javatv/gatwick/data/aae.mpg");
LocatorImpl.setMediaFile("service:/SERV2",
"file:/c:/work/javatv/gatwick/data/em-0002-01.mpg");
LocatorImpl.setMediaFile("service:/SERV3",
"file:/c:/work/javatv/gatwick/data/em-0002-02.mpg");
LocatorImpl.setMediaFile("service:/SERV1",
"file:/c:/work/javatv/gatwick/data/lasco_c3.mpg");
LocatorImpl.setMediaFile("service:/SERV10",
"file:/c:/work/javatv/gatwick/data/lasco_c3.mpg");
LocatorImpl.setMediaFile("service:/SERV15",
"http://www.bloomberg.com/videos/broadband/wm");
LocatorImpl.setMediaFile("service:/SERV5",
"file:/c:/work/javatv/gatwick/data/em-0002-02.mpg");
You can substitute these with Quicktime .mov files
that use the Cinepak video format and the IMA4 ADPCM audio format.
Copyright © 2008 Sun Microsystems, Inc. All rights reserved. Use subject to license terms.