ARRIS Enterprises, Inc. Confidential Information

Application Service Overview

The Application Service is responsible for handling applications in the system. An application is a software module which, in contrast to a service in the platform, is designed to interact with the user. The basic functionality of the Application Service is to facilitate concurrent execution of multiple applications.

Overview

To manage the behaviours of different types of applications, each application is designated as either primary, secondary or noninteractive. The primary application is the main UI, secondary applications are typically OTT services or similar, and noninteractive applications are auxiliary system applications that may render graphics. For more details, see multiple application terminology.

Applications have application properties that convey various pieces of information about the application and its behavior. Properties of secondary applications can be read via the ToiSecondaryApplication.getProperties() function. For information about properties that may be relevant for the portal to take into account, consult the application specific documentation.

The process of deciding which application should be visible and receive user input is the responsibility of the user interface, which is implemented in the primary application. The Application Service supplies the interface to implement this functionality. This means that the user interface needs to actively decide which secondary application to make visible and when it should receive input.

The primary application is always visible on top of any running secondary applications. This enables functionality in the primary application such as rendering popups or menus on top of other applications. It also means that the primary application needs to make itself transparent in order for any secondary applications to actually become visible to the end user.

In a production environment the primary application should always be running. If the primary application crashes, any secondary applications that were visible will be hidden and the primary application will be restarted.

Application States

The main responsibility of the Application Service is to manage the states of the secondary applications. The secondary applications can be in four different states: STATE_STOPPED, STATE_LOADING, STATE_VISIBLE, STATE_HIDDEN.

Secondary Application state diagram.

In the STATE_STOPPED state, the application is installed on the system but is not being executed or process (or processes) does no longer exist in the system. The application starts in this state by default and may return to it by exiting in an orderly fashion, crashing or being stopped due to lack of system resources. When the platform has released all resources and the application should be restarted to running state it will leave the STATE_STOPPED state and enter the STATE_LOADING state.
During the STATE_LOADING state, the application start procedure will be performed and it will initialize itself to become fully operational. The application will leave this state autonomously and enter HIDDEN once it is ready to be interacted with.
In the STATE_HIDDEN state, the application is running but is not visible to the user. In this state, it may be restarted by calling ToiSecondaryApplication.start(). Doing so will make the application reenter the STATE_LOADING state without going via STATE_STOPPED.
In the STATE_VISIBLE state, the application is running and is visible to the user when the primary application makes itself transparent. The application may have input focus in this state. As a rule, secondary applications will not enter this state unless ToiSecondaryApplication.show() has explicitly been called.

Dealing with state changes

Changing the state of a secondary application is an asynchronous operation that takes time to complete and may fail. Therefore it's not advisable to issue a command to a secondary application and then immediately perform some operation that assumes that the state transition has been completed successfully, such as making the portal transparent to show the application beneath it.

The recommended way to handle such situations is to provide an AsyncCallback when calling functions that lead to a state change in a ToiSecondaryApplication. The onCompleted() function will be called after the application has finished its transition to the new state.

Sometimes, secondary applications will change states for other reasons than a function being called on a ToiSecondaryApplication instance. Examples for when this happens includes the system entering standby, a previously visible secondary application becoming hidden because show() was called on another application, an application being closed from within its own UI, a web application calling window.close(), or an application crashing.

To detect state changes that didn't originate from the portal, the event listener mechanism can be used. The events include a ToiStateChangeReason which provides information about what kind of circumstance caused the state change to occur. Listening for these events allow a portal to react to events such as crashes, self-initiated exits or similar events.

STATE_CHANGE_REASON_UNEXPECTED_EXIT occurs when an application crashed or exited in an abnormal fashion.
STATE_CHANGE_REASON_USER_COMMAND occurs when the end-user interacts with the secondary to change its own state (having the secondary calling window.close() for example). This reason can also be given if the portal uses the application service to change the secondary applications state. Second hand effects such as an application becoming hidden because another was made visible will also trigger this reason.
STATE_CHANGE_REASON_SYSTEM_COMMAND occurs when the platform initiates a state change. Examples include the system entering standby or going down for a reboot.

Starting and restarting

When start() is called on a secondary application, an argument may be provided. This argument is interpreted by the application. For information about what arguments can be provided, consult the documentation for each application.

If start() is called on an application that is already running, it will enter the STATE_LOADING state and use the arguments provided in the latest start() for its internal logic.

Standby behaviour

When the STB enters a standby state, any visible secondary applications will change state and enter either the STATE_HIDDEN or STATE_STOPPED state. They will not reenter the STATE_VISIBLE state autonomously when the STB leaves the standby state.

As a consequence of the above, the primary application regains input focus and is expected to make the choice to either display graphics and resume normal operation or explicitly show() a secondary application when the STB leaves the standby state.

Setting input focus

Only one primary or secondary application can have input focus. As a consequence, setting input focus to a secondary application will remove input focus from whatever application had it previously.

Setting input focus to the primary application is done by resetting input focus via the Application Service.

Input handling

Making input focus exclusive to one application is intended to simplify input handling. In order to enable the primary application to retain control when it has lost input focus, it can eavesdrop on predefined inputs via ToiSecondaryApplication.subscribeKey().

Subscribing via subscribeKey() is done for each secondary application and may be done at any time. This relieves the primary application from the need to keep explicit track of which, if any, secondary application currently has input focus.

A secondary application cannot have input focus if it is not VISIBLE. A secondary application that has input focus and leaves the VISIBLE state for any reason will automatically relinquish input focus back to the primary application.

Playback Ownership

Media playback requires resources that are very limited, which means that for most configurations only one video tag can be playing content at any one time. For that reason, the concept of playback ownership determines which application is allowed to utilize these resources. The playback owner is determined as follows:

If a secondary application is visible, it is the playback owner. Otherwise, the primary application is playback owner.

Portal developers should close() the ToiMediaPlayer before showing a secondary application, and only open it again once the secondary application is hidden. To ensure that no race conditions arise, it is recommended to wait for the media player to complete its state change before showing the secondary application and to wait for the secondary application to finish its transition to STATE_HIDDEN before opening the media player.