Package com.sun.dtv.application

Application Management and Lifecycle Control.

See:
Description

Interface Summary

Application	Get attributes of an Application.
ApplicationProxy	Control an Application via the application manager.
AppManagerListener	Listener to be notified of changes in available applications.
AppProxyListener	Listener to be notified of changes to the application state.

Class Summary

AppFilter	AppFilter is called to accept an Application in a filter or not.
AppManager	AppManager provides control and access to Applications.
AppManagerPermission	AppManagerPermission is needed to query or control applications.

Package com.sun.dtv.application Description

Application Management and Lifecycle Control.

DTV Applications

DTV Applications run in a service driven environment managed by a system wide Application Manager. The Java DTV Runtime is one of the application runtimes on the device managed by the Application Manager. DTV Applications run in a dynamic multi-tasking environment driven by and responding to events from the broadcast media, user input, and tuners.

The Application Manager is a system component outside of the Java DTV Runtime that monitors and controls the execution of all applications. The Application Manager manages the Service contexts and the selected service in each context. Each service defines the applications that are permitted to run within its context. The Application Manager starts and stops applications to respond to changes in the service context by the device and user interface. In the case of signaling with KILL the application is stopped using Xlet.destroyApp(false); the application can choose to continue. In the case of signaling with DESTROY, the application is stopped using Xlet.destroyApp(true); the application is unconditionally destroyed.

The Application manager uses the broadcast media's application signaling to identify the set of applications that are considered to be available to each service. The information from the transport media is defined by ABNTNBR15606-3_2007 Section 12.18: Ginga Descriptors. This information is acted on by the Application Manager to start and stop applications, to make them available or not available, and to make them visible to the user or other applications or not.

The Application Manager collects and maintains information about the available and running applications. Applications can access the list of available and active applications applications using the AppManager class. The attributes of each Application are available from the Application class. Monitoring and control of applications is via the ApplicationProxy interface. Monitoring and control of applications is allowed only if the security policy allows the AppManagerPermission.

The DTV Java Application Model includes:

• Java DTV Packaging - Java ARchive (JAR)
• Java DTV Runtime - classpath, system libraries, etc.
• Java DTV Lifecycle - Xlet and XletContext
• Java DTV Authentication - JAR signing
• Java DTV Application Authorization - Security Policy
• Java DTV Service Context - Binding to service

Java DTV Application Packaging

Each application is packaged, authenticated, and authorized according to the common DTV Application Packaging and Security. Additional requirements specify the behavior for Java DTV applications.

Each application is contained within one or more JAR files [JAR]. The main JAR file contains the application class files, resource files, and a manifest that describes the application and its requirements. The JAR signing mechanism allows the JAR to be authenticated.

The JAR specification includes attributes to control how the application is executed. The JAR File Specification[JAR] defines the attributes and their interpretation. The interesting attributes include:

Manifest Attribute	Description
Main-Class	The application class implementing the Xlet Interface.
Class-Path	Refers to additional JARs that are added to classpath and are made available at runtime.

DTV Application Runtime

The DTV Runtime is established when an application must be started and is discarded when the application is destroyed. The runtime exists within a Java VM and provides the environment for one DTV application.

The runtime provides limited isolation between applications. All interactions between applications must be only via explicit use of APIs. Applications MUST NOT synchronize on System classes or system static objects; as the behavior across applications is unpredictable. There MUST NOT be any sharing of the state of application classes or objects between runtimes. ClassLoaders provide sufficient isolation of the classes and objects of the application. Implementations of the runtime MUST NOT synchronize on objects visible to applications.

Each Application MUST NOT be launched if another instance of the application is already active in the Service. The system MUST support multi-tasking with at least 2 Applications running concurrently.

System Properties

The following system properties are defined:

Property Name	Property Type	Property Value
com.sun.dtv.version	String	The version number of the DTV Java Runtime, the version of this specification "1.0".

XletContext for each application

The Java DTV Runtime MUST provide each application with an javax.microedition.xlet.XletContext including a set of DTV specific properties:

Property Name	Property Type	Property Value
com.sun.dtv.persistent.root	String	The root of the DTV file system.
com.sun.dtv.orgid	Integer	Organization id of the current application from the application manager.
com.sun.dtv.appid	Integer	Application id of the current application from the application manager.
javax.microedition.xlet.XletContext.ARGS	String[]	Arguments to the application via the Application Manager as provided by the application signaling or from an invocation of ApplicationProxy.start(java.lang.String[]).

Classpath and Classes

The application's JAR must be the first entry in the classpath for the application. All of the classes and resources it contains are made available the application at runtime.

The Class-Path attribute in the main section of the manifest contains a list of additional JAR files. Each of the JAR files must be added to the classpath. All of the classes and resources it contains are made available the application at runtime.

Processes, Threads and Threadgroups

Each application is started in its own thread group. The threadgroup MUST have its maxPriority be set to java.lang.Thread.NORM_PRIORITY.

Locale

Support for Locale within the Runtime includes:

• MUST support the EN.UK locale.
• MAY support any number of other locales.
• The default locale is pt_BR.

Text Encodings

Support for text encodings include:

• MUST support UTF-8 as defined by DataOutput.writeUTF(java.lang.String).
• MUST support Latin1 as defined by ISO 8859-1.
• MAY support additional text encodings.

SBTVD Application Lifecycle

The execution of an Application is managed by the Application Manager and is coordinated with the application using using Xlet and XletContext interfaces defined in javax.microedition.xlet.

The Application manager MUST set the classpath before the application is started to include the JAR file containing the application. For every JAR file, including the main JAR, the manifest MUST be examined and for each Class-Path attribute the referenced JAR file must be included. JAR files are examined depth first to add any referenced JARs. Each JAR MUST appear only once in the classpath when it is first referenced. Note: at runtime the application uses the URLClassLoader to specify locations (via locators) from which classes can be loaded dynamically.

The application MUST provide a class implementing the javax.microedition.xlet.Xlet interface and identify that class as the entry point of the application using the Main-Class attribute in the manifest. To initialize the application, an instance of the class is created using the constructor and the initXlet method is passed the XletContext. The XletContext has information from the runtime context for the application including properties and mechanisms to report state changes initiated by the application. The application states of loaded, paused, active, and destroyed are completely described by the specification of javax.microedition.xlet.

Note: javax.tv.xlet package is deprecated. The javax.microedition.xlet package is used for application management so that IXC can be used without duplicating the APIs or functionality. All instances of javax.microedition.xlet.XletContext MUST also implement javax.tv.xlet.XletContext. The interfaces have common methods and prescribed behaviors. This enables applications to use the instance with an explicit cast to javax.tv.xlet.XletContext in calls to javax.tv.service.selection.ServiceContextFactory.getServiceContext(xletContext).

DTV applications must cleanup before they exit either when Xlet.destroyXlet is called or before the application calls XletContext.NotifyDestroyed.

• Each thread created by the application must terminate.
• Each JMF Player created by the application must be stopped and closed.
• Each JavaTV ServiceContext created by the application must be stopped and closed
• Each ScarceResource reserved by the application must be released.
• Each Image with unflushed data must be flushed.
• The application must cleanup and return from Xlet.destroyXlet as quickly as possible.
• Each event listener registered must be removed.

Regardless of whether or not the DTV application has performed the cleanup required when an Xlet is destroyed, it is the responsibility of the implementation to release all ScarceResources and other resources, for example media related resources, used by the Xlet and to notify other applications listening for those resources using the APIs and listeners defined in each API.

Inter-Application Communication

DTV Applications can communicate with each other using the javax.microedition.xlet.ixc package. Communication from one application to another is established by binding an object to a name in the IxcRegistry and another application looking up the name and invoking the object's methods. The namespace is structured to allow common access to all of the names defined by signed and other applications and further all names defined for an organization and all of the names defined by an application. Each application is provided a part of the IXC namespace for itself, using the appId consisting of the organization id and application id. The construction of names is aided using the Application.getIxcFullyQualifiedName method.

DTV defines the structure of IXC names for applications to facilitate secure communications:

• secured - signed applications can communicate via the /dtv/signed/<appId>/ namespace. Each signed application can bind its own objects into its part of the namespace and can lookup objects of any signed application.
• unsecured - any application can communicate via the /dtv/ixc/<appId>/ namespace. Each unsigned application can bind its own objects into its part of the namespace and can lookup objects of any application.

This structure allows each application to reliably communicate with its peers in a controlled manner. Access to the parts of the namespace is controlled by the signed policy and unsigned policy.

Persistent Storage

Persistent Storage may be accessible to applications. The structure and access controls are defined in Persistent File Storage. The root of the filesystem is found in the System property com.sun.dtv.persistent.root. Access to files below the root are dictated by the security policy. Access to files above the root MUST cause a java.lang.SecurityException to be thrown.

The FileProperties APIs can be used to change the access rights of files that are owned by an application.

Recommended Security Policy For Java DTV

The security policy for Java DTV applications consists of recomendations for unsigned applications and signed applications. Signed applications can request additional permissions using the Per Application Policy. DTV Applications are not be authorized to use the enhanced functions and APIs of the device unless the application can be authenticated to a valid root certificate on the device. The DTV Application Packaging and Security applies to all Java DTV Applications.

Signed Application Policy

The following security policy is applied to signed applications and is combined with the Per Application Policy only if one is provided with a signed and authenticated application.

Permission	Description
java.util.PropertyPermission(<DTV defined system properties>, "read")	Allows read access to DTV defined properties available from java.lang.System.getProperty.
java.io.FilePermission(BroadcastFilesystem.getBroadcastRoot(), "read")	Allows read access to the broadcast file system.
javax.tv.media.MediaSelectPermission("*")	Allows access to selection of new media clips from the current Transport Stream.
javax.tv.service.ReadPermission("*")	Allows access to other services.
javax.tv.service.selection.ServiceContextPermission("getServiceContentHandlers", "own")	Allows access to all the content handlers for the applications own service.
javax.tv.service.selection.ServiceContextPermission("access", "own")	Allows access to the applications own service. Restricts access to other services.
Does not allow java.awt.AWTPermission	Restricts low level AWT control.
Does not allow java.util.PropertyPermission("user.language", "write")	Restricts changing the locale.
Does not allow java.lang.RuntimePermission	Restricts Runtime actions.
Does not allow java.io.SerializablePermission	Restricts overriding Serialization behavior.

For the Java DTV Runtime the Per Application Policy is mapped to the Java DTV Security policy. If the Policy Element is present then the corresponding Permission(s) below are included in the policy, with any parameters present in the element.

DTV Policy Element	Permission	Description
file	FilePermission(<ownerfiles>, "read,write")	ownerfiles is the concatination of the com.sun.dtv.persistent.root property with the value of the com.sun.dtv.orgid property separated by the appropriate file system delimiter.
applifecycle	AppManagerPermission("*", "read,manage")	Allows access to manage all applications in the current service.
networkdevice	NetworkDevicePermission("networkdevice.any", "dial=tel") and ScarceResourcePermission("networkdevice.any", "reserve")	Allows access to the network device, the default network and each telephone number.
dripfeed	DripFeedPermission("dripfeed://")	Allows access to the dripfeed control.
scarceresource	ScarceResourcePermission(name, actions)	Allows access to the named scarce resource with action(s).
tuning	ScarceResourcePermission("tuner.any", "reserve")	Allows access to all tuners.
smartcardaccess	javax.microedition.apdu.APDUPermission("aid")	Allows access to the SmartCard API.
serviceselect	SelectPermission("*", "*")	Allows access to all services.
userproperty	UserPropertyPermission("*", "read,remove,write")	Allows User Property actions read, remove, and write access.
network	SocketPermission(host, actions)	Allows access, for each host requested.
ixcaccess	IxcPermission("/dtv/signed/<appId>/*", "bind")	Allows binding names in the signed Application scope of the <appID> namespace.
ixcaccess	IxcPermission("/dtv/signed/*", "lookup")	Allows lookup of names in any signed Application scope of the namespace.
ixcaccess	IxcPermission("/dtv/ixc/<appId>/*", "bind")	Allows binding names in the unsecured scope for the <appID> namespace.
ixcaccess	IxcPermission("/dtv/ixc/*", "lookup")	Allows lookup of names in the unsecured scope of the namespace.
persistentfilecredential	FilePermission(filename, read/write mode)	Allows access for each filename and read or write mode.

Unsigned Application Policy

The following security policy applies to unsigned applications.

Permission	Description
java.util.PropertyPermission(<DTV defined system properties>, "read")	Allows read access to DTV defined system properties.
java.io.FilePermission(BroadcastFilesystem.getBroadcastRoot(), "read")	Allows read access to the broadcast file system.
javax.tv.media.MediaSelectPermission("*")	Allows access to selection of new media clips from the current Transport Stream.
javax.tv.service.ReadPermission("*")	Allows access to all services.
javax.tv.service.selection.ServiceContextPermission("getServiceContentHandlers", "own")	Allows access to all the content handlers for the application's own service.
javax.tv.service.selection.ServiceContextPermission("access", "own")	Allows access to the applications own service. Restricts access to other services.
Does not allow com.sun.dtv.media.dripfeed.DripFeedPermission	Restricts dripfeed control.
Does not allow java.awt.AWTPermission	Restricts low level AWT control.
Does not allow java.net.SocketPermission	Restricts network connections.
Does not allow java.util.PropertyPermission("user.language", "write")	Restricts changing the locale.
Does not allow java.lang.RuntimePermission	Restricts Runtime actions.
Does not allow java.io.SerializablePermission	Restricts overriding Serialization behavior.

Since:

JavaDTV1.0