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 mechanism 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 or LIBlets 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 application suites and LIBlets. 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 all provisioning mechanisms, 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 or HTTPS protocol (whatever is supported) 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 or 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 suite and LIBlet discovery is the process by which an application suite or LIBlet 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 or LIBlet itself. Discovery and installation of application suites and LIBlets, if supported, MUST follow the following high-level scheme:
When an application suite or LIBlet is provisioned, all files that comprise the applications or LIBlet are transferred to the device for installation. In addition to the application suite or LIBlet JAR file, one or more dependency 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 an application suite or LIBlet and its dependencies.
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.
If Application Descriptors are supported, the Application Suite JAD file lists its 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 the application suite and dependency LIBlets, MUST be transferred first before any of the application suite or dependency LIBlet JAR files 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.
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 Descriptor contains any application attributes that are allowed only in the Jar manifest (see Appendix A), then the provisioning MUST fail.
LIBlet provisioning can be performed as part of application provisioning (for LIBlets an application suites is depending on), or as a standalone provisioning.
For provisioning of a LIBlet during the provisioning of an application suite, if the required version of a LIBlet is already installed on the device, i.e. if a LIBlet with the same name, vendor and version is already available, then the LIBlet MUST NOT be provisioned (and later installed) again, replacing the exiting one.
For a standalone installation of a LIBlet though, if the same version of the LIBlet is already installed on the device, i.e. if a LIBlet with the same name, vendor and version is already available, then the provisioning is interpreted as part of a LIBlet Update, so it will be provisioned and later replace the existing one.
If Application Descriptors are supported, the LIBlet JAD file lists its 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 dependent LIBlet and dependency LIBlets, MUST be transferred first before any of the 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. This is true independent on whether the dependent LIBlet is provisioned as part of an application suite provisioning or standalone.
Application installation is the process by which any transfer of an application suite as far as required by the provisioning 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.
Installation of LIBlets the application suite is depending on is done as part of the application suite installation process. It only takes place, if the LIBlet of the required version is not yet installed on the device. In this case, 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 Application Suite 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 one of the dependency LIBlet descriptors
LIBlet-Name
,
LIBlet-Version
, and
LIBlet-Vendor
do not match
those in the respective 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 a LIBlet associated with the
application suite contains any instances of
MIDlet-Dependency-
<n>
attributes, then the installation of the application suite
MUST fail.
LIBlet-Name
attribute, then the installation of the application suite
MUST fail.
MIDlet-Dependency-
<n>
attribute, or as required by another LIBlet using the
LIBlet-Dependency-
<n>
attribute, is not already installed on the device, it MUST be
downloaded from the URL as specified in the
MIDlet-Dependency-JAD-URL
<n> or
LIBlet-Dependency-JAD-URL
<n>
attribute. If the LIBlet cannot be found there or if it has
not the required version, then the installation of the
application suite or dependent LIBlet 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.As mentioned before, LIBlets may be installed as part of an application suite installation, if they are among those, the application suite has defined a dependency upon. This kind of LIBlet installation is described in the Application Suite Installation section. This section handles the standalone installation of LIBlets. Standalone installation of LIBlets is the process by which any transfer of a LIBlet as far as required by the provisioning mechanism is performed and LIBlets are made available for usage by application suites. LIBlet installation is optional in MEEP 8, but MUST be supported if Provisioning and LIBlets are supported.
If the LIBlet to be installed depends on one or more LIBlets, implementation MAY make the user aware of all LIBlets the LIBlet depends on. The means by which LIBlet dependencies are presented to the user are implementation specific.
Installation of LIBlets the LIBlet to be installed is depending on is done as part of the requiring LIBlet installation process. It only takes place, if the LIBlet of the required version is not yet installed on the device. In this case, since other applications or LIBlets 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 LIBlet, the implementation MAY present to the user security information related to this LIBlet.
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 same version of the LIBlet to be explicitly installed is already installed on the device, it SHOULD be treated as an update. See the LIBlet Update section for additional information on how to handle an update.
To explicitly install a LIBlet, 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):
LIBlet-Jar-Size
+
Σ(LIBlet-Jar-Size
for distinct LIBlets)
LIBlet-Name
,
LIBlet-Version
, and
LIBlet-Vendor
do not match
those in the manifest of the LIBlet to be installed, the
installation MUST fail. Similarly, if those mandatory attributes
in one of the dependency LIBlet descriptors do not match
those in the respective LIBlet manifest, the installation of
the LIBlet to be explicitly installed MUST fail as well.
MIDlet-Dependency-
<n>
attributes, then the installation of the LIBlet MUST fail.
MIDlet-Name
attribute, then the installation of the LIBlet MUST fail.
LIBlet-Dependency-
<n>
attribute, is not already installed on the device, it MUST be
downloaded from the URL as specified in the
LIBlet-Dependency-JAD-URL
<n>
attribute. If the LIBlet cannot be found there or if it has
not the required version, then the installation of the
application suite MUST fail.
LIBlet-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)
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 there is an application
suite with same MIDlet-Name
and
MIDlet-Vendor
attributes already installed
on the device. Devices MAY support the updating of application suites.
If application suite update is not supported or cannot be accomplished
(e.g., because an application suite is preinstalled), then application
suite installation fails with status code 913 "Update not supported
or failed".
If an application is updated while running, it has to be stopped when the installation of the updated version begins. As this is not a security relevant incident, a soft deletion is sufficient.
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 Authentication Provider used.
If the application suite dependencies change, the developer of the application suite needs to provide an updated JAD file containing the new 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:
A LIBlet update is defined as the operation of
explicitly installing a specific LIBlet when there is a LIBlet with same
LIBlet-Name
,
LIBlet-Vendor
and
LIBlet-Version
attributes already installed
on the device. Devices MAY support the updating of LIBlets.
If LIBlet update is not supported or cannot be accomplished for some reason,
then LIBlet installation fails with status code 913 "Update not supported
or failed".
If a LIBlet is updated while one or more than one applications using it are running, all those applications have to be stopped when the updating installation of the LIBlet begins. As this is not a security relevant incident, a soft deletion is sufficient.
If a LIBlet update does not result in binding to the same Client as the original LIBlet, then the installation MUST fail. If the original LIBlet has been bound to more than one Client, and the Clients to which the original LIBlet has been bound to are not all among those the updated LIBlet is bound to, then the installation MUST fail. Additionally, if a LIBlet update and the already installed LIBlet 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 Authentication Provider used.
If the LIBlet dependencies change, the developer of the LIBlet needs to provide an updated JAD file containing the new dependencies to be provisioned to the device. These dependencies MUST be resolved like in the initial installation of the LIBlet.
As installed application suites and LIBlets depend on an installed LIBlet, the application developer or the authority performing the update has to make clear that the updated version does not reduce functionality of the original LIBlet (while an extension of functionality is no problem). The provisioning algorithm has no possibility to check this at all. Therefore an update of a LIBlet can cause using applications not to work properly any more or even crash if the provider of the update does not consider this responsibility.
Under specific conditions a LIBlet installed for one application or LIBlet can be used to update other applications and LIBlets that use previous versions of the LIBlet. If allowed by the application or LIBlet and when the application or LIBlet is updated, the LIBlet will be included in the Execution Environment when the application (or for a LIBlet: an application using this LIBlet) is subsequently invoked.
The updated LIBlet can be rebound to an application or LIBlet 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 then the new LIBlet can be bound to the application or LIBlet. 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 or LIBlet but it should not require the transfer of the application or LIBlet JAD or JARs. If any errors are detected, then the update fails and the application or LIBlet must revert to the previously installed state.
The rebinding of LIBlets to applications or LIBlets 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 .
If Provisioning is supported, devices MUST allow to delete application suites, with the exception of Persistent Application. If the deletion is not caused by a security relevant incident like blacklisting of the application or of its Client, a soft deletion is appropriate, otherwise a hard one. Before an application can be deleted, it MUST be always stopped.
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.
To detemine the behavior in case of the installation or update of an application suite depending on LIBlets can be very complex, because it requires to consider aspects of versioning, security etc. being described in several chapters of the specification.
This section therefore describes some popular use cases and the specification conformant behavior of an implementation in order to simplify orientation for creaters and users of MEEP 8 implementations.
All use case described in this section assume that the implementation supports provisioning of application suites, LIBlets and a security framework, all being optional in MEEP 8.
The success or failure of the installation, update, or deletion of an application suite or LIBlet is of interest to the service providing the application suite or LIBlet. 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 necessarily able to send status reports. Also, if status reports are supported, not all statuses make sense for every Provisioning mechanism.
If there exists a server, and status reports are supported and sent
to this server, the server MAY reply with a 2xx
response
(typically 200 OK
). MEEP implementations won't wait
for this answer though.
Unless an acknowledgement is requested with a MIDlet-Install-Notify
or LIBlet-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 or LIBlet 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
or
LIBlet-Install-Notify
attribute. If the ack
tag is present, the installation
of the application suite or LIBlet MUST fail if a server response
indicates that the installation has not succeeded. When an
application suite or LIBlet is updated, any ack
tag
SHOULD be ignored, and the updated application suite or LIBlet be
made available immediately.
If the application suite or LIBlet being installed has dependencies
on some dependency LIBlets, and status reports are supported, an
installation status report MUST be sent to any
LIBlet-Install-Notify
URL specified
by the dependency LIBlet vendor.
If status reports are principally supported, but a deletion status report cannot be sent for some reason (device is offline, no network being configured etc.), the deletion MUST take place nevertheless.
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 reports 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 or LIBlet on the device (if it is transferred from outside the device) or in the area where active application suites and LIBlets reside (if a transfer 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 or LIBlet
and the dependency LIBlets, computed as:
|
902 |
Cancelled |
This status can only be reported when using a Provisioning mechanism that allows the cancellation of an application suite or LIBlet installation, e.g. by supported user interaction directly on the device, or by a technician at the source of the application suite or LIBlet to be installed. |
903 |
Loss of Service |
This status can only be reported if a transfer 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 or LIBlet to be installed (e.g. the size of the JAR, if this is the format the application suite or LIBlet 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 one of the dependency
LIBlets' 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 any application suite 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 or LIBlet 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. Also if an application suite or LIBlet from a trusted Client tries to define a (direct or indirect) dependency from a LIBlet not coming from a trusted Client (if the "vendor" part of the Dependency attribute does not refer to a trusted Client). |
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. |
912 |
Deletion notification |
Sent if deletion of an application suite occured. |
913 |
Update not supported or failed |
Sent if an attempt was made to update an existing application suite
on the device by trying to install an application suite with same
|
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 or LIBlet depends on. |
917 |
LIBlet namespace collision |
If the device detects a namespace collision between classes in the application suite or LIBlet 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 or LIBlet, and if that upper limit is exceeded. |
919 |
General failure |
If installation of a valid application suite or LIBlet fails due to an unexpected internal error in the device, or if installation of an application suite or LIBlet 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 an application is protected by OMA DRM and the device cannot parse it. |
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved.