otaspecification.html

J2ME MIDP2.0 final specification

        the state it was in before installation began.</p>
      <p class="Paragraph">
        If the MIDlet suite is already installed on the device, it
        SHOULD be treated as an update. See <a
        href="MIDletUpdate">MIDlet Suite Update</a> for additional
        information on how to handle an update.</li>
      <p class="Paragraph">
        To install a MIDlet suite, the AMS performs the following
        series of steps and checks and provides the user with feedback
        about the progress:</p>
      <ol>
	<li class="List1">
	  The device initiates the download of the MIDlet suite via
	  HTTP. If an Application Descriptor was first downloaded as
	  described in the <a href="#AppDiscovery">MIDlet suite
	  Discovery</a> section, the request for the MIDlet suite MUST
	  be for exactly the URL specified in the descriptor;
	  additional headers are unnecessary.</li>
	<li class="List1">
	  If the server or proxy responds to the request for the
	  MIDlet suite with a 401 (<em class="Code">Unauthorized</em>)
	  or 407 (<em class="Code">Proxy Authentication
	  Required</em>), the device SHOULD re-send the request with
	  the user-supplied credentials in an <em class="Code">
	  Authorization</em> or <em class="Code">
	  Proxy-Authorization</em> header field as specified in
	  RFC2617. The credentials SHOULD be provided by the user--for
	  example, a common mechanism would be to present a dialog to
	  the user to enter a user name and password. The device MUST
	  be able to support at least the Basic Authentication Scheme
	  as described in RFC2617.</li>
	<li class="List1">
	  The MIDlet suite and the headers that are received MUST be
	  checked to verify that the retrieved MIDlet suite is valid
	  and can be installed on the device. The user MUST be alerted
	  to at least the following problems that prevent
	  installation:</li>
          <ul>
	  <li class="Bullet1">
	    If there is insufficient memory to store the MIDlet suite
	    on the device, the device MUST return <a
	    href="#StatusCodes"><em class="Code">Status Code
	    901</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the JAR is not available at the
	    <em class="Code">MIDlet-Jar-URL</em> attribute
	    in the descriptor, the device MUST return
	    <a href="#StatusCodes"><em class="Code">Status Code
	    907</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the received JAR file size does not match the size
	    specified in the Application Descriptor, the device MUST
	    return <a href="#StatusCodes"><em class="Code">Status Code
	    904</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the manifest or any other file can not be extracted
	    from the JAR, the device MUST return
	    <a href="#StatusCodes"><em class="Code">Status Code
	    907</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the JAR manifest is not in the correct syntax, or if any
	    of the required attributes are missing in the JAR manifest,
	    the device MUST return
	    <a href="#StatusCodes"><em class="Code">Status Code
	    907</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the mandatory attributes in the descriptor "<em
	    class="Code">MIDlet-Name</em>", "<em
	    class="Code">MIDlet-Version</em>", and "<em
	    class="Code">MIDlet-Vendor</em>" do not match those
	    in the JAR manifest, the device MUST return <a
	    href="#StatusCodes"><em class="Code">Status Code
	    905</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the MIDlet suite is trusted, then the values in the
	    application descriptor for MIDlet-* attributes MUST be
	    identical to the corresponding attribute values in the
	    Manifest. If not, the device MUST return <a
	    href="#StatusCodes"><em class="Code">Status Code
	    905</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the application failed to be authenticated, the device
	    MUST return
	    <a href="#StatusCodes"><em class="Code">Status Code
	    909</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the application is an unsigned version of an installed
	    signed version of the same application, the device MUST
	    return <a href="#StatusCodes"><em class="Code">Status Code
	    910</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the application is not authorized for a permission
	    listed in the <em class="Code">MIDlet-Permissions</em> attribute,
	    the device MUST return
	    <a href="#StatusCodes"><em class="Code">Status
	    Code 910</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If a static push registration fails for a reason other than
	    not being authorized, the device MUST
	    return <a href="#StatusCodes"><em class="Code">Status
	    Code 911</em></a> in the Status Report.</li>
	  <li class="Bullet1">
	    If the network service is lost during installation, <a
	    href="#StatusCodes"><em class="Code">Status Code
	    903</em></a> SHOULD be used in a Status Report if possible
	    (it may be impossible to deliver the status report due to
	    the network-service outage).</li>
          </ul>
	<li class="List1">
	  Provided there are no problems that prevent installation,
	  the MIDlets contained in the MIDlet suite MUST be installed
	  and made available for execution by the user via the
	  device's MIDlet selection mechanism.</li>
	<li class="List1">
	  Installation is complete when the MIDlet 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 <a href="#StatusReport">Installation
	  Status Reports.</a>.</li>
      </ol>

    <a name="MIDletUpdate"></a>
    <h2 class="SectionTitle">MIDlet Suite Update</h2>
    <p class="Paragraph">
      A MIDlet suite update is defined as the operation of installing
      a specific MIDlet suite when that same MIDlet suite (either the
      same version or a different version) is already installed on the
      device. Devices MUST support the updating of MIDlet suites. In
      order to be meaningful to the user, the device MUST allow the
      user to obtain information about the MIDlet suite(s) on the
      device and determine which versions of software are
      installed. See <a href="#DevIdReqHdr">Device Identification and
      Request Headers.</a> for the attributes that apply to
      updates.</p>
    <p class="Paragraph">
      When a MIDlet suite update is started, the device MUST notify
      the user if the MIDlet suite is a newer, older, or the same
      version of an existing MIDlet suite and MUST get confirmation
      from the user before proceeding.</p>
    <p class="Paragraph">
      The RMS record stores of a MIDlet suite being updated MUST be
      managed as follows:</p>
    <ul>
      <li class="Bullet1">
	If the <a
	href="javadoc/javax/microedition/midlet/doc-files/PKITrust.html">
	cryptographic signer</a> of the new MIDlet suite and the
	original MIDlet suite are identical, then the RMS record
	stores MUST be retained and made available to the new MIDlet
	suite.</li>
      <li class="Bullet1">
	If the scheme, host, and path of the URL that the new
	Application Descriptor is downloaded from is identical to the
	scheme, host, and path of the URL the original Application
	Descriptor was downloaded from, then the RMS MUST be retained
	and made available to the new MIDlet suite.</li>
      <li class="Bullet1">
	If the scheme, host, and path of the URL that the new MIDlet
	suite is downloaded from is identical to the scheme, host, and
	path of the URL the original MIDlet suite was downloaded from,
	then the RMS MUST be retained and made available to the new
	MIDlet suite.</li>
      <li class="Bullet1">
	If the above statements are false, then the device MUST ask
	the user whether the data from the original MIDlet suite
	should be retained and made available to the new MIDlet
	suite.</li>
    </ul>
    <p class="Paragraph">
      In all cases, an unsigned MIDlet MUST NOT be allowed to update a
      signed MIDlet suite. The format, contents and versioning of the
      record stores is the responsibility of the MIDlet suite. The
      user-granted permissions given to the original MIDlet suite
      SHOULD also be given to the new MIDlet suite, if they are in the
      security domain of the new MIDlet suite.</p>

    <h2 class="SectionTitle">MIDlet Suite Execution</h2>
    <p class="Paragraph">
      When the user selects a MIDlet to be run, the device MUST invoke
      the MIDlet with the CLDC and MIDP classes required by the MIDP
      specification. If multiple MIDlets are present, the user
      interface MUST allow the user to select each one for
      execution.</p>

    <h2 class="SectionTitle">MIDlet Suite Removal</h2>
    <p class="Paragraph">
      Devices MUST allow users to remove MIDlet suites. When a MIDlet
      suite is to be removed from the device, the user SHOULD be
      prompted to confirm that the MIDlet suite may be removed. The
      device SHOULD warn the user of any special circumstances that
      arise during the deletion of the MIDlet suite. For example, the
      MIDlet suite MAY contain multiple MIDlets, and the user SHOULD
      be made aware that all of the MIDlets and associated RMS record
      stores are being removed.</p>
    <p class="Paragraph">
      If the Application Descriptor includes the attribute
      MIDlet-Delete-Confirm, its value SHOULD be included in the
      prompt. This will allow the MIDlet suite provider to highlight
      any specific conditions that might arise if the MIDlet suite
      were to be removed.</p>

    <a name="StatusReport"></a>
    <h2 class="SectionTitle">Installation/Deletion Status Reports</h2>
    <p class="Paragraph">
      The success or failure of the installation, upgrade, or deletion
      of a MIDlet suite is of interest to the service providing the
      MIDlet suite. The service MAY specify URLs in the Application
      Descriptor that MUST be used to report installation and deletion
      status. See <a href="#AdditionalAttributes">Additional
      Descriptor Attributes</a> for more information. If the device
      cannot send the installation status report, the requested action
      MUST still be completed. For example, if the device cannot send
      the installation status report to the MIDlet-Install-Notify URL,
      the MIDlet suite MUST still be enabled, and the user MUST be
      allowed to use it. Likewise if the device cannot send the
      deletion status report to the MIDlet-Delete-Notify URL, the
      MIDlet suite MUST still be deleted.</p>
    <p class="Paragraph">
      The operation status is reported by means of an HTTP POST to the
      URL specified in the <em class="Code">MIDlet-Install-Notify</em>
      attribute for installations, or the <em
      class="Code">MIDlet-Delete-Notify</em> attribute for
      deletions. The only protocol that MUST be supported is "<em
      class="Code">http://</em>". Other protocols MAY be ignored
      by the device.</p>
    <p class="Paragraph">
      The content of the body of the POST request MUST include a
      status code and status message on the first line. See <A
      HREF="#StatusCodes">Status Codes and Message</a> for list of
      valid codes and status messages.</p>
    <p class="Paragraph">
      In the case of a deletion status report, the notification is
      sent only when the MIDlet is deleted; <a href="#StatusCodes"><em
      class="Code">Status Code 912</em></a> MUST be sent, notifying that
      the deletion occurred.</p>
    <p class="Paragraph">
      In response to a status report, the server MUST reply with
      a "<em class="Code">200 OK</em>" response. No content
      SHOULD be returned to the device and, if any is sent, it MUST be
      ignored. If a response is received the request SHOULD NOT be
      retried. Contrary to the MIDP 1.0 OTA Recommended Practice, the
      server MUST NOT include a <em class="Code">Set-Cookie</em>
      header with the attribute <em class="Code">Max-Age=0</em> to
      request that the <em class="Code">cookie</em> be discarded. If
      such an attribute is received, the device MUST ignore it. As an
      example, please see <a href="#InstStatExample">Example: Install
      Status via HTTP Post Request</a>.</p>
    <p class="Paragraph">
      For installations, if the status report cannot be sent, or if
      the server reply is not received, the installation status report
      MAY be sent again (as described above) each time a MIDlet in
      this suite is executed and the device has data network
      connectivity. This will improve the likelihood of the status
      report being successfully sent. The number of retries attempted
      SHOULD be kept small since each one may result in a charge to
      the user's bill. The MIDlet suite MUST be made available for
      use, whether or not the installation status report has been
      successfully sent and the acknowledgement have been
      received.</p>
    <p class="Paragraph">
      For deletions, an attempt to send the status report MUST be made
      the next time either an OTA installation is performed or an
      installation status report is being sent. This will improve the
      likelihood of the status report being successfully sent and will
      minimize confusion by the user when they see network
      activity. If the status report cannot be sent, or if the server
      reply is not received, the deletion status report MAY be sent
      again (as described above) each time an OTA installation
      installation is performed or an installation status report is
      being sent. The number of retries attempted SHOULD be kept small
      since each one may result in a charge to the user's bill. The
      MIDlet suite MUST be removed from memory, whether or not the
      installation status report has been successfully sent and the
      acknowledgement have been received.</p>

    <a name="StatusCodes"></a>
    <br><b>Install Status Codes and Message</b>
      <table class="Table" border="1" cellpadding="3">
      <tr>
	<th rowspan="1" colspan="1">
	  <p class="TableHead">
	    Status Code</p>