org.dvb.application.storage
Interface ApplicationStorageController

All Known Subinterfaces:
StoredApplicationService, UnboundApplicationService

public interface ApplicationStorageController

Defines the methods for storing, listing and removing applications to and from a service.

Since:
MHP1.1.3

Method Summary
 AppID[] getStoredAppIDs()
          Lists the AppIDs of the applications that are stored within this service.
 int getVersionNumber(AppID appId)
          Return the version number of the stored application whose AppID is given as a parameter.
 void remove(AppID appId)
          Removes a stored application from this service.
 void remove(AppID[] appIds)
          Removes multiple stored applications from this service.
 void store(AppProxy[] apps, boolean[] autoStart, java.lang.String[][] args)
          Installs several applications into this stored service.
 void store(AppProxy[] apps, boolean[] autoStart, java.lang.String[][] args, ApplicationStorageListener listener)
          Installs several applications into this stored service.
 void store(AppProxy app, boolean autoStart, java.lang.String[] args)
          Installs an application into this stored service.
 void store(Locator locator, AppID[] apps, boolean[] autoStart, java.lang.String[][] args, ApplicationStorageListener listener)
          Installs several applications into this stored service.
 

Method Detail

store

void store(AppProxy app,
           boolean autoStart,
           java.lang.String[] args)
           throws InvalidApplicationException,
                  UserRejectedInstallException,
                  NotEnoughResourcesException,
                  InvalidDescriptionFileException,
                  ApplicationDownloadException

Installs an application into this stored service.

If ApplicationStorageHandler is supported by the implementation and such a handler is registered then the handler will be asked for permission to install the application. If no such handler is asked then the end user of the GEM terminal may be asked for permission. Applications should be prepared for the possibility of a user interface being shown under these circumstances.

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

Successfully adding an application to a stored service that is currently being presented shall cause the terminal to behave as if the application was added to the AIT - i.e. it will send an AppsDatabaseEvent.APP_ADDED event to registered listeners, and if the autoStart parameter is true then the application shall be started.

If the same version of the same application is already installed in this stored service, then (if the caller has sufficient permissions to install the application) this method shall update the stored representation of the AIT from the autoStart and args parameters, and return without throwing an exception. Terminals shall not store the application again. Terminals are not expected (but are allowed) to prompt the user for permission in this case. If the stored service is currently being presented, and the autostart setting is changed, then:

Note that calling this method with a new value for the args parameter shall not have any effect on an existing instance of an application.

If a different version of the same application is already installed in this stored service, then this method shall install the new version of the application as normal. (Note that for the purposes of this method description, "new" and "old" versions refer to the version specified by the AppProxy passed to this method and the version currently installed in the service, respectively. They do not refer to numeric comparison of version numbers). On success, the old version shall be removed from the service. On failure, the old version of the application shall remain as it was before this method was called. If the stored service is currently being presented, then on success:

Parameters:
app - an AppProxy representing the application to be installed
autoStart - true, if the application becomes an autostart application in the stored application service; false, if the application becomes a normal present (non-autostart) application in the stored application service.
args - parameters to be available to the application when started. Passing in either null or an array of size zero indicates no parameters are to be available. These parameters shall be available to applications when running as part of the stored application service using the Xlet property "dvb.installer.parameters".
Throws:
InvalidApplicationException - thrown if the application does not include an application_storage_descriptor, or if the application is not identified as able to run stand-alone in it's application_storage_desciptor.
InvalidDescriptionFileException - thrown if the application description file is missing, invalid or otherwise not conformant to the specification
NotEnoughResourcesException - thrown if the GEM terminal does not have enough resources, e.g. storage space, available for the application
UserRejectedInstallException - thrown if either the end user or an ApplicationStorageHandler rejects the installation
ApplicationDownloadException - thrown if the downloading of the application files was notsuccessful (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) or if the application failed authentication while being downloaded
java.lang.SecurityException - thrown if the application calling this method does not have an ApplicationStoragePermission with action "storeService" for the organisation_id of the application to be stored, and an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.2

store

void store(AppProxy[] apps,
           boolean[] autoStart,
           java.lang.String[][] args)
           throws InvalidApplicationException,
                  UserRejectedInstallException,
                  NotEnoughResourcesException,
                  InvalidDescriptionFileException,
                  ApplicationDownloadException

Installs several applications into this stored service.

If ApplicationStorageHandler is supported by the implementation and such a handler is registered then the handler will be asked for permission to install the application. If no such handler is asked then the end user of the GEM terminal may be asked for permission. Applications should be prepared for the possibility of a user interface being shown under these circumstances.

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

This method either succeeds or fails completely. It will never install some applications but not others.

For each specified application, if that application is already installed in the service (whether the same version or a different version, then the rules specified in the store() method that stores a single application shall apply regarding updating the application and/or the stored representation of the AIT for that application. Note that the preceeding statement that this method either completely succeeds or completely fails still applies.

If this service is being presented, then on success the rules in the store() method that stores a single application regarding sending AppsDatabaseEvents and starting and killing applications shall apply.

Parameters:
apps - an array of AppProxys representing the applications to be installed. May not be null or zero-length.
autoStart - An array that is the same length as apps where each element is true, if the corresponding application in apps becomes an autostart application in the stored application service; or false, if the application becomes a normal present (non-autostart) application. May not be null.
args - parameters to be available to the applications when started. May be null, indicating all applications take no parameters. Otherwise it is an array that is the same length as apps, where each element is the arguments for the corresponding application in apps. If the element is either null or a subarray of size zero, that indicates no parameters are to be available. These parameters shall be available to applications when running as part of the stored application service using the Xlet property "dvb.installer.parameters".
Throws:
java.lang.IllegalArgumentException - If the arrays passed to this method have different lengths, or if they have length zero.
InvalidApplicationException - thrown if any of the applications do not include an application_storage_descriptor, or if any of the applications are not identified as able to run stand-alone in their application_storage_desciptor.
InvalidDescriptionFileException - thrown if one of the application description files is missing, invalid or otherwise not conformant to the specification
NotEnoughResourcesException - thrown if the GEM terminal does not have enough resources, e.g. storage space, available for the applications
UserRejectedInstallException - thrown if either the end user or an ApplicationStorageHandler rejects the installation
ApplicationDownloadException - thrown if the downloading of the application files was notsuccessful (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) or if the application failed authentication while being downloaded
java.lang.SecurityException - thrown if the application calling this method does not have ApplicationStoragePermissions with action "storeService" for the organisation_ids of all the applications to be stored, and an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.2

store

void store(AppProxy[] apps,
           boolean[] autoStart,
           java.lang.String[][] args,
           ApplicationStorageListener listener)

Installs several applications into this stored service.

If ApplicationStorageHandler is supported by the implementation and such a handler is registered then the handler will be asked for permission to install the application. If no such handler is asked then the end user of the GEM terminal may be asked for permission. Applications should be prepared for the possibility of a user interface being shown under these circumstances.

This method is asynchronous with completion reported via the ApplicationStorageListener.

This method either succeeds or fails completely. It will never install some applications but not others.

For each specified application, if that application is already installed in the service (whether the same version or a different version, then the rules specified in the store() method that stores a single application shall apply regarding updating the application and/or the stored representation of the AIT for that application. Note that the preceeding statement that this method either completely succeeds or completely fails still applies.

If this service is being presented, then on success the rules in the store() method that stores a single application regarding sending AppsDatabaseEvents and starting and killing applications shall apply.

Parameters:
apps - an array of AppProxys representing the applications to be installed. May not be null or zero-length.
autoStart - An array that is the same length as apps where each element is true, if the corresponding application in apps becomes an autostart application in the stored application service; or false, if the application becomes a normal present (non-autostart) application. May not be null.
args - parameters to be available to the applications when started. May be null, indicating all applications take no parameters. Otherwise it is an array that is the same length as apps, where each element is the arguments for the corresponding application in apps. If the element is either null or a subarray of size zero, that indicates no parameters are to be available. These parameters shall be available to applications when running as part of the stored application service using the Xlet property "dvb.installer.parameters".
listener - the listener to be notified of the success or failure of this installation.
Throws:
java.lang.IllegalArgumentException - If the arrays passed to this method have different lengths, or if they have length zero.
java.lang.SecurityException - thrown if the application calling this method does not have ApplicationStoragePermissions with action "storeService" for the organisation_ids of all the applications to be stored, and an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.3

store

void store(Locator locator,
           AppID[] apps,
           boolean[] autoStart,
           java.lang.String[][] args,
           ApplicationStorageListener listener)

Installs several applications into this stored service. The applications are from a service which need not be selected.

If ApplicationStorageHandler is supported by the implementation and such a handler is registered then the handler will be asked for permission to install the application. If no such handler is asked then the end user of the GEM terminal may be asked for permission. Applications should be prepared for the possibility of a user interface being shown under these circumstances.

This method is asynchronous with completion reported via the ApplicationStorageListener

This method either succeeds or fails completely. It will never install some applications but not others.

For each specified application, if that application is already installed in the service (whether the same version or a different version, then the rules specified in the store() method that stores a single application shall apply regarding updating the application and/or the stored representation of the AIT for that application. Note that the preceeding statement that this method either completely succeeds or completely fails still applies.

If this service is being presented, then on success the rules in the store() method that stores a single application regarding sending AppsDatabaseEvents and starting and killing applications shall apply.

Parameters:
locator - the locator of the service from which the applications are to be stored
apps - an array of application ids identifying the applications to be stored
autoStart - An array that is the same length as apps where each element is true, if the corresponding application in apps becomes an autostart application in the stored application service; or false, if the application becomes a normal present (non-autostart) application. May not be null.
args - parameters to be available to the applications when started. May be null, indicating all applications take no parameters. Otherwise it is an array that is the same length as apps, where each element is the arguments for the corresponding application in apps. If the element is either null or a subarray of size zero, that indicates no parameters are to be available. These parameters shall be available to applications when running as part of the stored application service using the Xlet property "dvb.installer.parameters".
listener - the listener to be notified of the success or failure of this installation.
Throws:
java.lang.IllegalArgumentException - If the arrays passed to this method have different lengths, or if they have length zero.
java.lang.SecurityException - thrown if the application calling this method does not have ApplicationStoragePermissions with action "storeService" for the organisation_ids of all the applications to be stored, and an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.3

remove

void remove(AppID appId)
            throws UserRejectedInstallException

Removes a stored application from this service.

Applications should be prepared for the platform consulting the end user of the GEM terminal for the permission to remove the application

If the application identified by the AppID passed in as a parameter is not installed in this service, and the caller has the permissions that would be needed to remove the application if it was installed, the method shall fail silently.

Successfully removing an application from a stored service that is currently being presented shall cause the terminal to send an AppsDatabaseEvent.APP_DELETED event to registered listeners, and if the application is Loaded, Active or Paused then it shall be destroyed as if it had been signalled as KILL in the AIT. (Note that there is no special-case for if an application removes itself from a stored service - this is not an error and shall be handled normally).

Parameters:
appId - AppID of the application to be removed
Throws:
UserRejectedInstallException - If the user chose not to remove the application.
java.lang.SecurityException - Thrown if the application calling this method does not have an ApplicationStoragePermission with action "removeService" for the organisation_id of the application to be removed, and an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.2

remove

void remove(AppID[] appIds)
            throws UserRejectedInstallException

Removes multiple stored applications from this service.

Applications should be prepared for the platform consulting the end user of the GEM terminal for permission to remove the applications

If an application identified by the AppIDs passed in as a parameter is not installed in this service, and the caller has the permissions that would be needed to remove the application if it was installed, then this method shall ignore that AppID.

This method either succeeds or fails completely. It will never remove some installed applications but not other installed applications.

Successfully removing application(s) from a stored service that is currently being presented shall cause the terminal to send an AppsDatabaseEvent.APP_DELETED event for each application to registered listeners, and if any of the removed applications are Loaded, Active or Paused then they shall be destroyed as if they had been signalled as KILL in the AIT. (Note that there is no special-case for if an application removes itself from a stored service - this is not an error and shall be handled normally).

Parameters:
appIds - AppIDs of the applications to be removed
Throws:
java.lang.IllegalArgumentException - If the array passed to this method has length zero.
java.lang.SecurityException - thrown if the application calling this method does not have ApplicationStoragePermissions with action "removeService" for the organisation_ids of all the applications to be removed, and an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
UserRejectedInstallException - If the user chose not to remove the application.
Since:
MHP1.1.2

getStoredAppIDs

AppID[] getStoredAppIDs()
Lists the AppIDs of the applications that are stored within this service.

Returns:
an array of AppID object representing the stored application
Throws:
java.lang.SecurityException - Thrown if the application calling this method does not have an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.2

getVersionNumber

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
Throws:
java.lang.SecurityException - Thrown if the application calling this method does not have an ApplicationStoragePermission with action "manageService" for the organisation_id of this service.
Since:
MHP1.1.2