org.dvb.application.storage

Class ApplicationCache

java.lang.Object

org.dvb.application.storage.ApplicationCache

public abstract class ApplicationCache
extends Object

A cache to store applications so that they may be started faster when signalled in broadcast.

Applications stored via this mechanism cannot be started directly, only via an AIT entry in a broadcast service.

Note that applications are globally uniquely identified by a combination of organisation ID, application ID, and version number. Application authors should ensure that their storable applications are consistently broadcast.

Each instance of ApplicationCache can store only a single version of an application - i.e. within an ApplicationCache, an organisation ID and application ID pair can uniquely identify an application. Successfully storing a different version of a cached application than the current one in an ApplicationCache shall result in the current one being removed from that ApplicationCache instance. If the call to store fails then the current version shall not be removed.

A single MHP terminal will support many instances of ApplicationCache. These shall share a single underlying application store, and that underlying store shall use reference-counting or similar techniques to allow several stored services and ApplicationCache instances to contain the same application without wasting storage space by storing the same application multiple times. Space permitting, the underlying application store shall support storing several different versions of a single application (i.e. same organisation ID and application ID but different version numbers) where these are stored via different ApplicationCache instances or form part of different stored services. The underlying application store shall manage the removal of versions of stored applications which are not used in any stored services or application caches.

If an application is already cached in one ApplicationCache, storing the same version of the same application in a different ApplicationCache shall not fail due to insufficient disk space, and if all files in the ADF are labelled as critical, it shall not fail due to inability to download files listed in the ADF and shall complete quickly (without waiting for the files listed in the ADF to be broadcast).

Since:

MHP1.1.2

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ApplicationCache() Interoperable applications shall not call this constructor.

Method Summary

Methods

Modifier and Type	Method and Description
static ApplicationCache	getDefaultCache() Get the default cache that this application can use.
abstract AppID[]	getStoredAppIDs() Lists the AppIDs of the applications that are stored within this cache.
abstract int	getVersionNumber(AppID appId) Return the version number of the stored application whose AppID is given as a parameter.
abstract void	remove(AppID appId) Requests the MHP terminal to initiate the removal of an application stored in the MHP terminal from this cache.
abstract void	store(AppProxy app, boolean canPrompt) Store an application in the MHP terminal.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ApplicationCache

protected ApplicationCache()

Interoperable applications shall not call this constructor.

Since:

MHP1.1.2

Method Detail

getDefaultCache

public static ApplicationCache getDefaultCache()

Get the default cache that this application can use. Note that in MHP 1.1, applications cannot access any cache other than the default one.

The object returned depends on the organisation_id of the calling application. Applications with the same organisation_id shall recieve the same ApplicationCache. Applications with different organisation_id shall recieve different, independent instances of ApplicationCache. (I.e. if one application stores an application or removes a stored application, that operation shall be visible to another application via the methods on this class if and only if the other application has the same organisation_id as the first application).

Returns:

An ApplicationCache instance.

Throws:

SecurityException - Thrown if the application calling this method does not have an ApplicationStoragePermission with action "manageCache" for it's own organisation_id.

Since:

MHP1.1.2

store

public abstract void store(AppProxy app,
         boolean canPrompt)
                    throws InvalidApplicationException,
                           NotEnoughResourcesException,
                           InvalidDescriptionFileException,
                           ApplicationDownloadException

Store an application in the MHP terminal.

MHP terminals may prompt the user for permission to free up resources if and only if all of the following conditions hold:

• canPrompt is true
• the caller has the necessary permissions (i.e. the SecurityException will not be thrown)
• the application is valid (i.e. the InvalidApplicationException will not be thrown)
• the application description file is valid (i.e. the InvalidDescriptionFileException will not be thrown)
• the MHP terminal determines that there are insufficient resources to store the application, and it cannot or will not silently free up enough resources (i.e. the NotEnoughResourcesException would be thrown)
• the MHP terminal determines that it could free up sufficient resources to store the application (i.e. to ensure the NotEnoughResourcesException would not be thrown) if it had the user's consent

Prompting the end-user for permission is not required however applications setting canPrompt to true should be prepared for the possibility of it happening. Note that if the user decides not to allow the terminal to free up resources, the NotEnoughResourcesException will be thrown (as if the terminal had not asked the user at all).

Note: This method is synchronous and will block until the storing is either completed or fails.

Storing (the same version of) an application that is already stored elsewhere (e.g. in another ApplicationCache, or in a StoredApplicationService) shall use the already-stored files.

Parameters:

app - an AppProxy representing the application to be installed

canPrompt - If true, the terminal is allowed to prompt the user for permission to free up space in order to store this application. If false, the terminal shall not prompt the user for permission to cache this application.

Throws:

InvalidApplicationException - thrown if the specified application is not signalled as capable of being stored, or if the specified application is not signalled as part of the same service as the calling application.

NotEnoughResourcesException - thrown if the MHP terminal does not have enough resources, e.g. storage space, available for the application

InvalidDescriptionFileException - thrown if the application description file is missing, invalid or otherwise not conformant to the specification

ApplicationDownloadException - thrown if the downloading of the application files was not successful (e.g. a carousel error, a file in the application description file is missing in the carousel, if the application was removed from the AIT or from its transport mechanism while installation is in progress, etc).

SecurityException - Thrown if the application calling this method does not have an ApplicationStoragePermission with action "storeCache" or "*" for the organisation_id of the application to be stored.

Since:

MHP1.1.2

remove

public abstract void remove(AppID appId)

Requests the MHP terminal to initiate the removal of an application stored in the MHP terminal from this cache.

The platform is not expected to consult the end user of the MHP terminal for the permission to remove the application.

This specification does not prevent a terminal keeping an application in cache even after all references to it have been removed via this API.

If the application identified by the AppID passed in as a parameter is not installed in this cache, the method shall fail silently.

If the application is already stored elsewhere (e.g. in another ApplicationCache, or in a StoredApplicationService) then those caches and stored services shall not be affected by calling this method.

Parameters:

appId - AppID of the application to be removed

Throws:

SecurityException - thrown if the application calling this method does not have an ApplicationStoragePermission with action "removeCache" for the organisation_id of the application to be removed and an ApplicationStoragePermission with action "manageCache"

Since:

MHP1.1.2

getStoredAppIDs

public abstract AppID[] getStoredAppIDs()

Lists the AppIDs of the applications that are stored within this cache.

Returns:

an array of AppID objects representing the stored applications

Since:

MHP1.1.2

getVersionNumber

public abstract int getVersionNumber(AppID appId)

Return the version number of the stored application whose AppID is given as a parameter.

Parameters:

appId - the AppID of the application whose version is queried

Returns:

the version number of the stored application, returns -1 if the application given as a parameter is not stored as part of this cache.

Since:

MHP1.1.2