Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

Copyright © 2006 Sun Microsystems, Inc. All rights reserved.

JSR-927 (Maintenance Release)

Java TV API 1.1 (JSR-927)

This is the specification of the Java TVTM API, version 1.1.


Java TV Provides a mechanism by which Xlets may discover their root container and describes a mechanism for alpha blending. Provides a means for referencing data and resources accessible via the Java TV APIs. Provides controls and events for the management of real-time media in a television environment. Provides access to IP datagrams transmitted in the broadcast stream. Provides mechanisms for accessing the service information (SI) database and APIs representing the SI elements it contains. Provides APIs to support electronic program guides (EPGs), including program schedules, program events and program ratings. Provides APIs to navigate through services and hierarchical service information. Provides a mechanism to select a Service for presentation. Provides additional information about the transport mechanisms that deliver the content the SI data describes. Provides APIs for creating and managing timer events. Provides interfaces used by applications and the application manager to communicate.

Java Media Framework  


This is the specification of the Java TVTM API, version 1.1.


This specification describes the Java TVTM API, a Java Micro Edition (Java ME) Optional Package that provides control over functionality unique to television receivers. Some of the features that the Java TV API provides are: access to the service information database, content selection, TV-specific media player control, and access to data that is broadcast with the television signal.

The Java TV API is primarily directed at an audience of Java developers who are producing interactive television content or content-creation tools.  Much of the functionality that is required by a television content developer is provided by the Java platform on the receiver. Typically, the PersonalJava application environment provides the Java platform for television receivers. The Java TV API describes those aspects of the television receiver that are not already addressed by some portion of the application environment.

The Java TV API is restricted as much as possible to functionality that is unique to a television receiver. Some APIs that are generic to consumer electronics devices, such as persistent storage mechanisms, are not included in the Java TV API. These non-television specific APIs are provided in new definitions for the application environment or are being developed in conjunction with various television standards bodies. In some cases, presumptions about television requirements will proscribe the use of other APIs available, either as part of the application environment or as an extension to the Java platform. These are noted in this specification where relevant.

The Java TV API can be deployed in environments with existing standards for such things as service and program information. It is important that those existing standards and code based on those standards are easily integrated within the Java TV API framework. Therefore, the Java TV API is defined with a relatively high level of abstraction from hardware and over-wire protocols.

Because the Java TV API is an extension to the Java platform this specification does not describe minimal or performance-related requirements.  This specification is a detailed description of the API elements that comprise the Java TV API and is intended to be read along with the Java TV API Technical Overview.

General Requirements

Relationship to Other Specifications

Personal Basis Profile

The Java TV API Optional Package must be used in conjunction with a Java ME Profile with at least the capabilities of Personal Basis Profile, version 1.0b (JSR-129).

Java Media Framework

The Java TV API 1.1 includes the APIs formerly provided by the Java Media Framework (JMF), version 1.0.

Security Architecture

The Java TV API requires an application environment that includes the Java 2, Standard Edition (J2SE) security model (i.e., the JDK 1.2 APIs for supporting and implementing fine-grained access control and code signing). A description of Java TV's security architecture can be found in this Java TV security document. Note that, unless otherwise specified, methods in the Java TV API that check security permissions do so by calling java.lang.SecurityManager.checkPermission(Permission p).

Null Parameters

If null is passed as an input parameter to a constructor or method, java.lang.NullPointerException is thrown unless otherwise noted. Exception and event classes accept null input parameters to their constructors without throwing exceptions, causing null to be subsequently returned by their appropriate query methods.


The Java TV API is designed to scale across a wide range of broadcast environments and receiver functionality. The APIs defined in this specification comprise a framework that is populated according to the capabilities of the platform on which it is implemented. Scalable behavior is noted in the specification where appropriate.

Optionally Implemented Interfaces

Some interfaces in this specification are optionally implemented by the classes of objects obtainable through the Java TV API. Such interfaces must always be present in the Java TV API implementation, but applications must test for their presence on certain objects at runtime. For example, Service objects optionally implement the ServiceNumber interface. If s is an instance of Service, then
must not throw java.lang.ClassNotFoundException, but
(s instanceof
may or may not be true.

Callback Threads

If a method M is indicated to induce a subsequent callback operation, then such callbacks occur via a different thread than the thread used to call M. Callback methods are instead invoked by system threads that are guaranteed to hold no locks on application objects. Note that there may be a severe limit on the total number of available system threads; therefore applications should be aware that extensive processing or blocking in callback threads may delay further callbacks from occuring. Please see MediaSelectListener, SIChangeListener (and subinterfaces), SIRequestor, ServiceContextListener and TVTimerWentOffListener.

Please send any comments on this specification to

JSR-927 (Maintenance Release)

Copyright © 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to License Terms. Your use of this web site or any of its content or software indicates your agreement to be bound by these License Terms.

For more information, please consult the JSR 927 specification.