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.
A MEEP 8 implementation supporting provisioning:
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.
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:
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.
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:
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.
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 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.
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):
MIDlet-Jar-Size
+
Σ(LIBlet-Jar-Size
for distinct LIBlets)
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.
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.
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.
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)
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.
LIBlet-Services
attribute does not contain valid service provider
information for the service as defined in the
Service Provider Packaging
then installation MUST fail.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:
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.
If the start of an application has been triggered, the device MUST invoke the application with the Execution Environment .
Devices MUST allow to delete application suites, with the exception of Persistent Application.
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.
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: |
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
Similarly, if the Provisioning mechanism supports Application
Descriptors, and the mandatory attributes in the LIBlet descriptor
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
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
|
906 |
Invalid Descriptor |
This status is reported for the following situations:
|
907 |
Invalid Installation Data |
This status is reported for the following situations:
|
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:
|
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 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 |
953 |
Non-Acceptable Content |
If the application is protected by OMA DRM and the device can not parse it. |