Application Provisioning

Overview and Goals

This chapter describes how application suites and LIBlets are provisioned; that is, how application suites and LIBlets are deployed to client devices, and the requirements imposed upon a client device to support these deployments. Following these recommendations will help ensure interoperability between clients and servers from all manufacturers.

There MUST be only one provisioning mechainsm in a concrete implementation though and it must remain unchanged. With other words, if an implementation has decided to implement a certain provisioning mechanism, there MUST NOT be any other way to install, update or delete application suites in this implementation.

One possible implementation of Provisioning is the OTA Provisioning as known from MIDP and IMP. The OTA Provisioning chapter describes how this kind of provisioning should look like in case an implementation decides to implement Provisioning this way.

The ability of an implementation to support provisioning is optional in MEEP 8. If an implementation decides that is does not have to support provisioning (as all application suites are already pre-installed during the manufacturing of the target device and there is no need for updates), it can decide to skip it. Also the way of provisioning - if supported - can be freely chosen as it is out of scope of the specification (see later in this section for details).

Devices MAY provide mechanisms that allow the discovery of applications. Throughout this chapter, an application with this functionality will be referred to as the Discovery Application, or DA. Please be aware that a DA does not make sense for any provisioning mechanism, so for a concrete provisioning mechanism it is possible that it will never include a DA.

The installation mechanism used during the provisioning is orthogonal to the provisioning mechanism itself. So installation can be done via the HTTP/HTTPS protocol (if available) as known from the OTA Provisioning mechanism as defined in the IMP-NG specification, but also e.g. BluetoothTM wireless technology, serial cable, IrDATM, etc.). The specification of those installation mechanisms re outside the scope of this specification, with the exception of the HTTP/HTTPs based installation variant of the OTA provisioning mechanism.

The term Application Management Software (AMS) is a generic term used to describe the software on the device that manages the transfer and lifecycle of applications. This term does not refer to any specific implementation and is used for convenience only. In some implementations, the term Java Application Manager (JAM) is used interchangeably.

This chapter describes the general functional requirements of the device and the functions supporting the application suite lifecycle and LIBlet provisioning. Descriptions are included for additional Application Attributes and mechanisms that identify the device type and characteristics to servers providing application suites and LIBlets.

Functional Requirements for Provisioning

A MEEP 8 implementation supporting provisioning:

Application Suite Lifecycle

The lifecycle of an application suite for an implementation supporting provisioning consists of discovery (optional), installation, update, invocation and deletion.

The lifecycle of a LIBlet for an implementation supporting provisioning consists of discovery (optional), installation, update, and deletion.

Discovery

Application discovery is the process by which an application suite is discovered using the device. The ability of Discovery itself is optional, as the Provisioning can take place in a way that does not require that the device discovers the application suite itself. Discovery and installation of application suites, if supported, MUST follow the following high-level scheme:

Provisioning

When an application suite is provisioned, all files that comprise the application are transferred to the device for installation. In addition to the application suite JAR file, one or more LIBlet JAR files could be transferred.

This section describes how the Discovery Application (DA, if any) and the Application Management System (AMS) handle the various components of the application suite.

Application Suite Provisioning

As mentioned before, the mechanism of discovery (if supported) is out of scope of this specification. As a result of a discovery or from another source, an information is available pointing to an Application Descriptor (if supported) or to the application suite itself. Once the information is available, the following steps should be performed:

  1. The Application Descriptor (if supported) or the application suite itself the information points to is checked to have the correct structure to enable retieval of information about the application suite (in case of an Application Descriptor) or the direct installation (otherwise), and a transfer (if necessary) is initiated.
  2. After completing the transfer (if any), the necessary information is passed to the AMS on the device to start the installation process. If an Application Descriptor is supported, it is used by the AMS to determine if the associated application suite can be successfully installed and executed on the device. This may involve transfer (if necessary) and check of Application Descriptors of any LIBlets the application suite depends on, if any LIBlet dependencies are specified by the application suite.

  3. If Application Descriptor (if supported) or the application suite itself is delivered in a transport format that is not the Unicode encoding that is specified by the specification it MUST be converted before it can be used. The default character set it has to be converted into is UTF-8. It is expected that an implementation is able to recognize and convert the transport format used, otherwise the installation MUST fail.

    The attributes in the Application Descriptor (if supported) MUST be formatted according to the syntax defined in Application Attributes; otherwise the provisioning MUST fail. All of the application attributes designated as mandatory by Appendix A MUST be present in the Application Descriptor (if supported); otherwise the provisioning MUST fail. If Application Descriptors are supported, and an Application Decriptor contains any application attributes that are allowed only in the Jar manifest (see Appendix A), then the provisioning MUST fail.

LIBlet Provisioning

LIBlet provisioning is performed as part of application provisioning.

If Application Descriptors are supported, the application suite JAD file lists its LIBlet dependencies. Each LIBlet may in turn have other LIBlet dependencies. In this case, and if a transfer of installation files is necessary for the respective provisioning mechanism, the JAD files involved, for both application and LIBlets, MUST be transferred first before any application suite or LIBlets can be transferred. Based on those JAD files, the device SHOULD calculate the total static size required for installation. Also, any JAD only validation steps MAY be undertaken before the actual installation data transfer (if required) is started.

Installation

Application installation is the process by which any transfer of an application suite as far as rwquired by the provisoning mechanism is performed and applications are made available for running. Application installation is optional in MEEP 8, but MUST be supported if Provisioning is supported.

If the application suite depends on one or more LIBlets, implementation MAY make the user aware of all LIBlets the application suite depends on. The means by which application dependencies are presented to the user are implementation specific.

LIBlet installation is done as part of the application suite installation process. Since other applications could depend on other versions of a LIBlet already installed in the device, a LIBlet is not simply replaced with a newer version. Instead, another (but typically newer) version of the LIBlet is installed. Any existing version of the LIBlet MUST NOT be deleted if there are other applications or LIBlets depending on it. It follows that multiple versions of the same LIBlet MAY reside on the device at the same time.

At installation of a trusted application suite, the implementation MAY present to the user security information related to the application suite.

During installation, the user MAY be informed of progress. The way this happens is implementation-dependent. If the installation is interrupted by any reason, the device MUST be left in the state it was in before installation began.

If the application suite is already installed on the device, it SHOULD be treated as an update. See the Update section for additional information on how to handle an update.

To install an application suite, the AMS performs the following series of steps and checks and MAY provide the user with feedback about the progress (in an implementation-dependent manner):

  1. The device initiates the transfer of the application suite (in case the provisioning mechanism includes any transfer operations).
  2. The application suite MUST be checked to verify that the retrieved application suite is valid and can be installed on the device. The following problems may occur:
    1. If there is insufficient memory to store the application suite on the device, the installation MUST fail. In case a LIBlet dependency is specified, the device MUST first verify there is sufficient persistent storage space by summing the JAR size specified in the JADs of the application suite and all of the LIBlets that the application suite declares dependency on, directly or indirectly, using the following formula:
      MIDlet-Jar-Size + Σ(LIBlet-Jar-Size for distinct LIBlets)
      The associated JARs will only be transferred if there is sufficient persistent storage space. If a LIBlet already exists on the device, its size will be omitted from this total size.
    2. If the application suite code is not available at the place the provisioning parameters specify it should, the installation MUST fail. Similarly, if a dependent LIBlet is not already installed on the device and cannot be found at the place the provisioning parametrs specify it should, the installation of the application suite MUST fail.
    3. If Application Descriptos are supported, and the size of the application suite to be installed does not match the size specified in the Application Descriptor, the installation MUST fail.
    4. If the manifest or any other file can not be extracted from the piece of software containing the application suite, like a JAR, the installation MUST fail.
    5. If the manifest is not in the correct syntax, or if any of the required application attributes are missing in the manifest, or if the manifest contains any application attributes that are allowed only in the JAD (see Appendix A), then the installation MUST fail.
    6. If Application Descriptors are supported, and the mandatory attributes in the descriptor MIDlet-Name, MIDlet-Version, and MIDlet-Vendor do not match those in the manifest of the application suite, the installation MUST fail. Similarly, if the mandatory attributes in the LIBlet descriptor LIBlet-Name, LIBlet-Version, and LIBlet-Vendor do not match those in the LIBlet manifest, the installation of the application suite MUST fail as well.
    7. If Application Descriptors are supported, the value of each attribute that appears in both, the manifest and Application Descriptor MUST have the identical value (with the exception of application suites with the MicroEdition-Profile attribute equal to "IMP-1.0", or "IMP-NG"). If not identical, the installation MUST fail. For IMP 1.0, and IMP-NG application suites, refer to Attribute Overrides in Application Descriptor.
    8. If an Application Descriptor (if supported) or Manifest of an Application Suite contains any instances of LIBlet-Dependency-<n> attributes, or if any LIBlet Application Descriptor (if supported) or Manifest of aLIBlet associated with the application suite contains any instances of MIDlet-Dependency-<n> attributes, then the installation of the application suite MUST fail.
    9. At installation time, the device MUST first verify there is sufficient disk space for persistent data using the data size specified in the JADs (if supported) of the application suite and the LIBlets, computed as:
      MIDlet-Data-Size + Σ (LIBlet-NonShared-Data-Size for distinct LIBlets) + Σ (LIBlet-Shared-Data-Size for distinct LIBlets if it is the first binding for the LIBlet on the device)
      The associated application suite and LIblets will only be transferred (if necessary) and installed if there is sufficient persistent storage space. In case of insufficient memory, the installation of the application suite MUST fail.
    10. If the application suite failed to be authenticated, the installation MUST fail.
    11. If circular dependencies are detected in the LIBlets that an application suite depends on, the device MUST reject the installation of such a binding.
    12. If a device imposes an upper limit on the number of LIBlet dependencies allowed for a single application suite, and if that upper limit is exceeded, the device MUST reject the installation of the application suite.
    13. If the application is not authorized for a permission as defined by the Requesting Permissions for an Application Suites section then installation must fail. The code of the application suite and the LIBlets it depends on MUST NOT be transferred (in case the respective provisioning mechanism requires a transfer).
    14. If the device detects a namespace collision between classes in the application suite and classes in the LIBlets it depends on, the device MUST fail the installation of such a binding.
  3. If the application is protected by OMA DRM and the device can not parse it, then the installation MUST fail.
  4. Each service requested by the application and its LIBlets in MIDlet-Dependency-<n> or LIBlet-Dependency-<n> attributes must be resolved. Each installed LIBlet that exports one of the requested services in its LIBlet-Services attribute must be considered a candidate service provider LIBlet.
  5. The dependent LIBlets found during installation or update MUST be bound to the application for use in the Execution Environment. The set of LIBlets remains bound to the application until it is explicitly updated. See Updating Applications to use Updated LIBlets for details.
  6. If a LIBlet that exports a service with a LIBlet-Services attribute does not contain valid service provider information for the service as defined in the Service Provider Packaging then installation MUST fail.
    LIBlets that export a service must be enabled when installed.
  7. If there are no problems that prevent installation, the applications contained in the application suite MUST be installed and made available for execution.
  8. The installation is complete when the application suite has been made available on the device, or an unrecoverable failure has occurred. In either case, the status MUST be reported as described in the Status Reports section in case the Provisioning mechanism allows the sending of status reports.

Update

An application suite update is defined as the operation of installing a specific application suite when that same application suite (either the same version or a different version) is already installed on the device. Devices MAY support the updating of application suites.

If an application suite update does not result in binding to the same Client as the original application suite, then installation MUST fail. Additionally, if an application suite update and the already installed application suite is not authorized by the same Client, then installation MUST fail. How it is decided, whether a Client is the same as another one, depends on the used Authentication Provider.

If the application suite dependencies change, the developer of the application suite needs to provide an updated JAD file containing the new LIBlet dependencies to be provisioned to the device. These dependencies MUST be resolved like in the initial installation of the application suite.

When updating a dependency declaration chain, the application suite declaring the dependency MUST increase its own version number, regardless of whether or not any code changes occurred to the application suite or LIBlet itself declaring the dependency.

For the case where an application suite is being updated only because of new LIBlet dependencies, the application suite developer will need to check that the required Permissions for new LIBlet dependencies are reflected in application manifest and/or JAD. The application suite will also need to be correctly authenticated.

In case the implementation supports the javax.microedition.rms package, the following has to be taken into account:

Updating Applications to Use Updated LIBlets

Under specific conditions a LIBlet installed for one application can be used to update other applications that use previous versions of the LIBlet. If allowed by the application and when the application is updated, the LIBlet will be included in the Execution Environment when the application is subsequently invoked.

The updated LIBlet can be rebound to an application by reevaluating all of the dependency information used during installation. Each dependency is evaluated and if the dependency expression has a version number that matches and there is no hash that must match exactly then the new LIBlet can be bound to the application. The entire Dependency Declaration Chain must be reprocessed including checking for circular dependency checking. The processing required is the same as re-installing the application but it should not require the transfer of the application JAD or JARs. If any errors are detected, then the update fails and the application must revert to the previously installed state.

The rebinding of LIBlets to applications can be performed immediately, can be deferred indefinitely or can be performed based on a profile setting in the implementation.

Invocation

If the start of an application has been triggered, the device MUST invoke the application with the Execution Environment .

Deletion

Application Suite Deletion

Devices MUST allow to delete application suites, with the exception of Persistent Application.

LIBlet Deletion

LIBlet deletion is usually done as part of the application suite deletion process, if a LIBlet has no other application suites depending on it. An implementation that has sufficient persistent storage MAY choose to retain LIBlets for possible later use, even after all application suites depending on the LIBlet have been deleted.

A LIBlet becomes unreferenced if there are no application suites installed on the device that specify a dependency on that particular LIBlet or if the LIBlet is not providing a service to or is not bound to any application. It is up to the implementation to determine when (if ever) it is appropriate to delete unreferenced LIBlets. For implementations that do retain unreferenced LIBlets, the AMS MAY provide a means to delete such LIBlets.

Some implementations MAY, according to policy, never allow unreferenced LIBlet automatic deletion, even if the LIBet's reference count drops to zero.

Status Reports

The success or failure of the installation, update, or deletion of an application suite is of interest to the service providing the application suite. The Application Descriptor - if supported - MAY include relevant application attributes for provisioning that specify URLs for status reporting. Those URLs MUST be used for reporting as specified below.

It has to be noted though, that not all Provisioning mechanisms are neccessarily able to send status reports. Also, if status reports are supported, not all statuses make sense for every Provisioning mechanism.

Unless an acknowledgement is requested with a MIDlet-Install-Notify attribute whose value includes the ack tag, the sending of any status report MUST be retried until the retry count reaches at least five (5), or it can be determined that there is no server response. The implementation MAY continue to retry the sending of the report.

The installed application suite MUST be made available for use even if no status reports are supported by the Provisioning mechanism, or - if supported - even if the sending of the installation status report fails, unless an acknowledgement is requested with the ack tag in the MIDlet-Install-Notify attribute. If the ack tag is present, the installation of the application suite MUST fail if a server response indicates that the installation has not succeeded. When an application suite is updated, any ack tag SHOULD be ignored, and the updated application suite be made available immediately.

If the application suite being installed has dependencies on some LIBlets, and status reports are supported, an installation status report MUST be sent to any LIBlet-Install-Notify URL specified by the LIBlet vendor.

Note that LIBlets are not deleted along with the application suite if there are other application suites that depend on them.

The following table contains the provisioning status codes and suggested status messages as well as a description of the situation that leads to the return of the specified status in case status reoports are supported.

Any status code different from 900 (Success) means that the installation has failed.

Table 3-2 : Install Status Codes and Messages

Status Code

Status Message

Situation described by this status

900

Success

Installation successful.

901

Insufficient Memory

There is insufficient memory to store the application suite on the device (if it is tranferred from outside the device) or in the area where active application suites reside (if a tranfer within the device is required.

Before the installation, the device MUST also first verify there is sufficient disk space for persistent data using the data size specified in the JADs (if supported) of the application suite and the LIBlets, computed as:
MIDlet-Data-Size + Σ(LIBlet-NonShared-Data-Size for distinct LIBlets) + Σ (LIBlet-Shared-Data-Size for distinct LIBlets if it is the first binding for the LIBlet on the device) If the available persistent storage space is insufficient for that, this status is also reported.

902

Cancelled

This status can only be reported when using a Provisioning mechanism that allows the cancellation of an application suite installation, e.g. by supported user interaction directly on the device, or by a technician at the source of the application suite to be installed.

903

Loss of Service

This staus can only be reported if a tranfer takes place within the provisioning process, this transfer takes place via a network, and the network service is lost during installation. It may be impossible though of course to deliver the status report due to the network service outage.

904

Application Suite size mismatch

This status can only be reported, if the Provisioning mechanism supports Application Descriptors, and the size of the application suite to be installed (e.g. the size of the JAR, if this is the format the application suite installation data is provided) does not match the size specified in the Application Descriptor.

905

Attribute mismatch

This status can only be reported, if the Provisioning mechanism supports Application Descriptors, and the mandatory attributes in the descriptor MIDlet-Name, MIDlet-Version, and MIDlet-Vendor do not match those in the manifest of the application suite.

Similarly, if the Provisioning mechanism supports Application Descriptors, and the mandatory attributes in the LIBlet descriptor LIBlet-Name, LIBlet-Version, and LIBlet-Vendor do not match those in the LIBlet JAR manifest.

Also, if Application Descriptors are supported, the value of each attribute that appears in both, the manifest and Application Descriptor MUST have the identical value, otherwise this status is reported as well (with the exception of application suites with the MicroEdition-Profile attribute equal to "IMP-1.0", or "IMP-NG").

In case of OTA Provisioning, the default variant of Provisioning in MEEP 8, this status is also reported if the OTA takes place via IP, and MIDlet-Required-IP-Version attribute is specified, and that IP version is not supported by the implementation.

906

Invalid Descriptor

This status is reported for the following situations:

  • if an Application Descriptor (if supported) or manifest of an Application Suite contains any instances of LIBlet-Dependency-<n> attributes, or if any LIBlet Application Descriptor (if supported) or manifest of a LIBlet associated with the application suite contains any instances of MIDlet-Dependency-<n> attributes
  • if Application Descriptors are supported by the Provisioning mechanism, and an Application Descriptor is not formatted according to the syntax defined in Application Attributes
  • if Application Descriptors are supported by the Provisioning mechanism, and an Application Descriptor does not contain all of the application attributes designated as mandatory by Appendix A MUST be present in the Application Descriptor
  • if Application Descriptors are supported by the Provisioning mechanism, and an Application Descriptor contains any application attributes that are allowed only in the Jar manifest (see Appendix A)

907

Invalid Installation Data

This status is reported for the following situations:

  • if the piece of software containing the installation data for the application suite or a LIBlet, e.g. a JAR, is not in the format expected by the Provisioning mechanism
  • if the manifest or any other file can not be extracted from the piece of software containing the application suite or a LIBlet, e.g. a JAR
  • if the manifest is not in the correct syntax, or if any of the required application attributes are missing in the manifest, or if the manifest contains any application attributes that are allowed only in the JAD (see Appendix A)
  • in case of OTA Provisioning, the default variant of Provisioning in MEEP 8, if the JAR is not available at the MIDlet-Jar-URL attribute in the descriptor, or if a dependent LIBlet is not already installed on the device and the JAR is not available at the LIBlet-Jar-URL attribute in the desriptor
  • if an Application Descriptor (if supported) or the application suite data are in a transport format that cannot be recognized by the implementation or cannot be converted into the required UTF-8 code.

908

Incompatible Configuration or Profile

The configuration or profile required by this application suite is not supported by the software stack available within the implementation on this device.

909

Application authentication failure

If the application suite or a LIBlet fails to be authenticated (see Authentication Providers for details.

910

Application authorization failure

This status is reported in the following situations:

  • if an application is not authorized for a permission as defined by the Requesting Permissions for an Application Suites section
  • if an application suite update does not result in binding to the same Client as the original application suite
  • if an application suite update and the already installed application suite is not authorized by the same Client

911

Push registration failure

If a static push registration fails for a reason other than not being authorized.

915

One or more missing dependency

The MIDlet-Dependency-<n> and LIBlet-Dependency-<n> attributes allow an application or a LIBlet to specify a dependency on an implementation of a standard optional API, a service, a proprietary API, or a LIBlet.

Any dependencies that cannot be satisfied by an implementation MUST be treated as an invalid packaging and causes this status to be reported.

916

Circular LIBlet dependency

If circular dependencies are detected in the LIBlets that an application suite depends on.

917

LIBlet namespace collision

If the device detects a namespace collision between classes in the application suite and classes in the LIBlets it depends on.

918

LIBlet dependencies limit exceeded

If a device imposes an upper limit on the number of LIBlet dependencies allowed for a single application suite, and if that upper limit is exceeded.

919

General failure

If installation of a valid application suite fails due to an unexpected internal error in the device, or if installation of an application suite fails due an error that cannot be reflected by one of the other status codes.

920

Service Configuration Error

If a LIBlet that exports a service with a LIBlet-Services attribute does not contain valid service provider information for the service as defined in the Service Provider Packaging.

953

Non-Acceptable Content

If the application is protected by OMA DRM and the device can not parse it.